Common Controls

General Introduction to the Common Controls

The updated common controls delivered in Whistler are a set of windows that are implemented by the common control library, which is a dynamic-link library (DLL) included with the Microsoft® Windows® operating system. Like other control windows, a common control is a child window that an application uses in conjunction with another window to perform I/O tasks.

  • Using Common Controls
  • Common Control Updates in Internet Explorer
  • Common Control Reference

Using Common Controls

Most common controls belong to a window class defined in the common control DLL. The window class and the corresponding window procedure define the properties, appearance, and behavior of the control. To ensure that the common control DLL is loaded, include the InitCommonControlsEx function in your application. You create a common control by specifying the name of the window class when calling the CreateWindowEx function or by specifying the appropriate class name in a dialog box template.

DLL Versions

All 32-bit versions of Windows include a common controls DLL, Comctl32.dll. However, this DLL has been updated several times since it was first introduced. Each successive version supports the features and application programming interface (API) interface of earlier versions. However, each new version also contains a number of new features and a correspondingly larger API. Applications must be aware of which version of Comctl32.dll is installed on a system, and only use the features and API that the DLL supports.

Because new versions of the common controls were distributed with Internet Explorer, the version of Commctl32.dll that is present is commonly different from the the version that was shipped with the operating system. It may actually be several versions more recent. It is thus not enough for your application to know which operating system it is running on. It must directly determine which version of Comctl32.dll is present. For a detailed discussion of common controls versions and how to determine which version of Comctl32.dll is installed, see Shell and Common Controls Versions.

Structure sizes for different common control versions

Ongoing enhancements to common controls have resulted in the need to extend many of the structures. For this reason, the size of the structures has changed between different versions of Commctrl.h. Because most of the common control structures take a structure size as one of the parameters, a message or function can fail if the size is not recognized. To remedy this, structure size constants have been defined to aid in targeting different version of Comctl32.dll. The following list defines the new structure size constants.

HDITEM_V1_SIZE | The size of the HDITEM structure in version 4.00.
LVCOLUMN_V1_SIZE | The size of the LVCOLUMN structure in version 4.00.
LVHITTESTINFO_V1_SIZE | The size of the LVHITTESTINFO structure in version 4.00.
LVITEM_V1_SIZE | The size of the LVITEM structure in version 4.00.
NMLVCUSTOMDRAW_V3_SIZE | The size of the NMLVCUSTOMDRAW structure in version 4.70.
NMTTDISPINFO_V1_SIZE | The size of the NMTTDISPINFO structure in version 4.00.
NMTVCUSTOMDRAW_V3_SIZE | The size of the NMTVCUSTOMDRAW structure in version 4.70.
PROPSHEETHEADER_V1_SIZE | The size of the PROPSHEETHEADER structure in version 4.00.
PROPSHEETPAGE_V1_SIZE | The size of the PROPSHEETPAGE structure in version 4.00.
REBARBANDINFO_V3_SIZE | The size of the REBARBANDINFO structure in version 4.70.
TTTOOLINFO_V1_SIZE | The size of the TOOLINFO structure in version 4.00.
TVINSERTSTRUCT_V1_SIZE | The size of the TVINSERTSTRUCT structure in version 4.00.

Common Control Styles

Each type of common control has a set of control styles that you can use to vary the appearance and behavior of the control. The common control library also includes a set of control styles that apply to two or more types of common controls. The common control styles are described in the Common Control Styles section.

Common Control Messages

Because common controls are windows, an application can manipulate them by using messages, such as WM_GETFONT or WM_SETTEXT. In addition, the window class of each common control supports a set of control-specific messages that an application can use to manipulate the control. An application can use any of the message sending or posting functions to pass messages to the control. Some common controls also have a set of macros that an application can use instead of the sending or posting functions. The macros are typically easier to use than the functions.

When a change is made to the system color settings, Windows sends a WM_SYSCOLORCHANGE message to all top-level windows. Your top-level window must forward the WM_SYSCOLORCHANGE message to its common controls; otherwise, the controls will not be notified of the color change. Forwarding the message ensures that the colors used by your common controls are consistent with those used by other user interface objects. For example, a toolbar control uses the "3D Objects" color to draw its buttons. If the user changes the 3D Objects color but the WM_SYSCOLORCHANGE message is not forwarded to the toolbar, the toolbar buttons will remain in their original color (or even change to a combination of old and new colors) while the color of other buttons in the system changes.

Common Control Notification Messages

Common controls are child windows that send notification messages to the parent window when events, such as input from the user, occur in the control. The application relies on these notification messages to determine what action the user wants it to take. Except for trackbars, which use the WM_HSCROLL and WM_VSCROLL messages to notify their parent of changes, common controls send notification messages as WM_NOTIFY messages. The lParam parameter of WM_NOTIFY is either the address of an NMHDR structure or the address of a larger structure that includes NMHDR as its first member. The structure contains the notification code and identifies the common control that sent the notification message. The meaning of the remaining structure members, if any, varies depending on the notification code.

Note Not all controls will send WM_NOTIFY messages. In particular, the standard Windows controls (edit controls, combo boxes, list boxes, buttons, scroll bars, and static controls) do not send WM_NOTIFY messages. Consult the documentation for the control to determine if it will send any WM_NOTIFY messages and, if it does, which notification codes it will send.

Each type of common control has a corresponding set of notification codes. The common control library also provides notification codes that can be sent by more than one type of common control. See the documentation for the control of interest to determine which notification codes it will send and what format they take.

Unicode Support

For versions 5.80 and later of comctl32.dll, common controls notifications support both ANSI and UNICODE formats on Windows 95 systems or later. The system determines which format to use by sending your window a WM_NOTIFYFORMAT message. To specify a format, return NFR_ANSI for ANSI notifications or NFR_UNICODE for Unicode notifications. If you do not handle this message, the system calls IsWindowUnicode to determine the format. Since Windows 95 and Windows 98 always return FALSE to this function call, they use ANSI notifications by default.

Common Control Updates in Internet Explorer

Common controls in Microsoft® Internet Explorer support the following new features.

Common Control Initialization
The common controls are now initialized with the InitCommonControlsEx function. This function enables you to specify which controls should be initialized for your application, rather than initialize all of the controls. The InitCommonControls function is still supported, but new applications should use InitCommonControlsEx.
New Common Control Styles
There are four new common control styles defined. These are CCS_LEFT, CCS_RIGHT, CCS_VERT, and CCS_NOMOVEX. For more information, see Common Control Styles.


Updated Common Controls

This is preliminary documentation and is subject to change.

The updated common controls delivered in Whistler are a set of windows that are implemented by the ComCtl32.dll version 6. This dynamic-link library (DLL) is included with the the Microsoft product code-named Whistler pre-release of the Microsoft® Windows® operating system.

The new Whistler common controls are based on the Windows 2000 common controls and Windows user controls. These controls have been modified for the Whistler pre-release, for the following reasons.

  • To improve the look and feel of the Windows controls
  • To fix existing problems with Windows controls
  • To allow innovation in Windows controls while providing compatibility with existing applications

This document includes the following topics.

  • What's New in the Whistler Controls
  • Common Controls
  • Enhancements to the List-View Control
  • Using the Controls
  • Requirements
  • Related Topics

What's New in the Whistler Controls

The new common controls are designed to display the new visual style of Windows and to be aware of the current system theme. The system theme is the set of user interface choices provided by the operating system and selected by the user. Common controls respond to a change of the system theme, altering their look and appearance. The following example shows how four possible sets of themed buttons might look.

Common controls use system theme information to render their visual states appropriately.

It is likely that the business and consumer releases of Whistler will use different system themes to distinguish the releases. By using the themed common controls, your application will provide a look that is consistent with the theme for each release.

Developers of custom controls can use the functions exposed by the theme manager, and provided in the Theme Reference, to determine the current system theme and draw the control user interface elements.

Common Controls

The following controls are included in the common control library.

New common controls

  • Overview of SysLink Controls

Updated common controls

  • Animation Control Online link
  • Month Calendar Control Online link
  • ComboBoxEx Control Online link
  • Date and Time Picker Control Online link
  • Drag List Box Online link
  • Flat Scroll Bar Online link
  • Header Control Online link
  • Hotkey Control Online link
  • Image List Online link
  • IP Address Control Online link
  • List View Control Online link
  • Pager Control Online link
  • Progress Bar Control Online link
  • Property Sheet Control Online link
  • Rebar Control Online link
  • Status Bar Online link
  • Tab Control Online link
  • Toolbar Control Online link
  • Tooltip Control Online link
  • Trackbar Control Online link
  • Tree View Control Online link
  • Up-Down Control Online link

Updated User Controls

  • Push Button Online link
  • Check Box Online link
  • Combo Box Online link
  • List Box Online link
  • Radio Button Online link
  • Scroll Bar Online link

The common controls library contains controls that provide the same functionality as the Windows common controls, documented in the Common Controls Overview Online link, and the Windows user controls that are documented in the Windows User Interface Online link.

Enhancements to the List-View Control

The list-view control provides new grouping, tiling, and insertion mark features. These new features are documented in the Theme Reference.

Grouping allows a user to arrange lists into groups of items that are visually divided on the page using a horizontal divider and a group title. Grouping items makes it simpler to scan large lists for information. Groups can be created based on item properties, attributes, or other characteristics.

Tiling is a new view that displays an icon and several lines of text. Tile view provides a better balance between visual and textual information. The tile view uses a 32 x 32 icon and several lines of text, as illustrated below.

Insertion marks are used to show users where dragged items will be placed. Insertion marks are currently displayed when the user drags an item into the Start menu or Quick Launch bar. The insertion point has been introduced for lists that are autoarranged. When a user drags a file to a point between two other files, the insertion point shows the expected location where the file will move.

Using the Controls

The common controls include support to enable your application to use these controls without rebuilding. Side-by-side component technology enables your application to load the specific version of a DLL at run time through use of a manifest. Because the manifest specifies the exact environment in which an application will run, multiple versions of a DLL can exist on one computer. See Manifest Files in the Microsoft® Platform Software Development Kit (SDK) for information on how to create a manifest.

Requirements

The common control library is not linked directly with an application and, therefore, requires side-by-side component support on any computer on which the application will run. ComCtl32.dll, version 6, requires a system for Unicode with side-by-side component support and cannot be used on previous Windows operating systems.

An application that is to run on other Windows operating systems cannot rely on the new common control library being present and should not use features that are available only in ComCtl32.dll, version 6.

The new common control library provides better validation of arguments. Applications should not rely on previous behavior.

It is the software vendor's responsibility to test with a particular manifest. Microsoft® will continue to resolve issues in future versions of this control library. For this reason, if your application relies on a previous behavior, you might need to modify your application before updating the manifest.

Related Topics

  • Theme Reference


Common Controls FAQ

Common Controls FAQ

This FAQ provides answers to some questions that are commonly asked about the common controls.

How do I create a wizard?

See Creating Wizards.

When you hold the mouse pointer over a partially concealed folder name in the Microsoft® Windows® Explorer tree view, a ToolTip appears that displays the entire name. How do I create one of these in-place ToolTips?

See In-Place ToolTips.

How do I create a toolbar that the user can customize?

See Customizing Toolbars.

How do I embed a control, such an edit box, in a toolbar control?

See Embedding Nonbutton Controls in Toolbars.

How do I create the kind of toolbar that Microsoft® Internet Explorer uses?

See Creating an Internet Explorer-style Toolbar.

How do I create the kind of menu bar that Microsoft® Internet Explorer uses?

See Creating an Internet Explorer-style Menu Bar.

How do I handle the common controls if my application needs to be localized?

See Localization Support for the Common Controls.


Creating an Internet Explorer-style Toolbar

One of the key user-interface features of Microsoft® Internet Explorer is the toolbar. It not only gives users access to a wide array of features, it also allows users to customize its layout to suit their personal preferences. The following illustration shows the Internet Explorer toolbar, and highlights some of the the key features.

Internet Explorer Toolbar

This toolbar essentially consists of a rebar control with four bands: three toolbars and a menu bar. Because it is implemented with the common controls API, developers can create toolbars with any or all of its features. This document discusses the essential features of the Internet Explorer toolbar and how to implement them in your application.

  • The Rebar Control
  • The Toolbars
  • Creating an Internet Explorer-style Menu Bar

The Rebar Control

The underlying structure of the Internet Explorer toolbar is provided by a rebar control. This control provides a way for users to customize the arrangement of a collection of tools. Each rebar contains one or more bands, which are typically long, narrow rectangles that contain a child window, commonly a toolbar control.

The rebar control displays its bands in a rectangular area, typically at the top of the window. This rectangle is subdivided into one or more strips that are the height of a band. Each band can be on a separate strip, or multiple bands can be placed on the same strip.

A rebar control provides users with two ways to arrange their tools:

  • Each band usually has a gripper at its left-hand edge. Grippers are used when two or more bands on a single strip exceed the width of the window. By dragging the gripper to the left or right, users can control how much space is allocated to each band.
  • Users can move the bands within the rebar's display rectangle by dragging and dropping. The rebar control then changes the display to accommodate the new arrangement of bands. If all the bands are removed from a strip, the height of the rebar will be reduced, enlarging the viewing area.
  • An application can add or remove bands as needed. Typically, applications enable users to select which bands they want to have displayed through the View menu or a shortcut menu.

If the combined width of the bands on a strip exceeds the width of the window, the rebar control will adjust their widths as needed. Some of the tools might be covered by the adjacent band.

Version 5.80 of the common controls provides a way to make tools that have been covered by another band accessible to the user. If you set the RBBS_USECHEVRON flag in the fStyle member of the band's REBARBANDINFO structure, a chevron will be displayed for toolbars that have been covered. When a user clicks the chevron, a menu is displayed that allows him or her to use the hidden tools. The following illustration from Internet Explorer 5 shows the menu that is displayed when part of the standard toolbar is covered by the address bar.

Rebar chevron drop-down menu

Since each band contains a control, you can provide additional flexibility through the control's API. For example, you can implement toolbar customization to enable the user to add, move, or delete buttons on a toolbar.

Implementing the Rebar Control

Most of the features of the Internet Explorer toolbar are actually implemented in the individual bands. The implementation of the rebar control itself is relatively straightforward:

  1. Create the rebar control with CreateWindowEx. Set dwExStyle to WS_EX_TOOLWINDOW and lpClassName to REBARCLASSNAME. Internet Explorer uses the following window styles:

    • RBS_BANDBORDERS
    • RBS_DBLCLKTOGGLE
    • RBS_REGISTERDROP
    • RBS_VARHEIGHT
    • CCS_NODIVIDER
    • CCS_NOPARENTALIGN
    • WS_BORDER
    • WS_CHILD
    • WS_CLIPCHILDREN
    • WS_CLIPSIBLINGS
    • WS_VISIBLE

    Set the other parameters as appropriate for your application.

  2. Create a control with CreateWindowEx or a specialized control creation function such as CreateToolbarEx.
  3. Initialize a band for the control by filling in the members of REBARBANDINFO. Include the RBBS_USECHEVRON style with the fStyle member to enable chevrons.
  4. Add the band to the rebar control with an RB_INSERTBAND message.
  5. Repeat steps 2-4 for the remaining bands.
  6. Implement handlers for the rebar notifications. In particular, you will need to handle RBN_CHEVRONPUSHED to display a dropdown menu when a chevron is clicked. For further information, see Handling Chevrons.

The grippers are included by default. To omit the gripper for a band, set the RBBS_NOGRIPPER flag in the fStyle member of the band's REBARBANDINFO structure. For further information on implementing rebar controls, see Rebar Controls.

Handling Chevrons

When a user clicks a chevron, the rebar control sends your application an RBN_CHEVRONPUSHED notification. The NMREBARCHEVRON structure that is passed with the notification contains the band's identifier and a RECT structure with the rectangle occupied by the chevron. Your handler must determine which buttons are hidden and display the associated commands on a pop-up menu.

The following procedure outlines how to handle an RBN_CHEVRONPUSHED notification:

  1. Retrieve the current bounding rectangle for the selected band by sending the rebar control an RB_GETRECT message.
  2. Retrieve the total number of buttons by sending the band's toolbar control a TB_BUTTONCOUNT message.
  3. Starting from the leftmost button, retrieve the button's bounding rectangle by sending the toolbar control a TB_GETITEMRECT message.
  4. Pass the band and button rectangles to IntersectRect. This function will return a RECT structure that corresponds to the visible portion of the button.
  5. Pass the button rectangle and the rectangle for the visible portion of the button to EqualRect.
  6. If EqualRect returns TRUE, the entire button is visible. Repeat steps 3-5 for the next button on the toolbar. If EqualRect returns FALSE, the button is at least partially hidden and all remaining buttons will be completely hidden. Continue to the next step.
  7. Create a pop-up menu with items for each of the hidden buttons.
  8. Display the pop-up menu with TrackPopupMenu. Use the chevron rectangle passed with the RBN_CHEVRONPUSHED notification to position the menu. The menu should be immediately below the chevron, with the left edges aligned.
  9. Handle the menu commands.

The Toolbars

Most of the complexity of the Internet Explorer toolbar lies in the implementation of controls that make up the rebar bands. Internet Explorer commonly displays four bands:

  • The menu bar
  • The standard toolbar
  • The links toolbar
  • The address toolbar

All of these bands, including the menu bar, actually hold toolbar controls. This section discusses the implementation of the standard and links toolbars. The menu bar is somewhat more complicated and is discussed separately in Creating an Internet Explorer-style Menu Bar.

The basic procedures for implementing toolbar controls are discussed in Toolbar Controls. This section focuses on some of the newer toolbar features that are used by Internet Explorer to increase the usability of the control.

  • Drop-down buttons
  • List-style buttons
  • Chevrons
  • Hot-tracking

Drop-down Buttons

Drop-down buttons support multiple commands. When the user clicks a drop-down button, the button displays a pop-up menu instead of launching a command. The user launches a command by selecting it from the menu. The following illustration shows a drop-down button and menu from the Internet Explorer standard toolbar.

Drop-down functionality can be added to any button style by adding a style flag to the fStyle member of the button's TBBUTTON structure. There are three styles of drop-down button, all of which are used by Internet Explorer:

  • Plain drop-down buttons have the BTNS_DROPDOWN style. They look like normal buttons, but they display a menu when clicked instead of launching a command.
  • Simple drop-down arrow buttons have the BTNS_WHOLEDROPDOWN style. They have an arrow displayed next to the button image or text. Other than the difference in appearance, they are identical to plain drop-down buttons. The Mail button used as the example in the preceding illustration is a drop-down arrow button.

  • Drop-down arrow buttons that add the TBSTYLE_EX_DRAWDDARROWS extended style to BTNS_DROPDOWN have an arrow that is separated from the text or image. This button style combines the functionality of drop-down and standard buttons. If the user clicks the arrow, a menu is displayed and the user can choose from several commands. If the user clicks the adjacent button, it launches a default command. The following illustration shows the Internet Explorer Back button, which uses a separated arrow.

    Drop-down button with separate arrow

When the user clicks a drop-down button with either the plain or simple arrow styles, the toolbar control sends your application a TBN_DROPDOWN notification. When your application receives this message, it is responsible for creating and displaying the menu, and for handling the selected command. For further discussion, see Toolbar Controls.

When the user clicks a separated arrow, the toolbar control sends your application a TBN_DROPDOWN notification. Your application should handle it the same way as it handles the other two types of drop-down buttons. If the user clicks the main button, your application receives a WM_COMMAND message with the button's command ID, just as if it were a standard button. Applications typically respond by launching the top command in the drop-down menu, but you are free to respond in any suitable way.

List-style Buttons

With standard buttons, if you add text, it is displayed below the bitmap. The following illustration shows the Internet Explorer Search and Favorites buttons with standard button text.

Standard button style

Internet Explorer 5 uses the TBSTYLE_LIST style. The text is to the right of the bitmap, reducing the height of the button and enlarging the viewing region. The following illustration shows the Internet Explorer 5 Search and Favorites buttons with the TBSTYLE_LIST style.

Chevrons

When the user rearranges the bands in the rebar control, part of a toolbar might be covered up. If the band was created with the RBBS_USECHEVRON style, the rebar control will display a chevron at the right edge of the toolbar. The user clicks the chevron to display a menu with the hidden tools. For a discussion on how to implement chevrons, see Handling Chevrons.

Hot-tracking

When hot-tracking is enabled, a button becomes hot when the cursor is over it. The hot button is normally distinguished from the other buttons on the toolbar by a distinctive image. By default, a hot button appears to be raised above the rest of the toolbar. When a new button becomes hot, your application receives a TBN_HOTITEMCHANGE notification. The following illustration shows the Internet Explorer 5 Search and Favorites buttons, with a hot Search button. In addition to having a raised appearance, the button's gray bitmap has been replaced with a colored one.

To enable hot-tracking, create a toolbar control with either the TBSTYLE_FLAT or TBSTYLE_LIST style. These are referred to as flat toolbars because the individual buttons are not ordinarily highlighted in any way. The bitmaps are simply displayed next to each other. They take on a button-like appearance only when they are hot. These two styles are also transparent, which means the background of the icons will be the color of the underlying client window.

To have a different bitmap displayed when the button is hot, create a second image list containing hot images for all the buttons on the toolbar. The size and order of these images should be the same as in the default image list. Send the toolbar control a TB_SETIMAGELIST to set the hot image list.


Creating an Internet Explorer-style Menu Bar

At a glance, the Microsoft® Internet Explorer 5 menu bar looks much like a standard menu. However, it looks quite different in use. The following illustration shows the Internet Explorer menu bar with the Tools item selected.

The menu bar is actually a toolbar control that looks and functions very much like a standard menu. Instead of top-level menu items, a menu bar has a series of text-only buttons that display a drop-down menu when clicked. However, as a specialized type of toolbar, a menu bar has some capabilities that standard menus lack. As a toolbar control:

  • It can be customized using standard toolbar techniques, allowing the user to move, delete, or add items.
  • It can have hot-tracking, so that users will know when they are over a top-level item without having to click it first.

A menu bar can be incorporated into a rebar control, giving it the following features:

  • It can have a gripper, which allows the user to move or resize the band.
  • It can share a strip in the rebar control with other bands, such as the standard toolbar in the preceding illustration.
  • It can display a chevron when it is covered by an adjacent band, giving the user access to the hidden items.
  • It can have an application-defined background bitmap.

This document discusses how to implement a menu bar. Since a menu bar is a specialized implementation of a toolbar control, the focus will be on topics that are specific to menu bars. For a discussion of how to incorporate a toolbar into a rebar control, see Creating an Internet Explorer-style Toolbar and Rebar Controls.

  • Making a Toolbar into a Menu Bar
  • Handling Navigation with Menu Hot-Tracking Disabled
  • Handling Navigation with Menu Hot-Tracking Enabled

Making a Toolbar into a Menu Bar

To make a toolbar into a menu bar:

  • Create a flat toolbar by including TBSTYLE_FLAT with the other window style flags. The TBSTYLE_FLAT style also enables hot-tracking. With this style, the menu bar looks much like a standard menu until the user activates a button. Then, the button appears to stand out from the toolbar and depress when it is clicked, just like a standard button. Because hot-tracking is enabled, all that is needed to activate a button is for the cursor to hover over it. If the cursor moves to another button, it will be activated and the old button deactivated.
  • Create list-style buttons by including TBSTYLE_LIST with the other window style flags. This style creates a thinner button that looks more like a standard top-level menu item.
  • Make the buttons text-only by setting the iBitmap member of the button's TBBUTTON structure to I_IMAGENONE and the iString member to the button text.
  • Give each button the BTNS_DROPDOWN style. When the button is clicked, the toolbar control sends your application a TBN_DROPDOWN notification to prompt it to display the button's menu.
  • Incorporate the menu bar into a rebar band. Enable both grippers and chevrons, as discussed in Creating an Internet Explorer-style Toolbar.
  • Implement a TBN_DROPDOWN handler to display the button's drop-down menu when it is clicked. The drop-down menu is a type of pop-up menu. It is created with TrackPopupMenu, with its upper-left corner aligned with the lower-left corner of the button.
  • Implement keyboard navigation, so that the menu bar is fully accessible without a mouse.
  • Implement menu hot-tracking. With standard menus, once a top level menu item's menu has been displayed, moving the cursor over another top-level item automatically displays its menu and collapses the menu of the previous item. The toolbar control will hot-track the cursor and change the button image, but it does automatically display the new menu. Your application must do so explicitly.

Most of these items are straightforward to implement and are discussed elsewhere. See Creating an Internet Explorer-style Toolbar, Toolbar Controls, or Rebar Controls for a general discussion of how to use toolbars and rebar controls. See Menus for a discussion of how to handle pop-up menus. The final two items, keyboard navigation and menu hot-tracking, are discussed in the remainder of this document.

Handling Navigation with Menu Hot-Tracking Disabled

Users can choose to navigate the menu bar with the mouse, the keyboard, or a mixture of both. To implement menu bar navigation, your application needs to handle toolbar notifications and monitor the mouse and keyboard. This task can be broken into two distinct parts: with and without menu hot-tracking. This section discusses how to handle navigation when no menus are displayed and menu hot-tracking is not enabled.

Mouse Navigation

If menu hot-tracking is disabled, you can treat a menu bar as a normal toolbar. If the user is navigating with a mouse, all your application needs to do is handle the TBN_DROPDOWN notification. When this notification is received, display the appropriate drop-down menu, and enable menu hot-tracking. From then on, you are in the menu hot-tracking regime, discussed in Implementing Menu Hot-Tracking.

As discussed in Mixed Navigation, you also need to handle the TBN_HOTITEMCHANGE notification to keep track of the active button. This notification is irrelevant if the user is only navigating with the mouse, but it is necessary when mouse and keyboard navigation are mixed.

Keyboard Navigation

As noted in the previous section, the user can do a number of navigation operations with the keyboard when menu hot-tracking is disabled. Toolbar controls support keyboard navigation only if they have focus. They also do not handle all the key presses that are needed for menu bars. The simplest solution to handling keyboard navigation is to process the relevant key press events explicitly.

If menu hot-tracking is disabled, your application needs to handle these key press events in the following way:

  • The F10 key. Activate the first button with TB_SETHOTITEM.
  • The LEFT ARROW and RIGHT ARROW keys. Activate the adjacent button with TB_SETHOTITEM. If the user attempts to navigate off either end of the menu bar, activate the first button at the opposite end.
  • The ESCAPE key. Deactivate the active button with TB_SETHOTITEM. The menu bar should be returned to the state it had prior to activating the first button.
  • An ALT-Key accelerator key. Use the TB_MAPACCELERATOR message to determine which button the Key character corresponds to. Display the button's drop-down menu and enable menu hot-tracking.
  • The DOWN ARROW key. If a button is active but no menu has been displayed, display the button's menu and enable menu hot-tracking.
  • The ENTER key. Deactivate the active button with TB_SETHOTITEM. The menu bar should be returned to the state it had prior to activating the first button.

Mixed Navigation

The keyboard navigation handlers outlined in the preceding section basically do two tasks: keep track of the active button and display the appropriate menu when a button is selected. These handlers are sufficient as long as the user navigates only with the keyboard. However, users often mix keyboard and mouse navigation. For example, they might activate the first button with the F10 key, use the mouse to activate a different button, and then open its menu with the DOWN ARROW key. If you are only monitoring key presses to keep track of the active key, you will display the wrong menu. You must also handle the TBN_HOTITEMCHANGE notification to accurately keep track of the active button.

Handling Navigation with Menu Hot-Tracking Enabled

Once menu hot-tracking is enabled, your application must change the way it responds to user navigation. To replicate the behavior of standard menus, you must implement the following features explicitly.

With mouse navigation:

  • If the user moves the cursor over another button, that menu immediately appears and the previous menu disappears.
  • Menu hot-tracking stays active until the user selects a command or clicks a point that is not part of the menu region. Either action deactivates menu hot-tracking until another button is clicked.
  • If the cursor moves off the menu, the current drop-down menu remains until the cursor moves back onto, or the user clicks a point outside, the area covered by the menu. If the cursor returns to a different button than the one currently being displayed, the old menu is collapsed and the new menu is displayed.

With keyboard navigation:

  • The RIGHT ARROW key. If the item has a submenu, display the submenu. If the item does not have a submenu, collapse the menu and any submenus, activate the next button with TB_SETHOTITEM, and display the menu for the adjacent button. If the last button is active when this message is received, display the menu for the first button.
  • The LEFT ARROW key. If the item is a submenu, collapse it and shift focus to its parent menu. If the item is not a submenu, collapse the menu, activate the next button with TB_SETHOTITEM, and display the menu for that button.
    • Pressing the LEFT ARROW key moves the focus to the left.
      • If the highlighted menu item is on the primary menu, that menu is collapsed, and the menu for the adjacent button is displayed. If the active button was at the left end of the toolbar, the menu for the last button is displayed.
      • If the highlighted menu item is on a submenu, the submenu is collapsed, shifting the focus back to its parent.
    • Pressing the RIGHT ARROW key moves the focus to the right.
      • If the highlighted menu item does not have a submenu, the menu for the adjacent button is displayed. If the active button was at the right end of the toolbar, the menu for the last button is displayed.
      • If the highlighted menu item has a submenu, the submenu is displayed.
    • The ESCAPE key backs the display up one step.
      • If a submenu is displayed, it is collapsed and focus shifts to the parent menu.
      • If a button's menu is displayed, it is collapsed and menu hot-tracking is disabled. The item's button remains active.
      • If no menus are displayed but a button is active, the button is deactivated and menu hot-tracking is disabled.
    • The UP ARROW and DOWN ARROW keys are used only to navigate within a particular menu.
    • The ENTER key launches the command associated with a menu item. If the menu item has a submenu, the ENTER key displays it.

As with the menu hot-tracking disabled case, your application needs to handle mouse, keyboard, and mixed navigation. However, the fact that a menu is displayed means that messaging will have to be handled somewhat differently.

Message Processing for Menu Hot-Tracking

Menu hot-tracking requires that a menu be displayed at all times, apart from the brief interval required to switch to a new menu. However, the drop-down menu that is displayed by TrackPopupMenu is modal. Your application will continue to receive some messages directly, including WM_COMMAND, TBN_HOTITEMCHANGE, and normal menu-related messages such as WM_MENUSELECT. However, it will not receive low-level keyboard or mouse messages directly. To handle messages such as WM_MOUSEMOVE, you must set a message hook to intercept messages directed to the menu.

When a drop-down menu is displayed, set the message hook by calling SetWindowsHookEx with the idHook parameter set to WH_MSGFILTER. All messages intended for the menu will be passed to your hook procedure. For example, the following code fragment sets a message hook that will trap messages going to a drop-down menu. MsgHook is the name of the hook procedure, and hhookMsg is the handle to the procedure.

hhookMsg = SetWindowsHookEx(WH_MSGFILTER, MsgHook, HINST_THISDLL, 0);

Menu messages are identified by setting the hook procedure's nCode parameter to MSGF_MENU. The lParam parameter will point to a MSG structure with the message. The details of which messages need to be handled, and how, are discussed in the remainder of this document.

Your application must pass all messages on to the next message hook by calling CallNextHookEx. You must also send mouse messages directly to the toolbar control, making sure to convert any point coordinates to the toolbar client coordinate space. Sending the messages directly ensures that the toolbar control receives the appropriate mouse messages. For instance, the toolbar needs to receive WM_MOUSEMOVE messages in order to hot-track its buttons.

When a new button is activated, your application must collapse the old drop-down menu with a WM_CANCELMODE message, and display a new menu. It must also collapse the drop-down menu when focus is taken from the menu bar with keyboard navigation or by clicking outside the menu area. Whenever you collapse a menu, you should free its message hook with UnhookWindowsHookEx. If you need to display another drop-down menu, create a new message hook. When a command is launched, the menu will be collapsed automatically but you must explicitly free the message hook.

The following code fragment frees the message hook that was set in the previous example.

UnhookWindowsHookEx(hhookMsg);

Mouse Navigation

When a normal toolbar control hot-tracks buttons, it highlights the active button and sends the application a TBN_HOTITEMCHANGE notification each time a new button is activated. Your application is responsible for displaying the appropriate drop-down menu. It must:

  • Handle the TBN_HOTITEMCHANGE notification to keep track of the active button. When the active button changes, collapse the old menu and create a new one.
  • Handle the TBN_DROPDOWN notification that is sent when a button is clicked. It should then collapse the menu and disable menu hot-tracking. The button remains active.
  • Handle the WM_LBUTTONDOWN, WM_RBUTTONDOWN, and WM_MOUSEMOVE messages in your message hook procedure, to keep track of the mouse position. If the mouse is clicked outside the menu area, collapse the current drop-down menu, deactivate menu hot-tracking, and return the menu bar to its preactivation state.
  • When a menu command is launched, disable menu hot-tracking. The menu will be collapsed automatically but you must explicitly free the message hook.

You must also handle menu-related messaging, such as the WM_INITMENUPOPUP message that is sent when a menu item needs to display a submenu. For a discussion of how to handle such messages, see Menus.

Keyboard Navigation

Your application must process keyboard messages in the message hook procedure and act on those that affect menu hot-tracking. The following key presses need to be handled:

  • The ESCAPE key. The ESCAPE key backs the display up one level. If a submenu is being displayed, it must be collapsed. If a button's primary menu is displayed, collapse it and disable menu hot-tracking. The button remains active.
  • The RIGHT ARROW key. If the item has a submenu, display it. If the item does not have a submenu, collapse the menu and any submenus, activate the next button with TB_SETHOTITEM, and display its menu. If the last button was active when this notification was received, display the menu for the first button.
  • The LEFT ARROW key. If the item is in a submenu, collapse it and shift focus to its parent menu. If the item is not a submenu, collapse the menu, activate the adjacent button with TB_SETHOTITEM, and display its menu. If the first button was active when this notification was received, display the menu for the last button.
  • The UP ARROW and DOWN ARROW keys. These keys are used to navigate within a menu but do not directly affect menu hot-tracking.
  • An ALT-Key accelerator key. Use the TB_MAPACCELERATOR message to determine which button the Key character corresponds to. If it corresponds to a different button than the currently active one, collapse the current drop-down menu, activate the new button with TB_SETHOTITEM, and display the menu for the adjacent button. If the Key character corresponds to the currently displayed button, collapse the drop-down menu and disable menu hot-tracking. The button should remain active.


Localization Support for the Common Controls

The common controls have built-in support for national languages. These features simplify the implementation of localized applications.

  • Specifying a Language for the Common Controls
  • Specifying a Language for Controls in a Dialog Box

Specifying a Language for the Common Controls

If you want to specify a language for the common controls that is different than the system language, call InitMUILanguage. The language specified by this function applies only to the process from which the function is called.

To determine the language currently being used by the common controls, call GetMUILanguage. It returns the value that was set by a previous call to InitMUILanguage. The language returned is the one that was specified for the process it is called from. If InitMUILanguage has not been called, or was called from another process, GetMUILanguage will return a default value.

Specifying a Language for Controls in a Dialog Box

Unlike common controls, predefined controls such as buttons or edit boxes do not use the current system language by default. The native font control is an invisible control that works in the background to allow a dialog box's predefined controls to display the current system language.

To use the native font control:

  1. Initialize the native font control by calling InitCommonControlsEx. Set the dwICC member of the INITCOMMONCONTROLSEX structure pointed to by lpInitCtrls to ICC_NATIVEFNTCTL_CLASS.

  2. Add the control to the resource script for the dialog box. Set one or more of the following style flags to specify which controls will be affected.

    Flag | Applies to
    NFS_EDIT | Edit controls
    NFS_STATIC | Static controls
    NFS_LISTCOMBO | List, ComboBox, List-View, and ComboBoxEx controls
    NFS_BUTTON | Button controls
    NFS_ALL | All controls
    NFS_USEFONTASSOC | East Asian platform. The control uses the font association feature instead of switching to the native font. All other platforms ignore it.

The following example illustrates how to add a native font control to a resource script. It causes the dialog box's edit, list, and combo box controls to display text using the current system language.

CONTROL    "",-1,"NativeFontCtl",NFS_EDIT|NFS_LISTCOMBO,0,0,0,0


Creating Wizards

Wizards are a type of property sheet that provide a simple and powerful way to guide users through complex procedures.

  • Introduction
  • How to Implement a Wizard
  • A Sample Wizard Application

For a general discussion of property sheets, see Property Sheets. For links to the Property Sheet API elements, see Property Sheet Reference.

Introduction

Wizards are one of the keys to simplifying the user experience. They allow you to take a complex operation, such as configuration of an application, and break it into a series of simple steps. At each point in the process, you can provide an explanation of what is needed, and display controls that allow the user to make selections and enter text.

In terms of implementation, a wizard is actually a type of property sheet. A property sheet is essentially a container for a collection of pages, where each page is a separate dialog box. Much of what you need to do to implement a wizard actually involves familiar dialog box programming techniques.

A standard property sheet displays the pages as if they were stacked one on top of the other. Each page has a tab at the top, and users select a page by clicking its tab. They then interact with the page as they would with a regular dialog box. The following illustration shows the Microsoft® Windows 2000 Date/Time property sheet in Control Panel.

Wizards present pages one at a time. Instead of tabs, there are Next and Back buttons located at the bottom of the wizard. Users click these buttons to navigate forward or backward through a sequence of pages. The order in which pages are displayed is controlled by the application and can be modified based on user input. The following illustration shows the welcome page of the Windows 2000 Hardware Wizard in Control Panel.

This chapter outlines the basic process of creating a Wizard97-style wizard. The next section is a general discussion of wizard implementation. The final section of the chapter is a detailed walkthrough of Wiz97 a simple wizard application.

Note: The discussion in most of this document assumes that you are implementing a Wizard97-style wizard for a system with version 5.80 or later of the common controls. You can use this style on Windows 2000 or later systems, or any Windows system with Internet Explorer 5 or later. However, you must use #define to set the value of _WIN32_IE to 0x0500 or higher before including the common controls header file (Commctrl.h). If you attempt to use the Wizard97 style with earlier versions of the common controls, your application may compile but it will not display properly. For a discussion about how to create a Wizard97-compatible wizard on earlier systems, see the Backward Compatible Wizards section.

How to Implement a Wizard

Implementing a wizard is similar to implementing a regular property sheet. At the most basic level, it is a matter of setting the appropriate style flag. To implement the individual pages, use the same dialog box programming techniques that you use for property sheets. However, there are are a number of wizard-specific property sheet features that are used by nearly all wizards.

The primary focus of this chapter is on those aspects of property sheets specific to wizards. It provides a detailed discussion of how to create a wizard's property sheet and pages, and how to handle navigation from one page to the next. It also goes into a few of the related design issues. For a complete discussion of design issues, you should see the Wizard97 Specification, elsewhere in the Platform SDK. Familiarity with standard dialog box programming techniques is assumed. For detailed information, see the discussion of Dialog Boxes, elsewhere in the Platform SDK. For a more general discussion of property sheets, see the Property Sheets chapter.

Once you have defined your task and designed a user interface for each page, the basic procedure for implementing a wizard is relatively straightforward:

  1. Create a dialog box template for each page.
  2. Define the pages by creating a PROPSHEETPAGE structure for each page. This structure defines the page, and contains pointers to the dialog box template and any bitmaps or other resources.
  3. Pass the PROPSHEETPAGE structure created in the previous step to CreatePropertySheetPage to create the page's HPROPSHEETPAGE handle.
  4. Define the wizard by creating a PROPSHEETHEADER structure for it.
  5. Pass the PROPSHEETHEADER structure to PropertySheet to display the wizard.
  6. Implement dialog box procedures for each page to handle notification messages from the page's controls and the wizard's buttons and to process other Windows messaging.

Creating the Dialog Box Templates

This chapter discusses how to create a Wizard97-style wizard. This wizard style is used by a wide variety of Microsoft applications. To be compatible with the Wizard97 style, your templates need to adhere to the Wizard97 Specification. This document has guidelines for such things as the dimensions for the dialog boxes, bitmap dimensions and colors, and the placement of controls.

There are two basic types of wizard page: exterior and interior. The exterior pages are the welcome and completion pages. The other pages in the wizard are interior.

Exterior Page Dialog Box Templates

All wizards have two exterior pages: welcome and completion. They come at the beginning and end of the sequence, respectively. Their basic layout is identical. For example, the following illustration shows a sample Wizard97 welcome page.

For exterior pages, the dialog box is 317x193 dialog units (dlus). It fills all of the wizard, except for the caption and the band at the bottom that contains the Back, Next, and Cancel buttons. The left side of the template, which is reserved for a watermark bitmap, should not contain any controls. The watermark is specified in the wizard's PROPSHEETHEADER structure and is added to the page automatically.

When you create the watermark bitmap, keep in mind that the dialog box may increase in size if, for example, the user chooses a large system font. Different languages also tend to have different font metrics. When the page grows, the area reserved for the watermark gets proportionately larger. However, you cannot change the watermark bitmap, nor is the bitmap stretched to fill the larger area. Instead, the bitmap is left in its original size in the upper-left portion of the reserved area. The part of the larger reserved area that is not covered by the watermark is automatically filled with the color of the bitmap's upper-left pixel.

If you need to have different sized watermark bitmaps for different font metrics, two possible solutions are:

  • Get the font metrics before creating the wizard, and specify an appropriately sized watermark bitmap.
  • Don't specify a watermark bitmap when you create the wizard. Wizard97 will leave the watermark area blank. Then draw an appropriately sized bitmap on the area reserved for the watermark.

You can place controls in the area to the right of the watermark as you would for a regular dialog box. The background color of this area is determined by the system, and requires no action on your part. You typically put two static controls in this area. The upper one holds the title and uses a large bold font (12 point Verdana Bold). The other one, which is for explanatory text, uses the standard dialog box font.

The main difference between the two types of exterior page is the wizard buttons and the text in the static controls. Welcome pages normally have a Next and a Back button, with only the Next button enabled. Completion pages have the Back button enabled, and the Next button is replaced by a Finish button. The wizard buttons are handled in the dialog box procedure, and don't affect the template. As far as the template is concerned, all you need to do is provide appropriate text in the static controls for each exterior page.

You can modify the text on the finish button by sending the wizard a PSM_SETFINISHTEXT message. By default, the Finish button does not include a keyboard accelerator. To define a keyboard accelerator, include an ampersand (&) in the text string that you pass to PSM_SETFINISHTEXT. For instance, "&Finish" defines 'F' as the keyboard accelerator.

Interior Page Dialog Box Templates

Interior pages have a somewhat different appearance than exterior pages. The following illustration shows what a typical Wizard97 interior page looks like.

The header area at the top of the page is handled by the property sheet, so it is not included in the template. The contents of the header are specified in the page's PROPSHEETPAGE structure and the wizard's PROPSHEETHEADER structure. Because the interior pages' template needs to fit between the header and the buttons, it is 317x143 dialog units, somewhat smaller than the template for exterior pages. None of the template area is reserved, but you should consult the Wizard97 Specification for guidelines on control placement.

Defining the Wizard Pages

Once you have created the dialog box templates and related resources such as bitmaps and string tables, you can create the property sheet pages. The procedure is similar to that for standard property sheets. First, fill in the appropriate members of a PROPSHEETPAGE structure and then call the CreatePropertySheetPage function to create the page's HPROPSHEETPAGE handle. However, there are a few features of this structure that are specific to wizards in general, and the Wizard97 style in particular.

There are a number of wizard-related flags that can be set in the dwFlags member of the PROPSHEETPAGE structure:

Flag | Description
PSP_HIDEHEADER | Set this flag for exterior pages. Do not set it for interior pages
PSP_USEHEADERTITLE | Set this flag for interior pages to put a title in the header area.
PSP_USEHEADERSUBTITLE | Set this flag for interior pages to put a subtitle in the header area.

If you have set PSP_USEHEADERTITLE or PSP_USEHEADERSUBTITLE, assign the title and subtitle text to the pszHeaderTitle and pszHeaderSubtitle members, respectively. When you assign text strings to members of the PROPSHEETPAGE and PROPSHEETHEADER structures, you can either assign a string pointer or use the MAKEINTRESOURCE macro to assign a value from a string resource. The string resource will be loaded from the module specified in the hInstance member of the wizard's PROPSHEETHEADER structure.

When a page is first selected, its dialog box procedure receives a WM_INITDIALOG message. The message's lParam value will point to a copy of of the page's PROPSHEETPAGE structure. In general, you should not modify this structure. However, the structure's lParam member is ignored by the operating system and is commonly used to store data that is shared by all pages. Typically, you would create an application-defined structure to store the shared data and assign its pointer to each page's lParam member. Each page's WM_INITDIALOG message handler then extracts and stores this pointer, giving all pages access to the shared data. An example of how to use lParam is given in the Wiz97 sample.

When you call CreatePropertySheetPage to create an HPROPSHEETPAGE handle for each page, assign the result to an element of an array of HPROPSHEETPAGE handles. This array is then used when creating the property sheet. The array index of a page's handle determines the default order in which it will be displayed. Once you have created a page's HPROPSHEETPAGE handle, you can reuse the same PROPSHEETPAGE structure to create the next page by assigning new values to the relevant members.

An alternative way to create pages is to use separate PROPSHEETPAGE structures for each page, and create an array of structures. This array is then used when creating the property sheet instead of an array of HPROPSHEETPAGE handles. Using separate PROPSHEETPAGE structures eliminates the need to call CreatePropertySheetPage but uses a bit more memory. Otherwise, there is no significant difference between the two approaches.

The following example defines an interior wizard page by assigning values to a PROPSHEETPAGE structure, psp. In this example, the page's title, subtitle, and dialog box template are all identified by their resource IDs. The CreatePropertySheetPage function is then called to create the page's HPROPSHEETPAGE handle. Because it will be the second page to appear, the handle is assigned to the array of handles, ahpsp, with an index of one.

    psp.dwSize =            sizeof(psp);
    psp.hInstance =         hInstance;
    psp.dwFlags =           PSP_DEFAULT|PSP_USEHEADERTITLE|PSP_USEHEADERSUBTITLE;
    psp.lParam =            (LPARAM) &wizdata;
    psp.pszHeaderTitle =    MAKEINTRESOURCE(IDS_TITLE1);
    psp.pszHeaderSubTitle = MAKEINTRESOURCE(IDS_SUBTITLE1);
    psp.pszTemplate =       MAKEINTRESOURCE(IDD_INTERIOR1);
    psp.pfnDlgProc =        IntPage1DlgProc;

    ahpsp[1] =              CreatePropertySheetPage(&psp);

Defining the Wizard Property Sheet

As with ordinary property sheets, you define the wizard's property sheet by filling in members of a PROPSHEETHEADER structure. This structure allows you to specify the pages that will make up the wizard and the default order in which they will be displayed, along with several related parameters. You then launch the wizard by calling the PropertySheet function.

There are a number of wizard-related flags that can be set in the structure's dwFlags .

Flag | Description
PSH_USEHBMHEADER | Set this flag instead of PSH_USEHEADER to use an HBITMAP handle to identify the bitmap that will be placed at the right side of an interior page's header area. Assign the handle to the hbmHeader member.
PSH_USEHBMWATERMARK | Set this flag instead of PSH_WATERMARK to use an HBITMAP handle to identify the watermark bitmap. Assign the handle to the hbmWatermark member.
PSH_USEHEADER | Set this flag to use a resource ID to identify the the header bitmap. Use MAKEINTRESOURCE to convert the resource ID into a string, and assign the string to the pszbmHeader member.
PSH_USEPLWATERMARK | Set this flag to define your own palette for the watermark bitmap. Assign the palette's HPALETTE handle to the hplWatermark member.
PSH_WATERMARK | Set this flag to use a resource ID to identify the watermark bitmap. Use MAKEINTRESOURCE to convert the resource ID into a string, and assign the string to the pszbmWatermark member.
PSH_WIZARD97 | Set this flag to specify a Wizard97-style wizard.
PSH_WIZARDCONTEXTHELP | Set this flag to display a context-sensitive Help button on the wizards caption bar.
PSH_WIZARDHASFINISH | Set this flag to display a Finish button on all pages. Typically, wizards only display Back, Next or Finish, and Cancel, and replace Next with Finish on the completion page. If this flag is set, every page will display all four buttons.

The pszCaption member of the PROPSHEETHEADER structure is ignored. Instead, the wizard displays the caption that is specified in the current page's dialog box template.

If you have created an array of HPROPSHEETPAGE handles for your pages, assign the array to the phpage member. If you have instead created an array of PROPSHEETPAGE structures, assign the array to the ppsp member and set the PSH_PROPSHEETPAGE flag in the dwFlags member.

The following example assigns values to psh, a PROPSHEETHEADER structure and calls the PropertySheet function to launch the wizard. The Wizard97-style wizard has both watermark and header graphics, specified by their resource IDs. The ahpsp array contains all the HPROPSHEETPAGE handles and defines the default order in which they will be displayed.

    psh.dwSize =         sizeof(psh);
    psh.hInstance =      hInstance;
    psh.hwndParent =     NULL;
    psh.phpage =         ahpsp;
    psh.dwFlags =        PSH_WIZARD97|PSH_WATERMARK|PSH_HEADER;
    psh.pszbmWatermark = MAKEINTRESOURCE(IDB_WATERMARK);
    psh.pszbmHeader =    MAKEINTRESOURCE(IDB_BANNER);
    psh.nStartPage =     0;
    psh.nPages =         4;

    PropertySheet(&psh);

The Dialog Box Procedure

Once the wizard has been launched, each page will need a dialog box procedure to process Windows messaging, particularly notifications from its controls and the wizard. The dialog box procedure will receive the usual WM_XXX Windows messages. The three that virtually all wizards will need to handle are WM_INITDIALOG, WM_DESTROY, and WM_NOTIFY.

Handling WM_INITDIALOG and WM_DESTROY

When a page is about to be displayed for the first time, its dialog box procedure receives a WM_INITDIALOG message. Handling this message allows the wizard to do any needed initialization tasks. For example, the sample code discussed later handles this message to set the font for the welcome and completion page titles.

The WM_INITDIALOG message's lParam value points to a copy of the page's PROPSHEETPAGE structure. The lParam member of this structure is ignored by the system. It typically points to an application-defined shared data structure that is used to store persistent data and pass data from one page to another.

To preserve access to the shared data structure for later use, load it's pointer into the pages' user data by calling theGetWindowLong function with an index of GWL_USERDATA. You can then use SetWindowLong to retrieve the pointer when needed. The Wiz97 sample has a simple example of how to use a shared data structure.

Note: Do not attempt to modify any members of the PROPSHEETPAGE structure other than lParam. Doing so will have unpredictable consequences.

When the property sheet is destroyed, you will receive a WM_DESTROY message. The wizard is automatically destroyed by the system, but handling this message allows you to do any needed cleanup.

Handling WM_NOTIFY

Notifications from the wizard come in the form of a WM_NOTIFY message. You will receive this message before the page is displayed and when any of the wizard's buttons are clicked. The lParam parameter of the message is a pointer to a NMHDR header structure. The notification's ID is contained in the structure's code member. The four that most wizards will need to handle are:

Code | Description
PSN_SETACTIVE | Sent before the page is displayed.
PSN_WIZBACK | Sent when the Back button is clicked.
PSN_WIZNEXT | Sent when the Next button is clicked.
PSN_WIZFINISH | Sent when the Finish button is clicked.
Handling PSN_SETACTIVE

The PSN_SETACTIVE notification message is sent each time a page is about to be made visible. The first time a page is visited, PSN_SETACTIVE follows the WM_INITDIALOG message. If the page is subsequently revisited, it will receive only a PSN_SETACTIVE notification. This notification is usually handled to initialize data for the page and enable the appropriate buttons.

By default, the wizard displays Back, Next, and Cancel buttons, with all buttons enabled. To disable a button or display Finish instead of Next, you must send a PSM_SETWIZBUTTONS message. Once this message has been sent, the state of the buttons will be preserved until it is modified by another PSM_SETWIZBUTTONS message, even if a new page is selected. Typically, all PSN_SETACTIVE handlers send this message to ensure that each page has the correct button state.

You can change the button state with this message at any time. For example, you may want the Next button to be initially disabled. Once a user has entered all the necessary information, you can send another PSM_SETWIZBUTTONS message to enable the Next button and let the user proceed to the next page.

The following code fragment uses the PropSheet_SetWizButtons macro to enable the Back and Next buttons on an interior page before it is displayed:

    case WM_NOTIFY :
    {
        LPNMHDR pnmh = (LPNMHDR)lParam;
        switch(pnmh->code)
        {
        ...
        case PSN_SETACTIVE :
            ...
            //this is an interior page
            PropSheet_SetWizButtons(hwnd, PSWIZB_NEXT | PSWIZB_BACK);
            ...
        }
    ...
    }
Handling PSN_WIZNEXT, PSNWIZBACK, and PSN_WIZFINISH

When a Next or Back button is clicked, you will receive a PSN_WIZNEXT or PSN_WIZBACK notification message. By default, the wizard will automatically go to either the next or previous page in the order that is defined when the property sheet is created. A common reason to handle these notifications is to prevent the user from switching pages, or to override the default page order.

To prevent the user from switching pages, handle the button notification, call the SetWindowLong function with the DWL_MSGRESULT value set to -1, and return TRUE. For example:

    case PSN_WIZNEXT :
        ...
        //Don't go to next page yet.
        SetWindowLong(hwnd, DWL_MSGRESULT, -1);
        return TRUE;
        ...

To override the standard order and go to a particular page, call SetWindowLong with the DWL_MSGRESULT value set to the page's dialog box resource ID, and return TRUE. For example:

    case PSN_WIZNEXT :
        ...
        //Go straight to the completion page.
        SetWindowLong(hwnd, DWL_MSGRESULT, IDD_FINISH);
        return TRUE;
        ...

When the Finish or Cancel buttons are clicked, you will receive a PSN_WIZFINISH or PSN_RESET notification message, respectively. When either of these buttons is clicked, the wizard will be automatically destroyed by the system. However, you can handle these notifications if you need to perform cleanup tasks before the wizard is destroyed. To prevent the wizard from being destroyed when you receive a PSN_WIZFINISH notification, call SetWindowLong with the DWL_MSGRESULT value set to TRUE, and return TRUE. For example:

    case PSN_WIZFINISH :
        ...
        //Not finished yet.
        SetWindowLong(hwnd, DWL_MSGRESULT, TRUE);
        return TRUE;
        ...

Backward Compatible Wizards

The preceding section assumes that you are implementing a wizard for a system with version 5 or later of the common controls. You will find this version on systems with Windows 2000 or later or any Windows system with Internet Explorer 5 or later.

If you are writing a wizard for systems with earlier versions of the common controls, many of the features discussed in the preceding section will not be available. A number of the members of the PROPSHEETHEADER and PROPSHEETPAGE structures that are used by the Wizard97 style are supported only by common controls version 5 and later. However, it is still possible to implement a backward compatible wizard with much the same look and feel as the Wizard97 style. To do so, you must explicitly implement the following:

  • Add the watermark graphic to the dialog box template for your welcome and completion pages.
  • Make all your templates same size. There is no separate system-defined header area for interior pages.
  • Create the interior page's header area explicitly on your templates.
  • Do not use a header graphic because it may conflict with the title or subtitle if the wizard changes size.

For further discussion of backward-compatible wizards, see the Backward-Compatible Wizards Specification.

A Sample Wizard Application

This section discusses Wiz97, a simple stand-alone wizard application that demonstrates the essentials of how to implement a Wizard97-style wizard. The focus is on how to create exterior and interior pages and navigate between them. There is only a limited discussion about how to design and implement individual dialog boxes. Although the sample dialog boxes have controls, only a few control notification messages are handled, largely to illustrate how to use certain features of wizards. For links to the source code, see the Wiz97 source files.

The Wiz97 wizard has a welcome page, a completion page, and two interior pages. The welcome page has a simple watermark and two static controls to hold the title and explanatory text.

The first interior page has a group box with three radio buttons and a check box. Note that the Next button is initially disabled. It is only enabled after one of the radio buttons or the check box is selected. If the check box is selected, clicking Next skips directly to the completion page instead of the second interior page.

The second interior page has three edit boxes, provided for illustration purposes only. None of the boxes have handlers.

The completion page is very similar to the welcome page. The text in the static controls is different, and the Next button is replaced by a Finish button. If the check box on the first interior page was selected, clicking Back will return to that page. If the check box was not selected at all, or was cleared, clicking Back will return to the second interior page.

The remainder of this section describes the implementation of the Wiz97 application. The complete sample code can be found under the Common Controls Samples topic or by clicking Wiz97 sample code. To make the code as readable as possible, all of the source code other than the dialog box procedures is in the WinMain function. For the same reason, error checking has been omitted. You should use whatever error checking is appropriate for your wizard application.

Note that this sample must be run on a system with version 5.80 of the common controls. Attempting to run it on earlier versions will have unpredictable results. For information (and sample code) about how to determine which version is present, see Shell and Common Control Versions .

Designing the Templates

The mechanics of creating a dialog box template is largely outside the scope of this document. For a general discussion of how to place your controls, specify bitmap colors and dimensions, and handle a number of other design issues, see the Wizard97 Specification. Here are some specific points to keep in mind when planning your template design:

  • The template doesn't include the band at the bottom of the wizard that holds the buttons.
  • For interior pages, the template also doesn't include the header area. Interior page templates are thus smaller than those for welcome and completion pages.
  • The template does not include the watermark bitmap. Just leave the area reserved for the watermark empty. The watermark bitmap is specified when you fill the PROPSHEETHEADER structure.
  • Remember that the color of the watermark's upper-left pixel will be used for a fill color if the dialog box is enlarged.

Creating the Wizard Pages

Creating the wizard pages primarily involves assigning values to the members of a PROPSHEETPAGE structure and calling CreatePropertySheetPage to create the page's HPROPSHEETPAGE handle. The following code example defines the welcome page by assigning values to a PROPSHEETPAGE structure named psp.

    psp.dwSize =      sizeof(psp);
    psp.dwFlags =     PSP_DEFAULT|PSP_HIDEHEADER;
    psp.hInstance =   hInstance;
    psp.lParam =      (LPARAM) &wizdata; //shared data structure
    psp.pfnDlgProc =  IntroDlgProc;
    psp.pszTemplate = MAKEINTRESOURCE(IDD_INTRO);

    ahpsp[0] =        CreatePropertySheetPage(&psp);

Setting the PSP_HIDEHEADER flag defines this page as exterior. The structure's lParam member points to an application-defined SHAREDWIZDATA structure. Because the Wiz97 wizard application assigns a pointer to this structure to the lParam member of the PROPSHEETPAGE structure used to to create all its pages, the SHAREDWIZDATA structure can be used to store shared data. The SHAREDWIZDATA structure is used to store the HFONT handle used by the welcome and completion pages, and the state of the radio buttons and check box on the first interior page. It is declared as:

    typedef struct SHAREDWIZDATA {
        HFONT hTitleFont;
        BOOL IsBoxChecked;
        BOOL IsButtonClicked;
    } SHAREDWIZDATA, *LPSHAREDWIZDATA;

The welcome page's dialog box procedure is assigned to IntroDlgProc. It is a generally a good practice for each page to have its its own dialog box procedure. Even a page with only static controls may still need to handle the wizard button notification messages.

When CreatePropertySheetPage is called, the HPROPSHEETPAGE handle is assigned to ahpsp [0]. The ahpsp array, which is an array of HPROPSHEETPAGE handles, is used later to create the property sheet. The array also determines the default order that the pages will be displayed.

The following example shows how to create the first interior page.

    psp.dwFlags =           PSP_DEFAULT|PSP_USEHEADERTITLE|PSP_USEHEADERSUBTITLE;
    psp.pszHeaderTitle =    MAKEINTRESOURCE(IDS_TITLE1);
    psp.pszHeaderSubTitle = MAKEINTRESOURCE(IDS_SUBTITLE1);
    psp.pszTemplate =       MAKEINTRESOURCE(IDD_INTERIOR1);
    psp.pfnDlgProc =        IntPage1DlgProc;

    ahpsp[1] =              CreatePropertySheetPage(&psp);

The dwSize, hInstance, and lParam members are the same for all pages, and are left unchanged. The PSP_HIDEHEADER flag is not set, so the page is interior. Setting the PSP_USEHEADERTITLE and PSP_USEHEADERSUBTITLE flags enables the system to place a title and subtitle in the header area. These titles are specified by assigning text strings, from a string table in this instance, to pszHeaderTitle and pszHeaderSubTitle. Assigning the HPROPSHEETPAGE handle to ahpsp[1] places the page second in the default display order.

The code used to create the second interior and completion pages is very similar to the first interior and welcome pages, respectively. The only difference is that different titles, dialog box procedures, and so on, are assigned to the members of the PROPSHEETPAGE structure, and the page's HPROPSHEETPAGE handle is assigned to a different element of ahpsp array.

Creating the Property Sheet

Creating the property sheet is similar to creating the individual pages. Assign values to members of a PROPSHEETHEADER structure, and then pass the structure to PropertySheet to launch the wizard. The following code example defines the Wiz97 property sheet by assigning values to a PROPSHEETHEADER structure named psh.

    psh.dwSize =         sizeof(psh);
    psh.hInstance =      hInstance;
    psh.hwndParent =     NULL;
    psh.phpage =         ahpsp;
    psh.dwFlags =        PSH_WIZARD97|PSH_WATERMARK|PSH_HEADER;
    psh.pszbmWatermark = MAKEINTRESOURCE(IDB_WATERMARK);
    psh.pszbmHeader =    MAKEINTRESOURCE(IDB_BANNER);
    psh.nStartPage =     0;
    psh.nPages =         4;

The PSH_WIZARD97 flag gives this property sheet the Wizard97 style. Setting PSH_WATERMARK and PSH_HEADER enables the system to add a watermark bitmap to the exterior pages, and a smaller bitmap to the header area of the interior pages. The watermark and header bitmaps, which are identified by their resource IDs, are assigned to the pszbmWatermark and pszbmHeader members, respectively. The handles to the individual pages are passed to the property sheet by assigning the ahpsp array to the phpage member.

Creating a Title Font

The Wizard97 Specification uses a 12 point Verdana Bold font for the titles of the welcome and completion pages. The Wiz97 application creates the font, and then assigns its HFONT handle to the hTitleFont member of the shared SHAREDWIZDATA structure.

The welcome and completion page's dialog box procedures extract a pointer to this structure when initializing the page. They then use the hTitleFont member to set the font for the static control that contains the title. The font is destroyed when the wizard shuts down, so it is created and destroyed only once. The following example shows how to create the font.

    NONCLIENTMETRICS ncm = {0};
    ncm.cbSize = sizeof(ncm);
    SystemParametersInfo(SPI_GETNONCLIENTMETRICS, 0, &ncm, 0);
    LOGFONT TitleLogFont = ncm.lfMessageFont;
    TitleLogFont.lfWeight = FW_BOLD;
    lstrcpy(TitleLogFont.lfFaceName, TEXT("Verdana Bold"));

    HDC hdc = GetDC(NULL);
    INT FontSize = 12;
    TitleLogFont.lfHeight = 0 - GetDeviceCaps(hdc, LOGPIXELSY) * FontSize / 72;
    wizdata.hTitleFont = CreateFontIndirect(&TitleLogFont);
    ReleaseDC(NULL, hdc);

The Dialog Box Procedures

Once the wizard is launched, most of the remainder of the application is handled by the dialog box procedures. Even with no active controls, pages still need to handle messages such as WM_INITDIALOG, and notifications from the Back, Next, Cancel, and Finish buttons. To simplify this task, each Wiz97 page has its own dialog box procedure.

The Welcome Page

The welcome page only has static controls, so its dialog box procedure is quite simple. The following example shows the code for the procedure:

BOOL CALLBACK IntroDlgProc (
                        HWND hwndDlg,
                        UINT uMsg,
                        WPARAM wParam,
                        LPARAM lParam
                        )
{
    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;

            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);

            HWND hwndControl = GetDlgItem(hwndDlg, IDC_TITLE);
            SetWindowFont(hwndControl,pdata->hTitleFont, TRUE);
            break;
        }

    case WM_NOTIFY :
        {
            LPNMHDR lpnm = (LPNMHDR) lParam;

            switch (lpnm->code)
            {
            case PSN_SETACTIVE : //Enable the Next button
                PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_NEXT);
                break;
            default :
                break;
            }
        }
        break;

    default:
        break;
    }
    return 0;
}

The first time a page's dialog box procedure is called, it will receive a WM_INITDIALOG message. The message handler extracts the pointer to the shared SHAREDWIZDATA structure from the lParam member of the page's PROPSHEETPAGE structure. It then uses SetWindowLong to assign the pointer to the page's user data. Each time the dialog box procedure is subsequently called, it uses GetWindowLong to extract the SHAREDWIZDATA pointer for later use. After storing the pointer, the message handler uses the hTitleFont member of the SHAREDWIZDATA structure to set the font for the static control that contains the title.

Following the WM_INITDIALOG message and each time a page is subsequently selected, its dialog box procedure receives a PSN_SETACTIVE notification message. This notification is sent before the page is displayed and is used for initialization. The welcome page's PSN_SETACTIVE notification handler uses the PropSheet_SetWizButtons macro to send a PSM_SETWIZBUTTONS message to enable the Next button. Because the wizard automatically takes care of displaying the next page, the Next button notification message is not handled. Although not shown here, the sample code has token button handlers as placeholders.

The Interior Pages

The first interior page is initially displayed with the Next button disabled. It is only enabled after a radio button or the check box is selected. If a user selects the check box, clicking Next takes the user directly to the completion page. The following example shows the dialog box procedure for the interior page.
BOOL CALLBACK IntPage1DlgProc (
                               HWND hwndDlg,
                               UINT uMsg,
                               WPARAM wParam,
                               LPARAM lParam
                               )
{
    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;
            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);
            break;
        }

    case WM_COMMAND :
        switch(LOWORD (wParam))
        {
        case IDC_CHECK1 :
            pdata->IsBoxChecked = !(pdata->IsBoxChecked);
            break;

        case IDC_RADIO1 :

        case IDC_RADIO2 :

        case IDC_RADIO3 :
            pdata->IsButtonClicked = TRUE;
            break;

        default :
            break;
        }

        if(pdata->IsBoxChecked || pdata->IsButtonClicked)
        {
            PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_NEXT);
        }

        else
        {
            PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK);
        }
        break;

    case WM_NOTIFY :
        {
        LPNMHDR lpnm = (LPNMHDR) lParam;

        switch (lpnm->code)
            {
            case PSN_SETACTIVE : //Enable the appropriate buttons.
                if(pdata->IsBoxChecked || pdata->IsButtonClicked)
                {
                    PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_NEXT);
                }

                else //Otherwise, only enable Back.
                {
                    PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK);
                }
                break;

            case PSN_WIZNEXT :

                if(pdata->IsBoxChecked)
                {
                    SetWindowLong(hwndDlg, DWL_MSGRESULT, IDD_END);
                    return TRUE;
                }
                break;

            default :
                break;
            }
        }
        break;

    default:
        break;
    }
    return 0;
}

The WM_INITDIALOG handler extracts the pointer to the shared SHAREDWIZDATA structure and assigns it to the page's user data. Initially, the PSN_SETACTIVE handler enables just the Back button. The Next button is only enabled after the user selects a radio button or the check box. If the check box has been selected, the PSN_WIZNEXT handler uses SetWindowLong to jump directly to the final page.

The IsBoxChecked member of the shared SHAREDWIZDATA structure is used to store the state of the check box. The value of the IsButtonClicked member indicates whether one of the radio buttons has been selected. Storing these state parameters in the SHAREDWIZDATA structure serves two purposes. One is to make this state information persistent, so that it is available if the page is revisited. The other is to make the state information available to other pages.

The second interior page does not implement any of the three edit boxes, so its dialog box procedure is minimal. As with the other dialog box procedures, its WM_INITDIALOG message handler assigns the pointer to the shared SHAREDWIZDATA structure to its user data. Its PSN_ACTIVE notification handler enables the Next and Back buttons. For more information, see the Wiz97 source code.

The Completion Page

The dialog box procedure for the completion page is similar to that for the welcome page. The following example shows the procedure code:

BOOL CALLBACK EndDlgProc (
                        HWND hwndDlg,
                        UINT uMsg,
                        WPARAM wParam,
                        LPARAM lParam
                        )
{
    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;
            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);

            HWND hwndControl = GetDlgItem(hwndDlg, IDC_TITLE);
            SetWindowFont(hwndControl,pdata->hTitleFont, TRUE);
            break;
        }

    case WM_NOTIFY :
        {
        LPNMHDR lpnm = (LPNMHDR) lParam;

        switch (lpnm->code)
            {
            case PSN_SETACTIVE :

                PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_FINISH);
                break;

            case PSN_WIZBACK :

                if(pdata->IsBoxChecked)
                {
                    SetWindowLong(hwndDlg, DWL_MSGRESULT, IDD_INTERIOR1);
                    return TRUE;
                }
                break;
            default :
                break;
            }
        }
        break;

    default:
        break;
    }
    return 0;
}

As with the welcome page, the WM_INITDIALOG handler extracts the shared SHAREDWIZDATA structure and stores the pointer in the page's user data. It then uses the hTitleFont member to set the font for the static control holding the title. The PSN_SETACTIVE handler enables the Back and Finish buttons.

The PSN_WIZBACK handler checks the IsBoxChecked member of the shared SHAREDWIZDATA structure to see if the check box on the second interior page is selected. If it is, the handler takes the user back to the first interior page, instead of the second interior page. As long as that check box is selected, the user will never see the second interior page.

Because there is no need for any cleanup, there is no PSN_WIZFINISH handler. The wizard is automatically destroyed when the Finish button is clicked. After the wizard is destroyed, control is returned to the WinMain function, which destroys the title font by using the DeleteObject function and then returns.

Summary

This chapter outlines the essential steps needed to implement a Wizard97-style wizard. The basic code that you need is given in the sample, and discussed in the second section. To go from this skeleton to a fully functioning wizard, all you need to do is use familiar dialog box programming techniques to create templates for your pages and implement the associated dialog box procedures.


Wiz97 Sample Code

The Wiz97 sample code implements a simple Wizard97-style wizard. It is implemented in the following source files:

  • Resource.h: Resource IDs
  • Wiz97.cpp: C source code
  • Wiz97.h: Header file for Wiz97.cpp, except for resource headers
  • Wiz97.mak: Makefile
  • Wiz97.rc: Resource file
  • Watermrk.bmp: Watermark bitmap (164 x 314 pixels)
  • Header.bmp: Header bitmap (49 x 49 pixels)


RESOURCE.H

//{{NO_DEPENDENCIES}}
// Microsoft Developer Studio generated include file.
// Used by Wiz97.rc
//
#define IDS_TITLE1                      1
#define IDS_SUBTITLE1                   2
#define IDS_TITLE2                      3
#define IDS_SUBTITLE2                   4
#define IDS_CAPTION                     5
#define IDB_BANNER                      102
#define IDB_WATERMARK                   103
#define IDD_INTRO                       107
#define IDD_INTERIOR1                   108
#define IDD_INTERIOR2                   109
#define IDD_END                         110
#define IDC_TITLE                       1000
#define IDC_INTRO_TEXT                  1001
#define IDC_RADIO1                      1002
#define IDC_RADIO2                      1003
#define IDC_RADIO3                      1004
#define IDC_EDIT2                       1006
#define IDC_EDIT3                       1007
#define IDC_EDIT4                       1008
#define IDC_CHECK1                      1010
#define IDC_GROUP1                      1011

// Next default values for new objects
//
#ifdef APSTUDIO_INVOKED
#ifndef APSTUDIO_READONLY_SYMBOLS
#define _APS_NEXT_RESOURCE_VALUE        104
#define _APS_NEXT_COMMAND_VALUE         40001
#define _APS_NEXT_CONTROL_VALUE         1012
#define _APS_NEXT_SYMED_VALUE           101
#endif
#endif

Built on: Thursday, October 21, 1999


WIZ97.CPP

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:Wiz97

--*/

#include "Wiz97.h"

INT WINAPI WinMain(HINSTANCE    hInstance,
                   HINSTANCE    hPrevInstance,
                   LPSTR        lpszCmdLine,
                   INT          nCmdShow
                   )
{
    PROPSHEETPAGE   psp =       {0}; //defines the property sheet pages
    HPROPSHEETPAGE  ahpsp[4] =  {0}; //an array to hold the page's HPROPSHEETPAGE handles
    PROPSHEETHEADER psh =       {0}; //defines the property sheet
    SHAREDWIZDATA wizdata =     {0}; //the shared data structure
    //
    //Create the Wizard pages
    //

    //Opening page

    psp.dwSize =        sizeof(psp);
    psp.dwFlags =       PSP_DEFAULT|PSP_HIDEHEADER;
    psp.hInstance =     hInstance;
    psp.lParam =        (LPARAM) &wizdata; //The shared data structure
    psp.pfnDlgProc =    IntroDlgProc;
    psp.pszTemplate =   MAKEINTRESOURCE(IDD_INTRO);

    ahpsp[0] =          CreatePropertySheetPage(&psp);

    //First interior page

    psp.dwFlags =           PSP_DEFAULT|PSP_USEHEADERTITLE|PSP_USEHEADERSUBTITLE;
    psp.pszHeaderTitle =    MAKEINTRESOURCE(IDS_TITLE1);
    psp.pszHeaderSubTitle = MAKEINTRESOURCE(IDS_SUBTITLE1);
    psp.pszTemplate =       MAKEINTRESOURCE(IDD_INTERIOR1);
    psp.pfnDlgProc =        IntPage1DlgProc;

    ahpsp[1] =              CreatePropertySheetPage(&psp);

    //Second interior page

    psp.dwFlags =           PSP_DEFAULT|PSP_USEHEADERTITLE|PSP_USEHEADERSUBTITLE;
    psp.pszHeaderTitle =    MAKEINTRESOURCE(IDS_TITLE2);
    psp.pszHeaderSubTitle = MAKEINTRESOURCE(IDS_SUBTITLE2);
    psp.pszTemplate =       MAKEINTRESOURCE(IDD_INTERIOR2);
    psp.pfnDlgProc =        IntPage2DlgProc;

    ahpsp[2] =              CreatePropertySheetPage(&psp);

    //Final page

    psp.dwFlags =       PSP_DEFAULT|PSP_HIDEHEADER;
    psp.pszTemplate =   MAKEINTRESOURCE(IDD_END);
    psp.pfnDlgProc =    EndDlgProc;

    ahpsp[3] =          CreatePropertySheetPage(&psp);

    //Create the property sheet

    psh.dwSize =            sizeof(psh);
    psh.hInstance =         hInstance;
    psh.hwndParent =        NULL;
    psh.phpage =            ahpsp;
    psh.dwFlags =           PSH_WIZARD97|PSH_WATERMARK|PSH_HEADER;
    psh.pszbmWatermark =    MAKEINTRESOURCE(IDB_WATERMARK);
    psh.pszbmHeader =       MAKEINTRESOURCE(IDB_BANNER);
    psh.nStartPage =        0;
    psh.nPages =            4;

    //Set up the font for the titles on the intro and ending pages

    NONCLIENTMETRICS ncm = {0};
    ncm.cbSize = sizeof(ncm);
    SystemParametersInfo(SPI_GETNONCLIENTMETRICS, 0, &ncm, 0);

    //Create the intro/end title font
    LOGFONT TitleLogFont = ncm.lfMessageFont;
    TitleLogFont.lfWeight = FW_BOLD;
    lstrcpy(TitleLogFont.lfFaceName, TEXT("Verdana Bold"));

    HDC hdc = GetDC(NULL); //gets the screen DC
    INT FontSize = 12;
    TitleLogFont.lfHeight = 0 - GetDeviceCaps(hdc, LOGPIXELSY) * FontSize / 72;
    wizdata.hTitleFont = CreateFontIndirect(&TitleLogFont);
    ReleaseDC(NULL, hdc);

    //Display the wizard

    PropertySheet(&psh);

    // Destroy the fonts
    DeleteObject(wizdata.hTitleFont);

    return 0;
}

BOOL CALLBACK IntroDlgProc (
                        HWND hwndDlg,
                        UINT uMsg,
                        WPARAM wParam,
                        LPARAM lParam
                        )
{
    //Process messages from the Welcome page

    //Retrieve the shared user data from GWL_USERDATA

    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            //Get the shared data from PROPSHEETPAGE lParam value
            //and load it into GWL_USERDATA

            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;

            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);

            //It's an intro/end page, so get the title font
            //from  the shared data and use it for the title control

            HWND hwndControl = GetDlgItem(hwndDlg, IDC_TITLE);
            SetWindowFont(hwndControl,pdata->hTitleFont, TRUE);
            break;
        }

    case WM_NOTIFY :
        {
        LPNMHDR lpnm = (LPNMHDR) lParam;

        switch (lpnm->code)
            {
            case PSN_SETACTIVE : //Enable the Next button
                PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_NEXT);
                break;

            case PSN_WIZNEXT :
                //Handle a Next button click here
                break;

            case PSN_RESET :
                //Handle a Cancel button click, if necessary
                break;

            default :
                break;
            }
        }
        break;

    default:
        break;
    }
    return 0;
}

BOOL CALLBACK IntPage1DlgProc (
                        HWND hwndDlg,
                        UINT uMsg,
                        WPARAM wParam,
                        LPARAM lParam
                        )
{

    //Process messages from the first interior page

    //Retrieve the shared user data from GWL_USERDATA

    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            //Get the PROPSHEETPAGE lParam value and load it into
            //DWL_USERDATA

            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;
            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);
            break;
        }

    case WM_COMMAND :
        switch(LOWORD (wParam))
        {
        case IDC_CHECK1 :
            pdata->IsBoxChecked = !(pdata->IsBoxChecked);
            break;

        case IDC_RADIO1 :

        case IDC_RADIO2 :

        case IDC_RADIO3 :
            pdata->IsButtonClicked = TRUE;
            break;

        default :
            break;

        }

        //If any of the radio buttons are clicked, or the
        //checkbox checked, enable the Next button

        if(pdata->IsBoxChecked || pdata->IsButtonClicked)
        {
            PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_NEXT);
        }

        else //otherwise, only enable the Back button
        {
            PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK);
        }

        break;

    case WM_NOTIFY :
        {
        LPNMHDR lpnm = (LPNMHDR) lParam;

        switch (lpnm->code)
            {
            case PSN_SETACTIVE : //Enable the appropriate buttons

                //If a radio button has been clicked or the
                //checkbox checked, enable Back and Next
                if(pdata->IsBoxChecked || pdata->IsButtonClicked)
                {
                    PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_NEXT);
                }

                else //Otherwise, only enable Back
                {
                    PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK);
                }
                break;

            case PSN_WIZNEXT :

                //If the checkbox is checked, jump to the final page

                if(pdata->IsBoxChecked)
                {
                    SetWindowLong(hwndDlg, DWL_MSGRESULT, IDD_END);
                    return TRUE;
                }
                break;

            case PSN_WIZBACK :
                //Handle a Back button click, if necessary
                break;

            case PSN_RESET :
                //Handle a Cancel button click, if necessary
                break;

            default :
                break;
            }
        }
        break;

    default:
        break;
    }
    return 0;
}

BOOL CALLBACK IntPage2DlgProc (
                        HWND hwndDlg,
                        UINT uMsg,
                        WPARAM wParam,
                        LPARAM lParam
                        )
{

    //Process messages from the second interior page

    //Retrieve the shared user data from GWL_USERDATA

    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            //Get the PROPSHEETPAGE lParam value and load it into
            //DWL_USERDATA

            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;
            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);
            break;
        }

    case WM_NOTIFY :
        {
        LPNMHDR lpnm = (LPNMHDR) lParam;

        switch (lpnm->code)
            {
            case PSN_SETACTIVE : //Enable the Next and Back buttons

                PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_NEXT);
                break;

            case PSN_WIZNEXT :
                //Handle a Next button click, if necessary
                break;

            case PSN_WIZBACK :
                //Handle a Back button click, if necessary
                break;

            case PSN_RESET :
                //Handle a Cancel button click, if necessary
                break;

            default :
                break;
            }
        }
        break;

    default:
        break;
    }
    return 0;
}

BOOL CALLBACK EndDlgProc (
                        HWND hwndDlg,
                        UINT uMsg,
                        WPARAM wParam,
                        LPARAM lParam
                        )
{

    //Process messages from the Completion page

    //Retrieve the shared user data from GWL_USERDATA

    LPSHAREDWIZDATA pdata = (LPSHAREDWIZDATA) GetWindowLong(hwndDlg, GWL_USERDATA);

    switch (uMsg)
    {
    case WM_INITDIALOG :
        {
            //Get the shared data from PROPSHEETPAGE lParam value
            //and load it into GWL_USERDATA

            pdata = (LPSHAREDWIZDATA) ((LPPROPSHEETPAGE) lParam) -> lParam;
            SetWindowLong(hwndDlg, GWL_USERDATA, (DWORD_PTR) pdata);

            //It's an intro/end page, so get the title font
            //from  userdata and use it on the title control

            HWND hwndControl = GetDlgItem(hwndDlg, IDC_TITLE);
            SetWindowFont(hwndControl,pdata->hTitleFont, TRUE);
            break;
        }

    case WM_NOTIFY :
        {
        LPNMHDR lpnm = (LPNMHDR) lParam;

        switch (lpnm->code)
            {
            case PSN_SETACTIVE : //Enable the correct buttons on for the active page

                PropSheet_SetWizButtons(GetParent(hwndDlg), PSWIZB_BACK | PSWIZB_FINISH);
                break;

            case PSN_WIZBACK :

                 //If the checkbox was checked, jump back
                 //to the first interior page, not the second
                if(pdata->IsBoxChecked)
                {
                    SetWindowLong(hwndDlg, DWL_MSGRESULT, IDD_INTERIOR1);
                    return TRUE;
                }
                break;

            case PSN_WIZFINISH :
                //Handle a Finish button click, if necessary
                break;

            case PSN_RESET :
                //Handle a Cancel button click, if necessary
                break;

            default :
                break;
            }
        }
    break;

    default:
        break;
    }
    return 0;
}

Built on: Thursday, October 21, 1999


WIZ97.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample New Wizard header

--*/
#ifndef _WIZARD_HXX_
#define _WIZARD_HXX_

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define INC_OLE2
#include <windows.h>
#include <windowsx.h>
#include <prsht.h>
#include <tchar.h>
#include <windef.h>
#include "resource.h"

#define LASTPAGE 3 //index of the last page

INT WINAPI
WinMain(
    HINSTANCE   hInstance,
    HINSTANCE   hPrevInstance,
    LPSTR       lpszCmdLine,
    INT         nCmdShow
    );

INT CALLBACK
IntroDlgProc(
    IN HWND     hwndDlg,
    IN UINT     uMsg,
    IN WPARAM   wParam,
    IN LPARAM   lParam
    );

INT CALLBACK
IntPage1DlgProc
(
    IN HWND     hwndDlg,
    IN UINT     uMsg,
    IN WPARAM   wParam,
    IN LPARAM   lParam
    );

INT CALLBACK
IntPage2DlgProc(
    IN HWND     hwndDlg,
    IN UINT     uMsg,
    IN WPARAM   wParam,
    IN LPARAM   lParam
    );

INT CALLBACK
EndDlgProc(
    IN HWND     hwndDlg,
    IN UINT     uMsg,
    IN WPARAM   wParam,
    IN LPARAM   lParam
    );

typedef struct SHAREDWIZDATA {
    HFONT hTitleFont; //The title font for the Welcome and Completion pages
    BOOL IsBoxChecked; //The state of the first interior page's check box
    BOOL IsButtonClicked; //The state of the first interior page's group box
    //other shared data added here
} SHAREDWIZDATA, *LPSHAREDWIZDATA;

#endif

Built on: Thursday, October 21, 1999


WIZ97.MAK

# Microsoft Developer Studio Generated NMAKE File, Based on Wiz97.dsp
!IF "$(CFG)" == ""
CFG=Wiz97 - Win32 Debug
!MESSAGE No configuration specified. Defaulting to Wiz97 - Win32 Debug.
!ENDIF

!IF "$(CFG)" != "Wiz97 - Win32 Release" && "$(CFG)" != "Wiz97 - Win32 Debug"
!MESSAGE Invalid configuration "$(CFG)" specified.
!MESSAGE You can specify a configuration when running NMAKE
!MESSAGE by defining the macro CFG on the command line. For example:
!MESSAGE
!MESSAGE NMAKE /f "Wiz97.mak" CFG="Wiz97 - Win32 Debug"
!MESSAGE
!MESSAGE Possible choices for configuration are:
!MESSAGE
!MESSAGE "Wiz97 - Win32 Release" (based on "Win32 (x86) Application")
!MESSAGE "Wiz97 - Win32 Debug" (based on "Win32 (x86) Application")
!MESSAGE
!ERROR An invalid configuration is specified.
!ENDIF

!IF "$(OS)" == "Windows_NT"
NULL=
!ELSE
NULL=nul
!ENDIF

!IF  "$(CFG)" == "Wiz97 - Win32 Release"

OUTDIR=.\Release
INTDIR=.\Release
# Begin Custom Macros
OutDir=.\Release
# End Custom Macros

ALL : "$(OUTDIR)\Wiz97.exe"

CLEAN :
    -@erase "$(INTDIR)\vc60.idb"
    -@erase "$(INTDIR)\Wiz97.obj"
    -@erase "$(INTDIR)\Wiz97.res"
    -@erase "$(OUTDIR)\Wiz97.exe"

"$(OUTDIR)" :
    if not exist "$(OUTDIR)/$(NULL)" mkdir "$(OUTDIR)"

CPP=cl.exe
CPP_PROJ=/nologo /ML /W3 /GX /O2 /D "WIN32" /D "NDEBUG" /D "_WINDOWS" /D "_MBCS" /Fp"$(INTDIR)\Wiz97.pch" /YX /Fo"$(INTDIR)\\" /Fd"$(INTDIR)\\" /FD /c

.c{$(INTDIR)}.obj::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cpp{$(INTDIR)}.obj::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cxx{$(INTDIR)}.obj::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.c{$(INTDIR)}.sbr::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cpp{$(INTDIR)}.sbr::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cxx{$(INTDIR)}.sbr::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

MTL=midl.exe
MTL_PROJ=/nologo /D "NDEBUG" /mktyplib203 /win32
RSC=rc.exe
RSC_PROJ=/l 0x409 /fo"$(INTDIR)\Wiz97.res" /d "NDEBUG"
BSC32=bscmake.exe
BSC32_FLAGS=/nologo /o"$(OUTDIR)\Wiz97.bsc"
BSC32_SBRS= \

LINK32=link.exe
LINK32_FLAGS=kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib /nologo /subsystem:windows /incremental:no /pdb:"$(OUTDIR)\Wiz97.pdb" /machine:I386 /out:"$(OUTDIR)\Wiz97.exe"
LINK32_OBJS= \
    "$(INTDIR)\Wiz97.obj" \
    "$(INTDIR)\Wiz97.res"

"$(OUTDIR)\Wiz97.exe" : "$(OUTDIR)" $(DEF_FILE) $(LINK32_OBJS)
    $(LINK32) @<<
  $(LINK32_FLAGS) $(LINK32_OBJS)
<<

!ELSEIF  "$(CFG)" == "Wiz97 - Win32 Debug"

OUTDIR=.\Debug
INTDIR=.\Debug
# Begin Custom Macros
OutDir=.\Debug
# End Custom Macros

ALL : "$(OUTDIR)\Wiz97.exe"

CLEAN :
    -@erase "$(INTDIR)\vc60.idb"
    -@erase "$(INTDIR)\vc60.pdb"
    -@erase "$(INTDIR)\Wiz97.obj"
    -@erase "$(INTDIR)\Wiz97.res"
    -@erase "$(OUTDIR)\Wiz97.exe"
    -@erase "$(OUTDIR)\Wiz97.ilk"
    -@erase "$(OUTDIR)\Wiz97.pdb"

"$(OUTDIR)" :
    if not exist "$(OUTDIR)/$(NULL)" mkdir "$(OUTDIR)"

CPP=cl.exe
CPP_PROJ=/nologo /MLd /W3 /Gm /GX /ZI /Od /D "WIN32" /D "_DEBUG" /D "_WINDOWS" /D "_MBCS" /Fp"$(INTDIR)\Wiz97.pch" /YX /Fo"$(INTDIR)\\" /Fd"$(INTDIR)\\" /FD /GZ /c

.c{$(INTDIR)}.obj::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cpp{$(INTDIR)}.obj::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cxx{$(INTDIR)}.obj::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.c{$(INTDIR)}.sbr::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cpp{$(INTDIR)}.sbr::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

.cxx{$(INTDIR)}.sbr::
   $(CPP) @<<
   $(CPP_PROJ) $<
<<

MTL=midl.exe
MTL_PROJ=/nologo /D "_DEBUG" /mktyplib203 /win32
RSC=rc.exe
RSC_PROJ=/l 0x409 /fo"$(INTDIR)\Wiz97.res" /d "_DEBUG"
BSC32=bscmake.exe
BSC32_FLAGS=/nologo /o"$(OUTDIR)\Wiz97.bsc"
BSC32_SBRS= \

LINK32=link.exe
LINK32_FLAGS=kernel32.lib user32.lib gdi32.lib winspool.lib comdlg32.lib advapi32.lib shell32.lib ole32.lib oleaut32.lib uuid.lib odbc32.lib odbccp32.lib comctl32.lib /nologo /subsystem:windows /incremental:yes /pdb:"$(OUTDIR)\Wiz97.pdb" /debug /machine:I386 /out:"$(OUTDIR)\Wiz97.exe" /pdbtype:sept
LINK32_OBJS= \
    "$(INTDIR)\Wiz97.obj" \
    "$(INTDIR)\Wiz97.res"

"$(OUTDIR)\Wiz97.exe" : "$(OUTDIR)" $(DEF_FILE) $(LINK32_OBJS)
    $(LINK32) @<<
  $(LINK32_FLAGS) $(LINK32_OBJS)
<<

!ENDIF

!IF "$(NO_EXTERNAL_DEPS)" != "1"
!IF EXISTS("Wiz97.dep")
!INCLUDE "Wiz97.dep"
!ELSE
!MESSAGE Warning: cannot find "Wiz97.dep"
!ENDIF
!ENDIF

!IF "$(CFG)" == "Wiz97 - Win32 Release" || "$(CFG)" == "Wiz97 - Win32 Debug"
SOURCE=.\Wiz97.cpp

"$(INTDIR)\Wiz97.obj" : $(SOURCE) "$(INTDIR)"

SOURCE=.\Wiz97.rc

"$(INTDIR)\Wiz97.res" : $(SOURCE) "$(INTDIR)"
    $(RSC) $(RSC_PROJ) $(SOURCE)

!ENDIF

Built on: Thursday, October 21, 1999


WIZ97.RC

//Microsoft Developer Studio generated resource script.
//
#include "resource.h"

#define APSTUDIO_READONLY_SYMBOLS
/////////////////////////////////////////////////////////////////////////////
//
// Generated from the TEXTINCLUDE 2 resource.
//
#include "afxres.h"

/////////////////////////////////////////////////////////////////////////////
#undef APSTUDIO_READONLY_SYMBOLS

/////////////////////////////////////////////////////////////////////////////
// English (U.S.) resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_ENU)
#ifdef _WIN32
LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US
#pragma code_page(1252)
#endif //_WIN32

#ifdef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// TEXTINCLUDE
//

1 TEXTINCLUDE DISCARDABLE
BEGIN
    "resource.h\0"
END

2 TEXTINCLUDE DISCARDABLE
BEGIN
    "#include ""afxres.h""\r\n"
    "\0"
END

3 TEXTINCLUDE DISCARDABLE
BEGIN
    "\r\n"
    "\0"
END

#endif    // APSTUDIO_INVOKED

/////////////////////////////////////////////////////////////////////////////
//
// Dialog
//

IDD_INTRO DIALOG DISCARDABLE  0, 0, 317, 193
STYLE WS_CHILD | WS_DISABLED | WS_CAPTION
CAPTION "Welcome Page"
FONT 8, "MS Sans Serif"
BEGIN
    LTEXT           "Welcome to Wiz97",IDC_TITLE,115,9,189,31,NOT WS_GROUP
    LTEXT           "Some explanatory text",IDC_INTRO_TEXT,115,40,189,18
END

IDD_INTERIOR1 DIALOG DISCARDABLE  0, 0, 317, 143
STYLE WS_CHILD | WS_DISABLED | WS_CAPTION
CAPTION "First Interior Page"
FONT 8, "MS Sans Serif"
BEGIN
    LTEXT           "You must click the checkbox or a radio button to advance to the next page",
                    IDC_STATIC,21,1,282,14
    CONTROL         "A  radio button",IDC_RADIO1,"Button",BS_AUTORADIOBUTTON,
                    28,41,62,10
    CONTROL         "Another radio Button",IDC_RADIO2,"Button",
                    BS_AUTORADIOBUTTON,28,61,81,10
    CONTROL         "A third radio button",IDC_RADIO3,"Button",
                    BS_AUTORADIOBUTTON,28,80,75,10
    GROUPBOX        "A Group of radio buttons",IDC_GROUP1,21,24,119,74,
                    WS_GROUP
    CONTROL         "Go directly to the last page",IDC_CHECK1,"Button",
                    BS_AUTOCHECKBOX | WS_TABSTOP,194,61,100,10
END

IDD_INTERIOR2 DIALOG DISCARDABLE  0, 0, 317, 143
STYLE WS_CHILD | WS_DISABLED | WS_CAPTION
CAPTION "Second Interior Page"
FONT 8, "MS Sans Serif"
BEGIN
    LTEXT           "Some explanatory text",IDC_STATIC,21,1,70,8
    LTEXT           "An Edit Box",IDC_STATIC,21,38,38,8
    LTEXT           "Another Edit Box",IDC_STATIC,21,67,54,8
    LTEXT           "A Third Edit Box",IDC_STATIC,21,96,52,8
    EDITTEXT        IDC_EDIT2,108,38,86,14,ES_AUTOHSCROLL
    EDITTEXT        IDC_EDIT3,108,67,86,14,ES_AUTOHSCROLL
    EDITTEXT        IDC_EDIT4,108,96,86,14,ES_AUTOHSCROLL
END

IDD_END DIALOG DISCARDABLE  0, 0, 317, 193
STYLE WS_CHILD | WS_DISABLED | WS_CAPTION
CAPTION "Completion Page"
FONT 8, "MS Sans Serif"
BEGIN
    LTEXT           "Completing Wiz97",IDC_TITLE,115,8,195,37
    LTEXT           "Some Explanatory Text",IDC_STATIC,115,58,195,128
END

/////////////////////////////////////////////////////////////////////////////
//
// DESIGNINFO
//

#ifdef APSTUDIO_INVOKED
GUIDELINES DESIGNINFO DISCARDABLE
BEGIN
    IDD_INTRO, DIALOG
    BEGIN
        LEFTMARGIN, 7
        RIGHTMARGIN, 310
        VERTGUIDE, 115
        VERTGUIDE, 304
        TOPMARGIN, 7
        BOTTOMMARGIN, 186
        HORZGUIDE, 8
        HORZGUIDE, 40
    END

    IDD_INTERIOR1, DIALOG
    BEGIN
        LEFTMARGIN, 28
        RIGHTMARGIN, 310
        VERTGUIDE, 28
        VERTGUIDE, 189
        BOTTOMMARGIN, 136
    END

    IDD_INTERIOR2, DIALOG
    BEGIN
        LEFTMARGIN, 7
        RIGHTMARGIN, 310
        VERTGUIDE, 21
        VERTGUIDE, 108
        VERTGUIDE, 194
        TOPMARGIN, 4
        BOTTOMMARGIN, 136
        HORZGUIDE, 38
        HORZGUIDE, 68
        HORZGUIDE, 98
    END

    IDD_END, DIALOG
    BEGIN
        LEFTMARGIN, 7
        RIGHTMARGIN, 310
        VERTGUIDE, 115
        TOPMARGIN, 7
        BOTTOMMARGIN, 186
    END
END
#endif    // APSTUDIO_INVOKED

/////////////////////////////////////////////////////////////////////////////
//
// Bitmap
//

IDB_BANNER              BITMAP  DISCARDABLE     "header.bmp"
IDB_WATERMARK           BITMAP  DISCARDABLE     "watermrk.bmp"

/////////////////////////////////////////////////////////////////////////////
//
// String Table
//

STRINGTABLE DISCARDABLE
BEGIN
    IDS_TITLE1              "Title: First Interior Page"
    IDS_SUBTITLE1           "Subtitle: Some explanatory text..."
    IDS_TITLE2              "Title: Second Interior Page"
    IDS_SUBTITLE2           "Subtitle: Some explanatory text..."
END

#endif    // English (U.S.) resources
/////////////////////////////////////////////////////////////////////////////

#ifndef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// Generated from the TEXTINCLUDE 3 resource.
//

/////////////////////////////////////////////////////////////////////////////
#endif    // not APSTUDIO_INVOKED

Built on: Thursday, October 21, 1999


Window Classes

The following window class names are provided by the common control library:
ANIMATE_CLASS | Creates animation controls. These controls silently display an audio video interleaved (AVI) clip.
DATETIMEPICK_CLASS | Creates date and time picker controls. These controls provide a simple and intuitive interface to exchange date and time information with a user.
HOTKEY_CLASS | Creates hot key controls. These controls make it easy for the user to define hot keys.
MONTHCAL_CLASS | Creates month calendar controls. These controls provide a simple and intuitive way for a user to select a date from a familiar interface.
PROGRESS_CLASS | Creates progress bars. These controls indicate the progress of a lengthy operation.
REBARCLASSNAME | Creates rebar controls. These controls act as a container for child windows.
STATUSCLASSNAME | Creates status windows. These controls display status information in a horizontal window.
TOOLBARCLASSNAME | Creates toolbars. These controls contain buttons that carry out menu commands.
TOOLTIPS_CLASS | Creates ToolTip controls. These controls display a small pop-up window containing a line of text that describes the purpose of a tool in an application.
TRACKBAR_CLASS | Creates trackbars. These controls let the user select from a range of values by moving a slider.
UPDOWN_CLASS | Creates up-down controls. These controls combine a pair of arrows with an edit control. Clicking the arrows increments or decrements the value in the edit control.
WC_COMBOBOXEX | Creates ComboBoxEx controls. These controls provide an extension of the combo box control that provides native support for item images.
WC_HEADER | Creates header controls. These controls display headings at the top of columns of information and let the user sort the information by clicking the headings.
WC_IPADDRESS | Creates IP address controls. These controls are similar to an edit control, but they enable you to enter a numeric address in Internet protocol (IP) format.
WC_LISTVIEW | Creates list-view controls. These controls display a collection of items, each consisting of an icon and a label, and provide several ways to arrange the items.
WC_PAGESCROLLER | Creates pager controls. These controls are used to contain and scroll another window.
WC_TABCONTROL | Creates tab controls. These controls define multiple pages for the same area of a window or dialog box. Each page consists of a set of information or a group of controls that an application displays when the user selects the corresponding tab.
WC_TREEVIEW | Creates tree-view controls. These controls display a hierarchical list of items. Each item consists of a label and an optional bitmap.


Styles

Following are the common control styles. Except where noted, these styles apply to header controls, toolbar controls, and status windows.
CCS_ADJUSTABLE | Enables a toolbar's built-in customization features, which enable the user to drag a button to a new position or to remove a button by dragging it off the toolbar. In addition, the user can double-click the toolbar to display the Customize Toolbar dialog box, which enables the user to add, delete, and rearrange toolbar buttons.
CCS_BOTTOM | Causes the control to position itself at the bottom of the parent window's client area and sets the width to be the same as the parent window's width. Status windows have this style by default.
CCS_LEFT | Version 4.70. Causes the control to be displayed vertically on the left side of the parent window.
CCS_NODIVIDER | Prevents a two-pixel highlight from being drawn at the top of the control.
CCS_NOMOVEX | Version 4.70. Causes the control to resize and move itself vertically, but not horizontally, in response to a WM_SIZE message. If CCS_NORESIZE is used, this style does not apply.
CCS_NOMOVEY | Causes the control to resize and move itself horizontally, but not vertically, in response to a WM_SIZE message. If CCS_NORESIZE is used, this style does not apply. Header windows have this style by default.
CCS_NOPARENTALIGN | Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent. If CCS_TOP or CCS_BOTTOM is also used, the height is adjusted to the default, but the position and width remain unchanged.
CCS_NORESIZE | Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height specified in the request for creation or sizing.
CCS_RIGHT | Version 4.70. Causes the control to be displayed vertically on the right side of the parent window.
CCS_TOP | Causes the control to position itself at the top of the parent window's client area and sets the width to be the same as the parent window's width. Toolbars have this style by default.
CCS_VERT | Version 4.70. Causes the control to be displayed vertically.


GetEffectiveClientRect

Calculates the dimensions of a rectangle in the client area.

void GetEffectiveClientRect(
    HWND hWnd,
    LPRECT lprc,
    LPINT lpInfo
   );

Parameters

hWnd
Handle to the window that has the client area to check.
lprc
Address of a RECT structure that receives the dimensions of the rectangle.
lpInfo
Address of an array of integers that identify controls in the client area. Each control requires a pair of consecutive elements. The first element of the pair must be nonzero and the second element of the pair must be the control identifier. The last element pair in the array must be zero to identify the end of the array.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


GetMUILanguage

Returns the language currently in use by the common controls for a particular process.

LANGID GetMUILanguage( VOID );

Parameters

None

Return Values

Returns the the LANGID of the language an application has specified for the common controls by calling InitMUILanguage. GetMUILanguage returns the value for the process that it is called from. If InitMUILanguage has not been called or was not called from the same process, GetMUILanguage returns the language-neutral LANGID, MAKELANGID(LANG_NEUTRAL, SUBLANG_NEUTRAL).

Remarks

See National Language Support for further discussion of localization.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


InitCommonControls

Registers and initializes the common control window classes. This function is obsolete. New applications should use the InitCommonControlsEx function.

void InitCommonControls(VOID);

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


InitCommonControlsEx

Registers specific common control classes from the common control dynamic-link library (DLL).

BOOL InitCommonControlsEx(
    LPINITCOMMONCONTROLSEX lpInitCtrls
);

Parameters

lpInitCtrls
Address of an INITCOMMONCONTROLSEX structure that contains information specifying which control classes will be registered.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Note The effect of each call to InitCommonControlsEx is cumulative. For example, if InitCommonControlsEx is called with the ICC_UPDOWN_CLASS flag, then is later called with the ICC_HOTKEY_CLASS flag, the result is that both the up-down and hot key common control classes are registered and available to the application.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


InitMUILanguage

Enables an application to specify a language to be used with the common controls that is different than the system language.

VOID InitMUILanguage(
  LANGID uiLang
);

Parameters

uiLang
The LANGID value of the language to be used by the common controls.

Return Values

None

Remarks

This function enables an application to override the system language setting, and specify a different language for the common controls. The selected language only applies to the process that InitMUILanguage is called from. See National Language Support for further discussion of localization.

See Also

GetMUILanguage

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ShowHideMenuCtl

Sets or removes the specified menu item's check mark attribute and shows or hides the corresponding control. The function adds a check mark to the specified menu item if it does not have one and then displays the corresponding control. If the menu item already has a check mark, the function removes the check mark and hides the corresponding control.

BOOL ShowHideMenuCtl(
    HWND hWnd,
    UINT_PTR uFlags,
    LPINT lpInfo
   );

Parameters

hWnd
Handle to the window that contains the menu and controls.
uFlags
Identifier of the menu item to receive or lose a check mark.
lpInfo
Address of an array that contains pairs of values. The second value in the first pair must be the handle to the application's main menu. Each subsequent pair consists of a menu item identifier and a control window identifier. The function searches the array for a value that matches uFlags and, if the value is found, checks or unchecks the menu item and shows or hides the corresponding control.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


CCM_GETUNICODEFORMAT

The CCM_GETUNICODEFORMAT message retrieves the Unicode character format flag for the control.

CCM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Parameters

This message has no parameters.

Return Values

Returns the Unicode format flag for the control. If this value is nonzero, the control is using Unicode characters. If this value is zero, the control is using ANSI characters.

Example

The following function can be used with a Microsoft® Windows® 95 or Microsoft® Windows® 98 system to test whether or not a property sheet control supports Unicode. For more information about testing controls for Unicode support, see Remarks.

BOOL IsComctl32Unicode(void)
{
    PROPSHEETPAGEW pspW = { PROPSHEETPAGEW_V1_SIZE };
    HPROPSHEETPAGE hpage = CreatePropertySheetW(&pspW);
    if (hpage) {
        DestroyPropertySheetPage(hpage);
        return TRUE;
    }
    else {
        return FALSE;
    }
)

Remarks

The Unicode format flag is used by Microsoft® Windows NT® systems with version 4.71 of Comctl32.dll or later. This message is, thus, supported by Windows 2000 and later, and by Windows NT 4 with Microsoft® Internet Explorer 4.0 or later. It is only useful on Windows 95 or Windows 98 systems with version 5.80 or later of Comctl32.dll. This means that they must have Internet Explorer 5 or later installed. Windows 95 and Windows 98 systems with earlier versions of Internet Explorer ignore the Unicode format flag, and its value has no bearing on whether a control supports Unicode. With these systems, you will instead need to test something that requires Unicode support.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.

See Also

CCM_SETUNICODEFORMAT


CCM_GETVERSION

Returns the version number for a control set by the most recent CCM_SETVERSION message.

CCM_GETVERSION
    wParam = 0;
    lParam = 0;

Parameters

None

Return Values

Returns the version number set by the most recent CCM_SETVERSION message. If no such message has been sent, it returns zero.

Remarks

This message does not return the DLL version. See Shell Versions for a discussion of how to use DllGetVersion to retrieve the current DLL version.

Note: The version number is set on a control by control basis, and may not be the same for all controls.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.

See Also


CCM_SETUNICODEFORMAT

THE CCM_SETUNICODEFORMAT message sets the Unicode character format flag for the control. This message enables you to change the character set used by the control at run time rather than having to re-create the control.

CCM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Value that determines the character set that is used by the control. If this value is TRUE, the control will use Unicode characters. If this value is FALSE, the control will use ANSI characters.

Return Values

Returns the previous Unicode format flag for the control.

Remarks

The Unicode format flag is used by Microsoft® Windows NT® systems with version 4.71 of Comctl32.dll or later. This message is thus supported by by Windows 2000 and later, and by Windows NT 4 with Microsoft® Internet Explorer 4.0 or later. It is only useful on Microsoft® Windows® 95 or Microsoft® Windows® 98 systems with version 5.80 or later of Comctl32.dll. This means that they must have Internet Explorer 5 or later installed. Windows 95 and Windows 98 systems with earlier versions of Internet Explorer ignore the Unicode format flag, and its value has no bearing on whether or not a control supports Unicode. For a discussion about how to test whether a control supports Unicode, see CCM_GETUNICODEFORMAT.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.

See Also

CCM_GETUNICODEFORMAT


CCM_SETVERSION

This message is used to inform the control that you are expecting a behavior associated with a particular version.

CCM_SETVERSION
    wParam = (int) iVersion;
    lParam = 0;

Parameters

iVersion
The version number.

Return Values

Returns the version specified in the previous CCM_SETVERSION message. If iVersion is set to a value greater than the current DLL version, it returns -1.

Remarks

In a few cases, a control may behave differently, depending on the version. This primarily applies to bugs that were fixed in later versions. The CCM_SETVERSION enables you to inform the control which behavior is expected. You can determine which version you have specified by sending a CCM_GETVERSION message. For an example of how to use this message, see Custom Draw

Note: This message only sets the version number for the control to which it is sent.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.

See Also


WM_NOTIFY

The WM_NOTIFY message is sent by a common control to its parent window when an event has occurred or the control requires some information.

WM_NOTIFY
    idCtrl = (int) wParam;
    pnmh = (LPNMHDR) lParam;

Parameters

idCtrl
Identifier of the common control sending the message. This identifier is not guaranteed to be unique. An application should use the hwndFrom or idFrom member of the NMHDR structure (passed as the lParam parameter) to identify the control.
pnmh
Pointer to an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.

Return Values

The return value is ignored except for notification messages that specify otherwise.

Remarks

If the message handler is in a dialog box procedure, you must use the SetWindowLong function with DWL_MSGRESULT to set a return value.

The standard Microsoft® Windows® controls (edit controls, combo boxes, list boxes, buttons, scroll bars, and static controls) do not send WM_NOTIFY messages. To determine if a common control will send a WM_NOTIFY message and, if it will, which notification codes it will send, see the documentation for the control.

For Windows 2000 and later systems, the WM_NOTIFY message cannot be sent between processes.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in winuser.h.


WM_NOTIFYFORMAT

Used to determine if a window accepts ANSI or Unicode structures in the WM_NOTIFY notification message. WM_NOTIFYFORMAT messages are sent from a common control to its parent window and from the parent window to the common control.

WM_NOTIFYFORMAT
    hwndFrom = (HWND) wParam;
    Command = lParam;

Parameters

hwndFrom
Handle to the window that is sending the WM_NOTIFYFORMAT message. If Command is NF_QUERY, this parameter is the handle to a control. If Command is NF_REQUERY, this parameter is the handle to the parent window of a control.
Command
Command value that specifies the nature of the WM_NOTIFYFORMAT message. This will be one of the following values:
NF_QUERY | The message is a query to determine whether ANSI or Unicode structures should be used in WM_NOTIFY messages. This command is sent from a control to its parent window during the creation of a control and in response to an NF_REQUERY command.
NF_REQUERY | The message is a request for a control to send an NF_QUERY form of this message to its parent window. This command is sent from the parent window. The parent window is asking the control to requery it about the type of structures to use in WM_NOTIFY messages.

Return Values

Returns one of the following:
NFR_ANSI | ANSI structures should be used in WM_NOTIFY messages sent by the control.
NFR_UNICODE | Unicode structures should be used in WM_NOTIFY messages sent by the control.
0 | An error occurred.

If Command is NF_REQUERY, the return value is the result of the requery operation.

Remarks

When a common control is created, the control sends a WM_NOTIFYFORMAT message to its parent window to determine the type of structures to use in WM_NOTIFY messages. If the parent window does not handle this message, the DefWindowProc function responds according to the type of the parent window. That is, if the parent window is a Unicode window, DefWindowProc returns NFR_UNICODE, and if the parent window is an ANSI window, DefWindowProc returns NFR_ANSI. If the parent window is a dialog box and does not handle this message, the DefDlgProc function similarly responds according to the type of the dialog box (Unicode or ANSI).

A parent window can change the type of structures a common control uses in WM_NOTIFY messages by setting lParam to NF_REQUERY and sending a WM_NOTIFYFORMAT message to the control. This causes the control to send an NF_QUERY form of the WM_NOTIFYFORMAT message to the parent window.

All common controls will send WM_NOTIFYFORMAT messages. However, the standard Windows controls (edit controls, combo boxes, list boxes, buttons, scroll bars, and static controls) do not.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in winuser.h.


FORWARD_WM_NOTIFY

Sends or posts the WM_NOTIFY message.

VOID FORWARD_WM_NOTIFY(
    hwnd,
    idFrom,
    pnmhdr,
    fn
   );

Parameters

hwnd
Handle to the window that receives the WM_NOTIFY message.
idFrom
Identifier of the control sending the message.
pnmhdr
Address of an NMHDR structure that contains the notification code and additional information. For some notification messages, this parameter points to a larger structure that has the NMHDR structure as its first member.
fn
Function that sends or posts the WM_NOTIFY message. This parameter can be either the SendMessage or PostMessage function.

Return Values

Returns a value whose meaning depends on the fn parameter.

Remarks

The FORWARD_WM_NOTIFY macro is defined as follows:

#define FORWARD_WM_NOTIFY(hwnd, idFrom, pnmhdr, fn) \
    (void)(fn)((hwnd), WM_NOTIFY, (WPARAM)(int)(id), \
    (LPARAM)(NMHDR FAR*)(pnmhdr))

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HANDLE_WM_NOTIFY

Calls a function that processes the WM_NOTIFY message.

HANDLE_WM_NOTIFY(
    hwnd,
    wParam,
    lParam,
    fn
   );

Parameters

hwnd
Handle to the window that received WM_NOTIFY.
wParam
First parameter of WM_NOTIFY.
lParam
Second parameter of WM_NOTIFY.
fn
Function that is to process WM_NOTIFY.

Return Values

Returns a value whose meaning depends on the fn parameter.

Remarks

The HANDLE_WM_NOTIFY macro is defined as follows:

#define HANDLE_WM_NOTIFY(hwnd, wParam, lParam, fn) \
    (fn)((hwnd), (int)(wParam), (NMHDR FAR*)(lParam))

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


INDEXTOSTATEIMAGEMASK

Prepares the index of a state image so that a tree-view control or list-view control can use the index to retrieve the state image for an item.

UINT INDEXTOSTATEIMAGEMASK(
    UINT i
   );

Parameters

i
Index of a state image.

Remarks

The INDEXTOSTATEIMAGEMASK macro is defined as follows:

#define INDEXTOSTATEIMAGEMASK(i) ((i) << 12)

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CHAR

The NM_CHAR notification message is sent by a control when a character key is processed. This notification message is sent in the form of a WM_NOTIFY message.

NM_CHAR
    lpnmc = (LPNMCHAR) lParam;

Parameters

lpnmc
Pointer to an NMCHAR structure that contains additional information about the character that caused the notification message.

Return Values

The return value is ignored by most controls. For more information, see the documentation for the individual controls.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.

See Also

NM_CHAR (toolbar)


NM_CLICK

Notifies a control's parent window that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.

NM_CLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in winuser.h.


NM_DBLCLK

Notifies a control's parent window that the user has double-clicked the left mouse button within the control. NM_DBLCLK is sent in the form of a WM_NOTIFY message.

NM_DBLCLK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in winuser.h.


NM_HOVER

Sent by a control when the mouse hovers over an item. This notification message is sent in the form of a WM_NOTIFY message.

NM_HOVER
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Unless otherwise specified, return zero to allow the control to process the hover normally, or nonzero to prevent the hover from being processed.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_KEYDOWN

Sent by a control when the control has the keyboard focus and the user presses a key. This notification message is sent in the form of a WM_NOTIFY message.

NM_KEYDOWN
    lpnmk = (LPNMKEY) lParam;

Parameters

lpnmk
Address of an NMKEY structure that contains additional information about the key that caused the notification message.

Return Values

Return nonzero to prevent the control from processing the key, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_KILLFOCUS

Notifies a control's parent window that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.

NM_KILLFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in winuser.h.


NM_NCHITTEST

Sent by a control when the control receives a WM_NCHITTEST message. This notification message is sent in the form of a WM_NOTIFY message.

NM_NCHITTEST
    lpnmmouse = (LPNMMOUSE) lParam;

Parameters

lpnmmouse
Address of a NMMOUSE structure that contains information about the notification. The pt member contains the mouse coordinates of the hit test message.

Return Values

Unless otherwise specified, return zero to allow the control to perform default processing of the hit test message, or return one of the HT* values documented under WM_NCHITTEST to override the default hit test processing.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_OUTOFMEMORY

Notifies a control's parent window that the control could not complete an operation because there was not enough memory available. NM_OUTOFMEMORY is sent in the form of a WM_NOTIFY message.

NM_OUTOFMEMORY
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RCLICK

Notifies a control's parent window that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to not allow the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RDBLCLK

Notifies a control's parent window that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.

NM_RDBLCLK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE

Notifies a control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Unless otherwise specified, the control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_RETURN

Notifies a control's parent window that the control has the input focus and that the user has pressed the ENTER key. NM_RETURN is sent in the form of a WM_NOTIFY message.

NM_RETURN
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_SETCURSOR

Notifies a control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.

NM_SETCURSOR
    lpnmm = (LPNMMOUSE) lParam;

Parameters

lpnmm
Address of an NMMOUSE structure that contains additional information about this notification message.

Return Values

Return zero to enable the control to set the cursor or nonzero to prevent the control from setting the cursor.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_SETFOCUS

Notifies a control's parent window that the control has received the input focus. NM_SETFOCUS is sent in the form of a WM_NOTIFY message.

NM_SETFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_TOOLTIPSCREATED

Notifies a control's parent window that the control has created a ToolTip control. This notification is sent in the form of a WM_NOTIFY message.

Syntax

NM_TOOLTIPSCREATED
    lpnmttc = (LPNMHDR) lParam;

Parameters

lpnmttc
Address of an NMTOOLTIPSCREATED structure that contains additional information about this notification message.

Return Value

Unless otherwise specified, the control ignores the return value from this notification.

Remarks

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


COLORSCHEME

Contains information for the drawing of buttons in a toolbar or rebar.

typedef struct tagCOLORSCHEME{
    DWORD dwSize;
    COLORREF clrBtnHighlight;
    COLORREF clrBtnShadow;
} COLORSCHEME, *LPCOLORSCHEME;

Members

dwSize
Size of this structure, in bytes.
clrBtnHighlight
COLORREF value that represents the highlight color of the buttons. Use CLR_DEFAULT for the default highlight color.
clrBtnShadow
COLORREF value that represents the shadow color of the buttons. Use CLR_DEFAULT for the default shadow color.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


INITCOMMONCONTROLSEX

Carries information used to load common control classes from the dynamic-link library (DLL). This structure is used with the InitCommonControlsEx function.

typedef struct tagINITCOMMONCONTROLSEX {
    DWORD dwSize;
    DWORD dwICC;
} INITCOMMONCONTROLSEX, *LPINITCOMMONCONTROLSEX;

Members

dwSize
Size of the structure, in bytes.
dwICC
Set of bit flags that indicate which common control classes will be loaded from the DLL. This value can be a combination of the following:
ICC_ANIMATE_CLASS | Load animate control class.
ICC_BAR_CLASSES | Load toolbar, status bar, trackbar, and ToolTip control classes.
ICC_COOL_CLASSES | Load rebar control class.
ICC_DATE_CLASSES | Load date and time picker control class.
ICC_HOTKEY_CLASS | Load hot key control class.
ICC_INTERNET_CLASSES | Load IP address class.
ICC_LISTVIEW_CLASSES | Load list-view and header control classes.
ICC_PAGESCROLLER_CLASS | Load pager control class.
ICC_PROGRESS_CLASS | Load progress bar control class.
ICC_TAB_CLASSES | Load tab and ToolTip control classes.
ICC_TREEVIEW_CLASSES | Load tree-view and ToolTip control classes.
ICC_UPDOWN_CLASS | Load up-down control class.
ICC_USEREX_CLASSES | Load ComboBoxEx class.
ICC_WIN95_CLASSES | Load animate control, header, hot key, list-view, progress bar, status bar, tab, ToolTip, toolbar, trackbar, tree-view, and up-down control classes.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LV_GROUP Structure

This is preliminary documentation and is subject to change.

Used to set and retrieve groups.

Syntax

typedef struct LV_GROUP {
    UINT cbSize;
    UINT mask;
    LPWSTR pszHeader;
    int cchHeader;
    int iGroupId;
    UINT stateMask;
    UINT state;
    UINT uAlign;
} LV_GROUP, *PLV_GROUP;

Members

cbSize
Size of an LV_GROUP structure.
mask
Flag that can have one or more of the following values.
LVGF_ALIGN
LVGF_FOOTER
LVGF_GROUPID
LVGF_HEADER
LVGF_NONE
LVGF_STATE
pszHeader
Pointer to a string that contains the header.
cchHeader
Number of characters in the string that specifies the header.
iGroupId
identifier (ID) of the group.
stateMask
Flag.
state
Flag that can have one of the following values.
LVGS_COLLAPSED
LVGS_HIDDEN
LVGS_NORMAL
uAlign
Flag that can have one or more of the following values. Use one of the header flags. Footer flags are optional.
LVGA_FOOTER_CENTER
LVGA_FOOTER_LEFT
LVGA_FOOTER_RIGHT
LVGA_HEADER_CENTER
LVGA_HEADER_LEFT
LVGA_HEADER_RIGHT

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LVGROUPMETRICS Structure

This is preliminary documentation and is subject to change.

Used to retrieve or set group metrics.

Syntax

typedef struct LVGROUPMETRICS {
    UINT cbSize;
    UINT mask;
    UINT Left;
    UINT Top;
    UINT Right;
    UINT Bottom;
    COLORREF crLeft;
    COLORREF crTop;
    COLORREF crRight;
    COLORREF crBottom;
    COLORREF crRightHeader;
    COLORREF crFooter;
} LVGROUPMETRICS, *PLVGROUPMETRICS;

Members

cbSize
Size of an LVGROUPMETRICS structure.
mask
Flag that can have one or more of the following values.
LVGF_BORDERCOLOR
LVGF_BORDERSIZE
LVGF_NONE
LVGF_TEXTCOLOR
Left
Specifies the left border.
Top
Specifies the top border.
Right
Specifies the right border.
Bottom
Specifies the bottom border.
crLeft
Specifies the color of the left border.
crTop
Specifies the color of the top border.
crRight
Specifies the color of the right border.
crBottom
Specifies the color of the bottom border.
crRightHeader
Specifies the color of the header text.
crFooter
Specifies the color of the footer text.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LVINSERTGROUPSORTED Structure

This is preliminary documentation and is subject to change.

Used to sort groups.

Syntax

typedef struct LVINSERTGROUPSORTED {
    PFNLVGROUPCOMPARE pfnGroupCompare;
    LPVOID *pvData;
    LV_GROUP lvGroup;
} LVINSERTGROUPSORTED, *PLVINSERTGROUPSORTED;

Members

pfnGroupCompare
Pointer to a compare function used to sort the groups.
pvData
Data to sort.
lvGroup
Group to sort.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LVINSERTMARK Structure

This is preliminary documentation and is subject to change.

Used to describe insertion points.

Syntax

typedef struct LVINSERTMARK {
    UINT cbSize;
    DWORD dwFlags;
    int iItem;
    DWORD dwReserved;
} LVINSERTMARK, *PLVINSERTMARK;

Members

cbSize
Size of the LVINSERTMARK structure.
dwFlags
Flag that specifies where the insertion point should appear. Use the following:
LVIM_AFTER
The insertion point appears after the item specified if the LVIM_AFTER flag is set; otherwise it appears before the specified item.
iItem
Item next to which the insertion point appears. If this member contains -1, there is no insertion point.
dwReserved
Reserved. Must be set to 0.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LVITEM Structure

This is preliminary documentation and is subject to change.

Specifies or receives the attributes of a list-view item.

Syntax

typedef struct _LVITEM {
    UINT mask;
    int iItem;
    int iSubItem;
    UINT state;
    UINT stateMask;
    LPTSTR pszText;
    int cchTextMax;
    int iImage;
    LPARAM lParam;
    int iIndent;
    int iGroupId;
    int cColumns;
    int puColumns;
} LVITEM, *LPLVITEM;

Members

mask
Set of flags that specify which members of this structure contain data to set or which members are being requested. You can set one or more of the following flags.
LVIF_DI_SETITEM
The operating system should store the requested list item information and not request it again. This flag is used only with the LVN_GETDISPINFO Online link notification message.
LVIF_IMAGE
The iImage member is valid or must be filled in.
LVIF_INDENT
The iIndent member is valid or must be filled in.
LVIF_NORECOMPUTE
The control does not generate LVN_GETDISPINFO to retrieve text information if it receives an LVM_GETITEM Online link message. Instead, the pszText member contains LPSTR_TEXTCALLBACK.
LVIF_PARAM
The lParam member is valid or must be filled in.
LVIF_STATE
The state member is valid or must be filled in.
LVIF_TEXT
The pszText member is valid or must be filled in.
iItem
Zero-based index of the item to which this structure refers.
iSubItem
One-based index of the subitem to which this structure refers, or zero if this structure refers to an item rather than a subitem.
state

Indicates the item's state, state image, and overlay image. The stateMask member indicates the valid bits of this member.

Bits 0 through 7 of this member contain the item state flags. These can be one or more of the item state values.

Bits 8 through 11 of this member specify the one-based overlay image index. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed on the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To set the overlay image index in this member, use the INDEXTOOVERLAYMASK Online link macro. The image list's overlay images are set with the ImageList_SetOverlayImage Online link function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item's icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To set the state image index, use the INDEXTOSTATEIMAGEMASK Online link macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the LVM_SETIMAGELIST Online link message.

stateMask

Value that specifies which bits of the state member will be retrieved or modified. For example, setting this member to LVIS_SELECTED causes only the item's selection state to be retrieved.

This member enables you to modify one or more item states without retrieving all the item states first. For example, setting this member to LVIS_SELECTED and state to zero causes the item's selection state to be cleared, but none of the other states are affected.

To retrieve or modify all the states, set this member to (UINT)-1.

You can use the macro ListView_SetItemState Online link to both set and clear bits.

pszText

If the structure specifies item attributes, pszText is a pointer to a null-terminated string that contains the item text. If the structure receives item attributes, pszText is a pointer to a buffer that receives the item text.

If the value of pszText is LPSTR_TEXTCALLBACK, the item is a callback item. If the callback text changes, you must explicitly set pszText to LPSTR_TEXTCALLBACK and notify the list-view control of the change by sending an LVM_SETITEM Online link or LVM_SETITEMTEXT Online link message.

Do not set pszText to LPSTR_TEXTCALLBACK if the list-view control has the List View Window Style Online link LVS_SORTASCENDING or LVS_SORTDESCENDING style.

cchTextMax
Number of characters in the buffer pointed to by pszText. This member is only used when the structure receives item attributes. It is ignored when the structure specifies item attributes.
iImage

Index of the item icon in the control's image list. This applies to both the large and small image list.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the list-view control sends the parent an LVN_GETDISPINFO notification message to retrieve the index when it needs to display the image.

lParam
32-bit value specific to the item. If you use the LVM_SORTITEMS Online link message, the list-view control passes this value to the application-defined comparison function. You can also use the LVM_FINDITEM Online link message to search a list-view control for an item with a specified lParam value.
iIndent
Number of image widths to indent the item. A single indentation equals the width of an item image. Therefore, the value 1 indents the item by the width of one image, the value 2 indents by two images, and so on. This field is supported only for items. Attempting to set subitem indentation causes the calling function to fail.
iGroupId
Identifier (ID) that this item belongs to. You can set this parameter during GETDISPINFO if the mask for the group ID is set.
cColumns
Number of columns in the tile array.
puColumns
Array of integers that specify the column to associate with a particular tile. When a list-view control is in tile mode, each item can have different columns associated with it.

Remarks

The LVITEM structure has been updated to support a new mask value, LVIF_INDENT, that enables item indenting. This structure supersedes the LV_ITEM structure. Three new members, iGroupId, cColumns, and puColumns are added to this structure for use with the common controls delivered in the Microsoft product code-named Whistler.

The LVITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM Online link, and LVM_DELETEITEM Online link.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LVTILEINFO Structure

This is preliminary documentation and is subject to change.

Provides information about an item in a list-view control when it is displayed in tile view.

Syntax

typedef struct LVTILEINFO {
    UINT cbSize;
    int iItem;
    UINT cColumns;
    PUINT puColumns;
} LVTILEINFO, *PLVTILEINFO;

Members

cbSize
Size of the LVTILEINFO structure.
iItem
Item for which the information is retrieved or set.
cColumns
Number of columns to display for this item.
puColumns
Pointer to the array of column indices; length of cColumns.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LVTILEVIEWINFO Structure

This is preliminary documentation and is subject to change.

Provides information about a list-view control when it is displayed in tile view.

Syntax

typedef struct LVTILEVIEWINFO {
    UINT cbSize;
    SIZE sizeTile;
    int cLines;
} LVTILEVIEWINFO, *PLVTILEVIEWINFO;

Members

cbSize
Size of the LVTILEVIEWINFO structure.
sizeTile
Size of an individual tile.
cLines
Number of lines in the tile.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


NMCHAR

Contains information used with character notification messages.

typedef struct tagNMCHAR{
    NMHDR hdr;
    UINT ch;
    DWORD dwItemPrev;
    DWORD dwItemNext;
} NMCHAR, FAR *LPNMCHAR;

Members

hdr
NMHDR structure that contains additional information about this notification.
ch
Character that is being processed.
dwItemPrev
32-bit value that is determined by the control that is sending the notification.
dwItemNext
32-bit value that is determined by the control that is sending the notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMHDR

Contains information about a notification message.

typedef struct tagNMHDR {
    HWND hwndFrom;
    UINT idFrom;
    UINT code;
} NMHDR;

Members

hwndFrom
Window handle to the control sending a message.
idFrom
Identifier of the control sending a message.
code
Notification code. This member can be a control-specific notification code or it can be one of the common notification codes.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in winuser.h.


NMKEY

Contains information used with key notification messages.

typedef struct tagNMKEY {
    NMHDR hdr;
    UINT nVKey;
    UINT uFlags;
} NMKEY, FAR *LPNMKEY;

Members

hdr
NMHDR structure that contains additional information about this notification.
nVKey
Virtual key code of the key that caused the event.
uFlags
Flags associated with the key. These are the same flags that are passed in the high word of the lParam parameter of the WM_KEYDOWN message.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMMOUSE

Contains information used with mouse notification messages.

typedef struct tagNMMOUSE {
    NMHDR     hdr;
    DWORD_PTR dwItemSpec;
    DWORD_PTR dwItemData;
    POINT     pt;
    LPARAM    dwHitInfo;
} NMMOUSE, FAR* LPNMMOUSE;

Members

hdr
NMHDR structure that contains additional information about this notification.
dwItemSpec
Control-specific item identifier.
dwItemData
Control-specific item data.
pt
POINT structure that contains the screen coordinates of the mouse when the click occurred.
dwHitInfo
Carries information about where on the item or control the cursor is pointing.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMOBJECTNOTIFY

Contains information used with the TBN_GETOBJECT, TCN_GETOBJECT, and PSN_GETOBJECT notification messages.

typedef struct tagNMOBJECTNOTIFY {
    NMHDR     hdr;
    int       iItem;
    IID*      piid;
    IUnknown* pObject;
    HRESULT   hResult;
} NMOBJECTNOTIFY, FAR* LPNMOBJECTNOTIFY;

Members

hdr
NMHDR structure that contains additional information about this notification.
iItem
Control-specific item identifier. This value will comply to item identification standards for the control sending the notification. However, this member is not used with the PSN_GETOBJECT notification message.
piid
Interface identifier of the requested object.
pObject
Address of an object provided by the window processing the notification message. The application processing the notification message sets this member.
hResult
COM success or failure flags. The application processing the notification message sets this member.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTOOLTIPSCREATED

Contains information used with NM_TOOLTIPSCREATED notification messages.

typedef struct tagNMTOOLTIPSCREATED {
    NMHDR hdr;
    HWND hwndToolTips;
} NMTOOLTIPSCREATED, * LPNMTOOLTIPSCREATED;

Parameters

Members

hdr
NMHDR structure that contains additional information about this notification.
hwndToolTips
Window handle to the ToolTip control created.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Header: Declared in commctrl.h.


Customizing a Control's Appearance Using Custom Draw

Custom draw is not a common control; it is a service that many common controls provide. Custom draw services allow an application greater flexibility in customizing a control's appearance. Your application can harness custom draw notifications to easily change the font used to display items or manually draw an item without having to do a full-blown owner draw.

  • About Custom Draw
  • Custom Draw With List-View and Tree-View Controls
  • Using Custom Draw
  • Custom Draw Reference

About Custom Draw

This section contains general information about custom draw functionality and provides a conceptual overview of how an application can support custom draw.

Currently, the following controls support custom draw functionality:

  • Header controls
  • List-view controls
  • Rebar controls
  • Toolbar controls
  • ToolTip controls
  • Trackbar controls
  • Tree-view controls

Note Custom draw is implemented in version 4.70 and later of Comctl32.dll.

About Custom Draw Notification Messages

All common controls that support custom draw send NM_CUSTOMDRAW notification messages at specific points during drawing operations. These notifications describe drawing operations that apply to the entire control as well as drawing operations specific to items within the control. Like many notification messages, NM_CUSTOMDRAW notifications are sent as WM_NOTIFY messages.

The lParam parameter of a custom draw notification message will be the address of an NMCUSTOMDRAW structure or a control-specific structure that contains an NMCUSTOMDRAW structure as its first member. The following table illustrates the relationship between the controls and the structures they use.

Structure | Used by
NMCUSTOMDRAW | Rebar, trackbar, and header controls
NMLVCUSTOMDRAW | List-view controls
NMTBCUSTOMDRAW | Toolbar controls
NMTTCUSTOMDRAW | ToolTip controls
NMTVCUSTOMDRAW | Tree-view controls

Paint Cycles, Drawing Stages, and Notification Messages

Like all Microsoft® Windows® applications, common controls periodically paint and erase themselves based on messages received from the system or other applications. The process of a control painting or erasing itself is called a paint cycle. Controls that support custom draw send NM_CUSTOMDRAW notification messages periodically through each paint cycle. This notification message is accompanied by an NMCUSTOMDRAW structure or another structure that contains an NMCUSTOMDRAW structure as its first member.

One piece of information that the NMCUSTOMDRAW structure contains is the current stage of the paint cycle. This is referred to as the draw stage and is represented by the value in the structure's dwDrawStage member. A control informs its parent about four basic draw stages. These basic, or global, draw stages are represented in the structure by the following flag values (defined in Commctrl.h).

Global draw stage values | Description
CDDS_PREPAINT | Before the paint cycle begins.
CDDS_POSTPAINT | After the paint cycle is complete.
CDDS_PREERASE | Before the erase cycle begins.
CDDS_POSTERASE | After the erase cycle is complete.

Each of the preceding values can be combined with the CDDS_ITEM flag to specify draw stages specific to items. For convenience, Commctrl.h contains the following item-specific values.

Item-specific draw stage values | Description
CDDS_ITEMPREPAINT | Before an item is drawn.
CDDS_ITEMPOSTPAINT | After an item has been drawn.
CDDS_ITEMPREERASE | Before an item is erased.
CDDS_ITEMPOSTERASE | After an item has been erased.
CDDS_SUBITEM | Version 4.71. Flag combined with CDDS_ITEMPREPAINT or CDDS_ITEMPOSTPAINT if a subitem is being drawn. This will only be set if CDRF_NOTIFYITEMDRAW is returned from CDDS_PREPAINT.

Your application must process the NM_CUSTOMDRAW notification message and then return a specific value that informs the control what it must do. See the following sections for more information about these return values.

Taking Advantage of Custom Draw Services

The key to harnessing custom draw functionality is in responding to the NM_CUSTOMDRAW notification messages that a control sends. The return values your application sends in response to these notifications determine the control's behavior for that paint cycle.

This section contains information about how your application can use NM_CUSTOMDRAW notification return values to determine the control's behavior. Details are broken into the following topics:

  • Responding to the prepaint notification
  • Requesting item-specific notifications
  • Drawing the item yourself
  • Changing fonts and colors

Responding to the prepaint notification

At the beginning of each paint cycle, the control sends the NM_CUSTOMDRAW notification message, specifying the CDDS_PREPAINT value in the dwDrawStage member of the accompanying NMCUSTOMDRAW structure. The value that your application returns to this first notification dictates how and when the control sends subsequent custom draw notifications for the rest of that paint cycle. Your application can return a combination of the following flags in response to the first notification.

Return value | Effect
CDRF_DODEFAULT | The control will draw itself. It will not send additional NM_CUSTOMDRAW notifications for this paint cycle. This flag cannot be used with any other flag.
CDRF_NOTIFYITEMDRAW | The control will notify the parent of any item-specific drawing operations. It will send NM_CUSTOMDRAW notification messages before and after it draws items.
CDRF_NOTIFYPOSTPAINT | The control will send an NM_CUSTOMDRAW notification when the painting cycle for the entire control is complete.
CDRF_SKIPDEFAULT | The control will not perform any painting at all.

Requesting item-specific notifications

If your application returns CDRF_NOTIFYITEMDRAW to the initial prepaint custom draw notification, the control will send notifications for each item it draws during that paint cycle. These item-specific notifications will have the CDDS_ITEMPREPAINT value in the dwDrawStage member of the accompanying NMCUSTOMDRAW structure. You can request that the control send another notification when it is finished drawing the item by returning CDRF_NOTIFYPOSTPAINT to these item-specific notifications. Otherwise, return CDRF_DODEFAULT and the control will not notify the parent window until it starts to draw the next item.

Drawing the item yourself

If your application draws the entire item, return CDRF_SKIPDEFAULT. This allows the control to skip items that it does not need to draw, thereby decreasing system overhead. Keep in mind that returning this value means the control will not draw any portion of the item.

Changing fonts and colors

Your application can use custom draw to change an item's font. Simply select the HFONT you want into the device context specified by the hdc member of the NMCUSTOMDRAW structure associated with the custom draw notification. Since the font you select might have different metrics than the default font, make sure you include the CDRF_NEWFONT bit in the return value for the notification message. For more information on using this functionality, see the sample code in Using Custom Draw. The font that your application specifies is used to display that item when it is not selected. Custom draw does not allow you to change the font attributes for selected items.

To change text colors for all controls that support custom draw except for the list view and tree view, simply set the desired text and background colors in the device context supplied in the custom draw notification structure with the SetTextColor and SetBkColor functions. To modify the text colors in the list view or tree view, you need to place the desired color values in the clrText and clrTextBk members of the NMLVCUSTOMDRAW or NMTVCUSTOMDRAW structure.

Custom Draw With List-View and Tree-View Controls

Most common controls can be handled in essentially the same way. However, the list-view and tree-view controls have some features that require a somewhat different approach to custom draw.

For Version 5.0 of the common controls, these two controls may display clipped text if you change the font by returning CDRF_NEWFONT. This behavior is necessary for backward compatibility with earlier versions of the common controls. If you want to change the font of a list-view or tree-view control, you will get better results if you send a CCM_SETVERSION message with the wParam value set to 5 before adding any items to the control.

Custom Draw With List-View Controls

Because list-view controls have subitems and multiple display modes, you will need to handle the NM_CUSTOMDRAW notification somewhat differently than for the other common controls.

For report mode:

  1. The first NM_CUSTOMDRAW notification will have the dwDrawStage member of the associated NMCUSTOMDRAW structure set to CDDS_PREPAINT. Return CDRF_NOTIFYITEMDRAW.
  2. You will then receive an NM_CUSTOMDRAW notification with dwDrawStage set to CDDS_ITEMPREPAINT. If you specify new fonts or colors and return CDRF_NEWFONT, all subitems of the item will be changed. If you want instead to handle each subitem separately, return CDRF_NOTIFYSUBITEMDRAW.
  3. If you returned CDRF_NOTIFYITEMDRAW in the previous step, you will then receive an NM_CUSTOMDRAW notification for each subitem with dwDrawStage set to CDDS_SUBITEM | CDDS_PREPAINT. To change the font or color for that subitem, specify a new font or color and return CDRF_NEWFONT.

For the large icon, small icon, and list modes:

  1. The first NM_CUSTOMDRAW notification will have the dwDrawStage member of the associated NMCUSTOMDRAW structure set to CDDS_PREPAINT. Return CDRF_NOTIFYITEMDRAW.
  2. You will then receive an NM_CUSTOMDRAW notification with dwDrawStage set to CDDS_ITEMPREPAINT. You can change the fonts or colors of an item by specifying new fonts and colors and returning CDRF_NEWFONT. Because these modes do not have subitems, you will not receive any additional NM_CUSTOMDRAW notifications.

An example of a list-view NM_CUSTOMDRAW notification handler is given in the next section.

Using Custom Draw

The following code fragment is a portion of a WM_NOTIFY handler that illustrates how to handle custom draw notifications sent to a list-view control:

LPNMLISTVIEW  pnm    = (LPNMLISTVIEW)lParam;

switch (pnm->hdr.code){
...
case NM_CUSTOMDRAW:

    LPNMLVCUSTOMDRAW  lplvcd = (LPNMLVCUSTOMDRAW)lParam;

    switch(lplvcd->nmcd.dwDrawStage) {
    case CDDS_PREPAINT :
        return CDRF_NOTIFYITEMDRAW;

    case CDDS_ITEMPREPAINT:
        SelectObject(lplvcd->nmcd.hdc,
                     GetFontForItem(lplvcd->nmcd.dwItemSpec,
                                    lplvcd->nmcd.lItemlParam) );
        lplvcd->clrText = GetColorForItem(lplvcd->nmcd.dwItemSpec,
                                          lplvcd->nmcd.lItemlParam);
        lplvcd->clrTextBk = GetBkColorForItem(lplvcd->nmcd.dwItemSpec,
                                              lplvcd->nmcd.lItemlParam);

/* At this point, you can change the background colors for the item
and any subitems and return CDRF_NEWFONT. If the list-view control
is in report mode, you can simply return CDRF_NOTIFYSUBITEMREDRAW
to customize the item's subitems individually */

        ...
        return CDRF_NEWFONT;
    //  or return CDRF_NOTIFYSUBITEMREDRAW;

    case CDDS_SUBITEM | CDDS_ITEMPREPAINT:
        SelectObject(lplvcd->nmcd.hdc,
                     GetFontForSubItem(lplvcd->nmcd.dwItemSpec,
                                       lplvcd->nmcd.lItemlParam,
                                       lplvcd->iSubItem));
        lplvcd->clrText = GetColorForSubItem(lplvcd->nmcd.dwItemSpec,
                                             lplvcd->nmcd.lItemlParam,
                                             lplvcd->iSubItem));
        lplvcd->clrTextBk = GetBkColorForSubItem(lplvcd->nmcd.dwItemSpec,
                                                 lplvcd->nmcd.lItemlParam,
                                                 lplvcd->iSubItem));

/* This notification is received only if you are in report mode and
returned CDRF_NOTIFYSUBITEMREDRAW in the previous step. At
this point, you can change the background colors for the
subitem and return CDRF_NEWFONT.*/

        ...
        return CDRF_NEWFONT;
    }
...
}

The first NM_CUSTOMDRAW notification has the dwDrawStage member of the NMCUSTOMDRAW structure set to CDDS_PREPAINT. The handler returns CDRF_NOTIFYITEMDRAW to indicate that it wishes to modify one or more items individually. The control then sends an NM_CUSTOMDRAW notification with dwDrawStage set to CDDS_PREPAINT for each item. The handler returns CDRF_NOTIFYITEMDRAW to indicate that it wishes to modify the item.

If CDRF_NOTIFYITEMDRAW was returned in the previous step, the next NM_CUSTOMDRAW notification has dwDrawStage set to CDDS_ITEMPREPAINT. The handler retrieves the current color and font values. At this point, you can specify new values for small icon, large icon, and list modes. If the control is in report mode, you can also specify new values that will apply to all subitems of the item. If you have changed anything, return CDRF_NEWFONT. If the control is in report mode and you want to handle the subitems individually, return CDRF_NOTIFYSUBITEMREDRAW.

The final notification is only sent if the control is in report mode and you returned CDRF_NOTIFYSUBITEMREDRAW in the previous step. The procedure for changing fonts and colors is the same as that step, but it only applies to a single subitem. Return CDRF_NEWFONT to notify the control if the color or font was changed.


NM_CUSTOMDRAW

Sent by some common controls to notify their parent windows about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
#ifdef LIST_VIEW_CUSTOM_DRAW
    lpNMCustomDraw = (LPNMLVCUSTOMDRAW) lParam;
#elif TOOL_TIPS_CUSTOM_DRAW
    lpNMCustomDraw = (LPNMTTCUSTOMDRAW) lParam;
#elif TREE_VIEW_CUSTOM_DRAW
    lpNMCustomDraw = (LPNMTVCUSTOMDRAW) lParam;
#elif TOOL_BAR_CUSTOM_DRAW
    lpNMCustomDraw = (LPNMTBCUSTOMDRAW) lParam;
#else
    lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;
#endif

Parameters

lpNMCustomDraw
Address of a custom draw-related structure that contains information about the drawing operation. The following table lists the controls and their associated structures.
Control | Structure
List view | NMLVCUSTOMDRAW
ToolTip | NMTTCUSTOMDRAW
Tree view | NMTVCUSTOMDRAW
Toolbar | NMTBCUSTOMDRAW
All other supported controls | NMCUSTOMDRAW

Return values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:

Return Value | Description
CDRF_DODEFAULT | The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW | The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYPOSTERASE | The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT | The control will notify the parent after painting an item.

When dwDrawStage equals CDDS_ITEMPREPAINT:

Return Value | Description
CDRF_NEWFONT | Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing fonts and colors.
CDRF_NOTIFYSUBITEMDRAW | Version 4.71. Your application will receive an NM_CUSTOMDRAW message with dwDrawStage set to CDDS_ITEMPREPAINT | CDDS_SUBITEM before each list-view subitem is drawn. You can then specify font and color for each subitem separately or return CDRF_DODEFAULT for default processing.
CDRF_SKIPDEFAULT | Your application drew the item manually. The control will not draw the item.

Remarks

Currently, the following controls support custom draw functionality: header, list view, rebar, toolbar, ToolTip, trackbar, and tree view.

See Also

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMCUSTOMDRAW

Contains information specific to an NM_CUSTOMDRAW notification message.

typedef struct tagNMCUSTOMDRAWINFO {
    NMHDR     hdr;
    DWORD     dwDrawStage;
    HDC       hdc;
    RECT      rc;
    DWORD_PTR dwItemSpec;
    UINT      uItemState;
    LPARAM    lItemlParam;
} NMCUSTOMDRAW, FAR * LPNMCUSTOMDRAW;

Members

hdr
NMHDR structure that contains information about this notification message.
dwDrawStage
Current drawing stage. This value is one of the following.
Global Values | Description
CDDS_POSTERASE | After the erasing cycle is complete.
CDDS_POSTPAINT | After the painting cycle is complete.
CDDS_PREERASE | Before the erasing cycle begins.
CDDS_PREPAINT | Before the painting cycle begins.
Item-specific Values | Description
CDDS_ITEM | Indicates that the dwItemSpec, uItemState, and lItemlParam members are valid.
CDDS_ITEMPOSTERASE | After an item has been erased.
CDDS_ITEMPOSTPAINT | After an item has been drawn.
CDDS_ITEMPREERASE | Before an item is erased.
CDDS_ITEMPREPAINT | Before an item is drawn.
CDDS_SUBITEM | Version 4.71. Flag combined with CDDS_ITEMPREPAINT or CDDS_ITEMPOSTPAINT if a subitem is being drawn. This will only be set if CDRF_NOTIFYITEMDRAW is returned from CDDS_PREPAINT.
hdc
Handle to the control's device context. Use this HDC to perform any GDI functions.
rc
RECT structure that describes the bounding rectangle of the area being drawn. This member is initialized only by the CDDS_ITEMPREPAINT notification.

Version 5.80. This member is also initialized by the CDDS_PREPAINT notification.

dwItemSpec
Item number. What is contained in this member will depend on the type of control that is sending the notification. See the NM_CUSTOMDRAW notification reference for the specific control to determine what, if anything, is contained in this member.
uItemState
Current item state. This value is a combination of the following:
Value | Description
CDIS_CHECKED | The item is checked.
CDIS_DEFAULT | The item is in its default state.
CDIS_DISABLED | The item is disabled.
CDIS_FOCUS | The item is in focus.
CDIS_GRAYED | The item is grayed.
CDIS_HOT | The item is currently under the pointer ("hot").
CDIS_INDETERMINATE | The item is in an indeterminate state.
CDIS_MARKED | The item is marked. The meaning of this is up to the implementation.
CDIS_SELECTED | The item is selected.
lItemlParam
Application-defined item data.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Animation Controls

An animation control is a window that displays an AVI clip. An AVI clip is a series of bitmap frames like a movie. Animation controls can only display AVI clips that do not contain audio.

The information on Animation Controls presented within this article will cover the following topics:

  • About Animation Controls
  • Using Animation Controls
  • Animation Control Reference
  • Animation Control Styles

About Animation Controls

One common use for an animation control is to indicate system activity during a lengthy operation. This is possible because the operation thread continues executing while the AVI clip is displayed. For example, the Find dialog box of Microsoft® Windows® Explorer displays a moving magnifying glass as the system searches for a file.

An animation control can display an AVI clip originating from either an uncompressed AVI file or from an AVI file that was compressed using run-length (BI_RLE8) encoding. You can add the AVI clip to your application as an AVI resource, or the clip can accompany your application as a separate AVI file.

Note The AVI file, or resource, must not have a sound channel. The capabilities of the animation control are very limited and are subject to change. If you need a control to provide multimedia playback and recording capabilities for your application, you can use the MCIWnd control. For more information about the MCIWnd control, see the multimedia documentation in the Platform SDK.

Animation Control Creation

An animation control belongs to the ANIMATE_CLASS window class. You create an animation control by using the CreateWindow function or the Animate_Create macro. The macro positions the animation control in the upper-left corner of the parent window and, if the ACS_CENTER style is not specified, sets the width and height of the control based on the dimensions of a frame in the AVI clip. If ACS_CENTER is specified, Animate_Create sets the width and height of the control to zero. You can use the SetWindowPos function to set the position and size of the control.

If you create an animation control within a dialog box or from a dialog box resource, the control is automatically destroyed when the user closes the dialog box. If you create an animation control within a window, you must explicitly destroy the control.

About Animation Control Messages

An application sends messages to an animation control to open, play, stop, and close the corresponding AVI clip. Each message has one or more macros that you can use instead of sending the message explicitly.

After creating an animation control, an application sends the ACM_OPEN message to open an AVI clip and load it into memory. The message specifies either the path of an AVI file or the name of an AVI resource. The system loads the AVI resource from the module that created the animation control.

If the animation control has the ACS_AUTOPLAY style, the control begins playing the AVI clip immediately after the AVI file or AVI resource is opened. Otherwise, an application can use the ACM_PLAY message to start the AVI clip. An application can stop the clip at any time by sending the ACM_STOP message. The last frame played remains displayed when the control finishes playing the AVI clip or when ACM_STOP is sent.

An animation control can send two notification messages, ACN_START and ACN_STOP, to its parent window. Most applications do not handle either notification.

To close the AVI file or AVI resource and remove it from memory, an application can use the Animate_Close macro, which sends ACM_OPEN with the file name or resource name set to NULL.

Default Message Processing

This section describes the window messages handled by the window procedure for the ANIMATE_CLASS window class.
Message | Processing performed
WM_CLOSE | Frees the AVI file or AVI resource associated with the animation control.
WM_DESTROY | Frees the AVI file or AVI resource, frees an internal data structure, and then calls the DefWindowProc function.
WM_ERASEBKGND | Erases the window background using the current background color for static controls.
WM_NCCREATE | Allocates and initializes an internal data structure and then calls DefWindowProc.
WM_NCHITTEST | Returns the HTTRANSPARENT hit test value.
WM_PAINT | Draws an AVI frame in the animation control.
WM_SIZE | Checks if the control has the ACS_CENTER style. If the control does not, it calls DefWindowProc. Otherwise, it centers the animation in the control, invalidates the control, and then calls DefWindowProc.

Using Animation Controls

This section provides examples that demonstrate how to create an animation control and display an AVI clip in the control.

  • Creating an Animation Control
  • Controlling the AVI Clip

Creating an Animation Control

The following function creates an animation control in a dialog box. The animation control is positioned below the specified control, and the dimensions of the animation control are based on the dimensions of a frame in the AVI clip.

// CreateAnimationCtrl - creates an animation control, positions it
//     below the specified control in a dialog box, and opens the AVI
//     clip for the animation control.
// Returns the handle to the animation control.
// hwndDlg - handle to the dialog box.
// nIDCtl - identifier of the control below which the animation control
//          is to be positioned.
//
// Constants
//     IDC_ANIMATE - identifier of the animation control.
//     CX_FRAME, CY_FRAME - width and height of the frames
//     in the AVI clip.
HWND CreateAnimationCtrl(HWND hwndDlg, int nIDCtl)
{
    HWND hwndAnim = NULL;
    RECT rc;
    POINT pt;

    // Create the animation control.
    hwndAnim = Animate_Create(hwndDlg, IDC_ANIMATE,
        WS_BORDER | WS_CHILD, g_hinst);

    // Get the screen coordinates of the specified control button.
    GetWindowRect(GetDlgItem(hwndDlg, nIDCtl), &rc);

    // Convert the coordinates of the lower-left corner to
    // client coordinates.
    pt.x = rc.left;
    pt.y = rc.bottom;
    ScreenToClient(hwndDlg, &pt);

    // Position the animation control below the Stop button.
    SetWindowPos(hwndAnim, 0, pt.x, pt.y + 20,
        CX_FRAME, CY_FRAME,
        SWP_NOZORDER | SWP_DRAWFRAME);

    // Open the AVI clip, and show the animation control.
    Animate_Open(hwndAnim, "SEARCH.AVI");
    ShowWindow(hwndAnim, SW_SHOW);

    return hwndAnim;
}

Controlling the AVI Clip

The following function uses the animation control macros to control the display of the AVI clip in an animation control.

// DoAnimation - plays, stops, or closes an animation control's
//     AVI clip, depending on the value of an action flag.
// hwndAnim - handle to an animation control
// nAction - flag that determines whether to play, stop, or close
//           the AVI clip.
void DoAnimation(HWND hwndAnim, int nAction)
{
    switch (nAction) {
        case PLAYIT:

         // Play the clip continuously starting with the
         // first frame.
            Animate_Play(hwndAnim, 0, -1, -1);
            break;

        case STOPIT:
            Animate_Stop(hwndAnim);
            break;

        case CLOSEIT:
            Animate_Close(hwndAnim);
            break;

        default:
            break;
    }
    return;
}


Animation Control Styles

The following window styles are used with animation controls:

ACS_AUTOPLAY
Starts playing the animation as soon as the AVI clip is opened.
ACS_CENTER
Centers the animation in the animation control's window.
ACS_TIMER
By default, the control creates a thread to play the AVI clip. If you set this flag, the control plays the clip without creating a thread; internally the control uses a Win32 timer to synchronize playback.
ACS_TRANSPARENT
Allows you to match an animation's background color to that of the underlying window, creating a "transparent" background. The control will send a WM_CTLCOLORSTATIC message to its parent. Use SetBkColor to set the background color for the device context to an appropriate value. The control interprets the upper-left pixel of the first frame as the animation's default background color. It will remap all pixels with that color to the value you supplied in response to WM_CTLCOLORSTATIC.


ACM_OPEN

Opens an AVI clip and displays its first frame in an animation control. You can send this message explicitly or use the Animate_Open or Animate_OpenEx macro.

ACM_OPEN
#if (_WIN32_IE >= 0x0400)
    wParam = (WPARAM)(HINSTANCE)hinst;
#else
    wParam = 0;
#endif
    lParam = (LPARAM) (LPSTR) lpszName;

Parameters

hinst
Version 4.71. Instance handle to the module from which the resource should be loaded. Set this value to NULL to have the control use the HINSTANCE value used to create the window. Note that if the window is created by a DLL, the default value for hinst is the HINSTANCE value of the DLL, not of the application that calls the DLL.
lpszName
Address of a buffer that contains the path of the AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads the AVI resource from the module specified by the instance handle passed to the CreateWindow function, the Animate_Create macro, or the dialog box creation function that created the control. In Version 4.71 and later, the resource is loaded from the module specified by hinst. An AVI resource must have the "AVI" type.

If this parameter is NULL, the system closes the AVI file that was previously opened for the specified animation control, if any.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

The AVI file or resource specified by lpszName must not contain audio.

With Windows 95, the animation control only responds to the ANSI version of the message (ACM_OPENA) with an ANSI string for lpszName. The Unicode version, ACM_OPENW, will fail.

You can only open silent AVI clips. ACM_OPEN and Animate_Open fail if lpszSource specifies an AVI clip that contains sound.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ACM_PLAY

Plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing. You can send this message explicitly or by using the Animate_Play macro.

ACM_PLAY
    wParam = (WPARAM) (UINT) cRepeat;
    lParam = (LPARAM) MAKELONG(wFrom, wTo);

Parameters

cRepeat
Number of times to replay the AVI clip. A value of -1 means replay the clip indefinitely.
wFrom
Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.
wTo
Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of -1 means end with the last frame in the AVI clip.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ACM_STOP

Stops playing an AVI clip in an animation control. You can send this message explicitly or by using the Animate_Stop macro.

ACM_STOP
    wParam = 0;
    lParam = 0;

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Animate_Close

Closes an AVI clip and displays its first frame in an animation control. You can use this macro or send the ACM_OPEN message explicitly.

BOOL Animate_Close(
    HWND hwnd
);

Parameters

hwnd
Handle to the animation control.

Return Values

Always returns FALSE.

Remarks

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

See Also

Animate_Open, MAKEINTRESOURCE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Animate_Create

Creates an animation control. Animate_Create calls the CreateWindow function to create the animation control.

HWND Animate_Create(
    HWND hwndP,
    UINT id,
    DWORD dwStyle,
    HINSTANCE hInstance
);

Parameters

hwndP
Handle to the parent window.
id
Child window identifier of the animation control.
dwStyle
Window styles. For a list of the animation control style values, see Animation Control Styles.
hInstance
Handle to the instance of the module that is creating the animation control.

Return Values

Returns the handle to the animation control.

Remarks

The Animate_Create macro sets the width and height of the animation control to zero if the ACS_CENTER style is specified. If the ACS_CENTER style is not specified, Animate_Create sets the width and height based on the dimensions of a frame in the AVI clip.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Animate_Open

Opens an AVI clip and displays its first frame in an animation control. You can use this macro or send the ACM_OPEN message explicitly.

BOOL Animate_Open(
    HWND hwndAnim,
    LPTSTR lpszName
);

Parameters

hwndAnim
Handle to the animation control.
lpszName
Address of a buffer that contains the path of the AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads an AVI resource from the module specified by the instance handle passed to the CreateWindow function, the Animate_Create macro, or the dialog box creation function that created the control.

The AVI file or resource specified by lpszName must not contain audio.

If this parameter is NULL, the system closes the AVI file that was previously opened for the specified animation control, if any.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

You can only open silent AVI clips. ACM_OPEN and Animate_Open will fail if lpszSource specifies an AVI clip that contains sound.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Animate_OpenEx

Opens an AVI clip from a resource in a specified module and displays its first frame in an animation control. You can use this macro or send the ACM_OPEN message explicitly.

BOOL Animate_OpenEx(
    HWND hwndAnim,
    HINSTANCE hinst,
    LPTSTR lpszName
);

Parameters

hwndAnim
Handle to the animation control.
hinst
Instance handle to the module that the resource should be loaded from. If this value is NULL, the resource is loaded from the module that created the animation control.
lpszName
Address of a buffer that contains the path of the AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads the AVI resource from the module specified by hinst.

The AVI file or resource specified by lpszName must not contain audio.

If this parameter is NULL, the system closes the AVI file that was previously opened for the specified animation control, if any.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

You can only open silent AVI clips. ACM_OPEN and Animate_Open will fail if lpszSource specifies an AVI clip that contains sound.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Animate_Play

Plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing. You can use this macro or send the ACM_PLAY message explicitly.

BOOL Animate_Play(
    HWND hwndAnim,
    UINT wFrom,
    UINT wTo,
    UINT cRepeat
);

Parameters

hwndAnim
Handle to the animation control in which to play the AVI clip.
wFrom
Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.
wTo
Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of -1 means end with the last frame in the AVI clip.
cRepeat
Number of times to replay the AVI clip. A value of -1 means replay the clip indefinitely.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Animate_Seek

Directs an animation control to display a particular frame of an AVI clip. The control displays the clip in the background while the thread continues executing. You can use this macro or send the ACM_PLAY message explicitly.

BOOL Animate_Seek(
    HWND hwndAnim,
    UINT wFrame
);

Parameters

hwndAnim
Handle to the animation control in which to display the AVI frame.
wFrame
Zero-based index of the frame to display.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

Animate_Play

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Animate_Stop

Stops playing an AVI clip in an animation control. You can use this macro or send the ACM_STOP message explicitly.

BOOL Animate_Stop(
    HWND hwndAnim
);

Parameters

hwndAnim
Handle to the animation control.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ACN_START

Notifies an animation control's parent window that the associated AVI clip has started playing. This notification message is sent in the form of a WM_COMMAND message.

ACN_START

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ACN_STOP

Notifies an animation control's parent window that the associated AVI clip has stopped playing. This notification message is sent in the form of a WM_COMMAND message.

ACN_STOP

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ComboBoxEx Controls

A ComboBoxEx control is an extension of the combo box control that provides native support for item images. To make item images easily accessible, the control provides image list support. By using this control, you can provide the functionality of a combo box without having to manually draw item graphics.

  • About ComboBoxEx Controls
  • Using ComboBoxEx Controls
  • ComboBoxEx Control Reference

About ComboBoxEx Controls

Effectively, a ComboBoxEx control creates a child combo box and performs owner draw tasks for you based on an assigned image list. Therefore, the CBS_OWNERDRAWFIXED style is implied and you need not use it when creating the control. Because image lists are used to provide item graphics, the CBS_OWNERDRAWVARIABLE style cannot be used.

A ComboBoxEx control must be initialized by calling the InitCommonControlsEx function, specifying ICC_USEREX_CLASSES in the accompanying INITCOMMONCONTROLSEX structure.

You can create a ComboBoxEx control by using the CreateWindowEx function and specifying WC_COMBOBOXEX as the window class. The class is registered when the InitCommonControlsEx function is called as explained above.

ComboBoxEx controls are created without a default image list. To use item images, you must create an image list for the ComboBoxEx control and assign it to the control using the CBEM_SETIMAGELIST message. If you do not assign an image list to the ComboBoxEx control, the control displays item text only.

ComboBoxEx Control Styles

ComboBoxEx controls support only the following ComboBox styles:

  • CBS_SIMPLE
  • CBS_DROPDOWN
  • CBS_DROPDOWNLIST
  • WS_CHILD

There are also several extended styles that are used only by ComboBoxEx.

Note: the CBS_SIMPLE style may not work properly in some cases.

Because the ComboBoxEx control performs owner draw tasks for you based on an assigned image list, the CBS_OWNERDRAWFIXED style is implied; you need not use it when creating the control. Because image lists are used to provide item graphics, the CBS_OWNERDRAWVARIABLE style cannot be used. The ComboBoxEx control also supports extended styles that provide additional features.

ComboBoxEx Control Items

ComboBoxEx controls maintain item information using a COMBOBOXEXITEM structure. This structure includes members for item indexes, image indexes (normal, selection state, and overlay), indentation values, text strings, and item-specific values.

The ComboBoxEx control provides easy access to and manipulation of items through messaging. To add or delete an item, send the CBEM_INSERTITEM or CBEM_DELETEITEM message. You can modify items currently in the control using the CBEM_SETITEM message.

Callback Items

ComboBoxEx controls support callback item attributes. You can specify an item as a callback item when you add it to the control using CBEM_INSERTITEM. When you assign values to an item's COMBOBOXEXITEM structure, you must specify the appropriate callback flag values. The following are COMBOBOXEXITEM structure members and their corresponding callback flag values.
Member | Callback value
pszText | LPSTR_TEXTCALLBACK
iImage | I_IMAGECALLBACK
iSelectedImage | I_IMAGECALLBACK
iOverlay | I_IMAGECALLBACK
iIndent | I_INDENTCALLBACK

The control will request information about callback items by sending CBEN_GETDISPINFO notification messages. This notification is sent in the form of a WM_NOTIFY message. When your application processes this message, it must provide the requested information for the control. If you set the mask member of the accompanying COMBOBOXEXITEM structure to CBEIF_DI_SETITEM, the control will store the item data and will not request it again.

ComboBoxEx Control Image Lists

If you want a ComboBoxEx control to display icons with items, you must provide an image list. ComboBoxEx controls support up to three images for an item—one for its selected state, one for its nonselected state, and one for an overlay image. Assign an existing image list to a ComboBoxEx control using the CBEM_SETIMAGELIST message.

The COMBOBOXEXITEM structure contains members that represent the image indexes for each image list (selected, unselected, and overlay). For each item, set these members to display the desired images. It is not necessary to specify image indexes for each type of image. You can mix and match image types as you like, but always set the mask member of the COMBOBOXEXITEM structure to indicate which members are being used. The control ignores members that have not been flagged as valid.

Note: if you use the CBS_SIMPLE style, icons are not displayed.

About ComboBoxEx Control Notification Messages

A ComboBoxEx control sends notification messages to report changes within itself or to request callback item information. The parent of the control receives all WM_COMMAND messages from the combo box contained within the ComboBoxEx control. The ComboBoxEx control sends its own notifications using WM_NOTIFY messages. As a result, the control's owner must be prepared to process both forms of notification messages.

Following are the ComboBoxEx-specific notification messages.
Notification | Description
CBEN_BEGINEDIT | Signals that the user has activated the drop-down list or clicked in the control's edit box.
CBEN_ENDEDIT | Signals that the user has selected an item from the drop-down list or has concluded an edit operation within the edit box.
CBEN_DELETEITEM | Reports that an item was deleted.
CBEN_GETDISPINFO | Requests information about an item's attributes.
CBEN_INSERTITEM | Signals that an item was inserted in the control.

ComboBoxEx Control Message Forwarding

The following are the standard combo box messages that a ComboBoxEx control forwards to its child combo box. Some of these messages may be processed by the ComboBoxEx control either before or after the message has been forwarded.

  • CB_DELETESTRING
  • CB_FINDSTRINGEXACT
  • CB_GETCOUNT
  • CB_GETCURSEL
  • CB_GETDROPPEDCONTROLRECT
  • CB_GETDROPPEDSTATE
  • CB_GETITEMDATA
  • CB_GETITEMHEIGHT
  • CB_GETLBTEXT
  • CB_GETLBTEXTLEN
  • CB_GETEXTENDEDUI
  • CB_LIMITTEXT
  • CB_RESETCONTENT
  • CB_SETCURSEL
  • CB_SETDROPPEDWIDTH
  • CB_SETEXTENDEDUI
  • CB_SETITEMDATA
  • CB_SETITEMHEIGHT
  • CB_SHOWDROPDOWN

Following are the windows messages that a ComboBoxEx control forwards to its parent window:

  • WM_COMMAND (This includes all of the CBN_ notifications.)
  • WM_NOTIFY

Using ComboBoxEx Controls

This section contains sample code and information about the following topics related to ComboBoxEx controls:

  • Creating a ComboBoxEx Control
  • Preparing ComboBoxEx Items and Images
  • Supporting Callback Items
  • Processing ComboBoxEx Notifications

Creating a ComboBoxEx Control

To create a ComboBoxEx control, call the CreateWindowEx function, using WC_COMBOBOXEX as the window class. You must first register the window class by calling the InitCommonControlsEx function, while specifying the ICC_USEREX_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.

The following application-defined function creates a ComboBoxEx control with the CBS_DROPDOWN style in the main window.

// CreateComboEx - Registers the ComboBoxEx window class and creates
// a ComboBoxEx control in the client area of the main window.
//
// g_hwndMain - A handle to the main window.
// g_hinst    - A handle to the program instance.

HWND WINAPI CreateComboEx(void)
{
    HWND hwnd;
    INITCOMMONCONTROLSEX icex;

    icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
    icex.dwICC = ICC_USEREX_CLASSES;

    InitCommonControlsEx(&icex);

    hwnd = CreateWindowEx(0, WC_COMBOBOXEX, NULL,
                    WS_BORDER | WS_VISIBLE |
                    WS_CHILD | CBS_DROPDOWN,
                    // No size yet--resize after setting image list.
                    0,      // Vertical position of Combobox
                    0,      // Horizontal position of Combobox
                    0,      // Sets the width of Combobox
                    100,    // Sets the height of Combobox
                    g_hwndMain,
                    NULL,
                    g_hinst,
                    NULL);
    return (hwnd);
}

Preparing ComboBoxEx Items and Images

To add an item to a ComboBoxEx control, first define a COMBOBOXEXITEM structure. Set the mask member of the structure to indicate which members you want the control to use. Set the specified members of the structure to the values you want, and then send the CBEM_INSERTITEM message to add the item to the control.

The following application-defined function adds 15 items to an existing ComboBoxEx control. Note that the mask member of the COMBOBOXEXITEM structure includes flag values that tell the control to display images for each item.

#define MAX_ITEMS 15

// AddItems - Uses the CBEM_INSERTITEM message to add items to an
// existing ComboBoxEx control.

BOOL WINAPI AddItems(HWND hwndCB)
{
    //  Declare and init locals.
    COMBOBOXEXITEM cbei;
    int iCnt;

    typedef struct {
        int iImage;
        int iSelectedImage;
        int iIndent;
        LPTSTR pszText;
    } ITEMINFO, *PITEMINFO;

    ITEMINFO IInf[ ] = {
        { 0, 3,  0, "first"},
        { 1, 4,  1, "second"},
        { 2, 5,  2, "third"},
        { 0, 3,  0, "fourth"},
        { 1, 4,  1, "fifth"},
        { 2, 5,  2, "sixth"},
        { 0, 3,  0, "seventh"},
        { 1, 4,  1, "eighth"},
        { 2, 5,  2, "ninth"},
        { 0, 3,  0, "tenth"},
        { 1, 4,  1, "eleventh"},
        { 2, 5,  2, "twelfth"},
        { 0, 3,  0, "thirteenth"},
        { 1, 4,  1, "fourteenth"},
        { 2, 5,  2, "fifteenth"}
    };

    // Set the mask common to all items.
    cbei.mask = CBEIF_TEXT | CBEIF_INDENT |
                CBEIF_IMAGE| CBEIF_SELECTEDIMAGE;

    for(iCnt=0;iCnt<MAX_ITEMS;iCnt++){
        // Initialize the COMBOBOXEXITEM struct.
        cbei.iItem          = iCnt;
        cbei.pszText        = IInf[iCnt].pszText;
        cbei.cchTextMax     = sizeof(IInf[iCnt].pszText);
        cbei.iImage         = IInf[iCnt].iImage;
        cbei.iSelectedImage = IInf[iCnt].iSelectedImage;
        cbei.iIndent        = IInf[iCnt].iIndent;

        // Tell the ComboBoxEx to add the item. Return FALSE if
        // this fails.
        if(SendMessage(hwndCB,CBEM_INSERTITEM,0,(LPARAM)&cbei) == -1)
            return FALSE;
    }

    // Assign the existing image list to the ComboBoxEx control
    // and return TRUE.
    SendMessage(hwndCB,CBEM_SETIMAGELIST,0,(LPARAM)g_himl);

    // Set size of control to make sure it's displayed correctly now
    // that the image list is set.
    SetWindowPos(hwndCB,NULL,20,20,250,120,SWP_NOACTIVATE);

    return TRUE;
}

Supporting Callback Items

If your application is going to use callback items in a ComboBoxEx control, it must be prepared to handle the CBEN_GETDISPINFO notification message. A ComboBoxEx control sends this notification whenever it needs the owner to provide specific item information. For more information about callback items, see Callback Items.

The following application-defined function processes CBEN_GETDISPINFO by providing attributes for a given item. Note that it sets the mask member of the incoming COMBOBOXEXITEM structure to CBEIF_DI_SETITEM. Setting mask to this value makes the control retain the item information so it will not need to request the information again.

// DoItemCallback - Processes CBEN_GETDISPINFO by providing item
// attributes for a given callback item.

void WINAPI DoItemCallback(PNMCOMBOBOXEX pNMCBex)
{
    DWORD dwMask = pNMCBex->ceItem.mask;

    if(dwMask & CBEIF_TEXT)
        ;// Provide item text.

    if(dwMask & CBEIF_IMAGE)
        ;// Provide an item image index.

    /*
     * Provide other callback information as desired.
     */

    // Make the ComboBoxEx control hold onto the item information.
    pNMCBex->ceItem.mask = CBEIF_DI_SETITEM;
}

Processing ComboBoxEx Notifications

A ComboBoxEx control notifies its parent window of events by sending WM_NOTIFY messages. Because the control uses a child combo box, it forwards all WM_COMMAND notification messages it receives to the parent window to be processed. Therefore, your application must be prepared to process WM_NOTIFY messages from the ComboBoxEx and WM_COMMAND messages forwarded from the ComboBoxEx child combo box control.

The example in this section handles the WM_NOTIFY and WM_COMMAND messages from a ComboBoxEx control by calling a corresponding application-defined function to process them.

LRESULT CALLBACK WndProc (HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
    switch(msg){
        case WM_COMMAND:
            // If this is an "old style" combo box notification, handle it.
            if((HWND)lParam == g_hwndCB)
                DoOldNotify(hwnd,  wParam);
            break;

        case WM_NOTIFY:
            return (DoCBEXNotify(hwnd, lParam));

        case WM_PAINT:
            hdc = BeginPaint(hwnd, &ps);
            EndPaint(hwnd, &ps);
            break;

        case WM_DESTROY:
            PostQuitMessage(0);
            break;

        default:
            return DefWindowProc(hwnd, msg, wParam, lParam);
            break;
    }
    return FALSE;
}


ComboBoxEx Control Extended Styles

ComboBoxEx controls support most standard combo box control styles. Additionally, ComboBoxEx controls support the following extended styles, which you can set and retrieve by using CBEM_SETEXTENDEDSTYLE and CBEM_GETEXTENDEDSTYLE messages:

CBES_EX_CASESENSITIVE
String searches in the list will be case sensitive. This includes searches as a result of text being typed in the edit box and the CB_FINDSTRINGEXACT message.
CBES_EX_NOEDITIMAGE
The edit box and the dropdown list will not display item images.
CBES_EX_NOEDITIMAGEINDENT
The edit box and the dropdown list will not display item images.
CBES_EX_NOSIZELIMIT
Allows the ComboBoxEx control to be vertically sized smaller than its contained combo box control. If the ComboBoxEx is sized smaller than the combo box, the combo box will be clipped.
CBES_EX_PATHWORDBREAKPROC
Windows NT only. The edit box will use the slash (/), backslash (\), and period (.) characters as word delimiters. This makes keyboard shortcuts for word-by-word cursor movement (CTRL+ARROW) effective in path names and URLs.

Note: if you try to set an extended style for a ComboBoxEx control created with the CBS_SIMPLE style, it might not repaint properly. The CBS_SIMPLE style also does not work properly with the CBES_EX_PATHWORDBREAKPROC extended style.


CBEM_DELETEITEM

Removes an item from a ComboBoxEx control.

CBEM_DELETEITEM
    wParam = (WPARAM)(int) iIndex;
    lParam = 0;

Parameters

iIndex
Zero-based index of the item to be removed.

Return Values

Returns an INT value that represents the number of items remaining in the control. If iIndex is invalid, the message returns CB_ERR.

Remarks

This message maps to the combo box control message CB_DELETESTRING.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_GETCOMBOCONTROL

Retrieves the handle to the child combo box control.

CBEM_GETCOMBOCONTROL
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the combo box control within the ComboBoxEx control.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_GETEDITCONTROL

Retrieves the handle to the edit control portion of a ComboBoxEx control. A ComboBoxEx control uses an edit box when it is set to the CBS_DROPDOWN style.

CBEM_GETEDITCONTROL
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the edit control within the ComboBoxEx control if it uses the CBS_DROPDOWN style. Otherwise, the message returns NULL.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_GETEXTENDEDSTYLE

Retrieves the extended styles that are in use for a ComboBoxEx control.

CBEM_GETEXTENDEDSTYLE
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that contains the ComboBoxEx control extended styles in use for the control.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_GETIMAGELIST

Retrieves the handle to an image list assigned to a ComboBoxEx control.

CBEM_GETIMAGELIST
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the image list assigned to the control if successful, or NULL otherwise.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_GETITEM

Retrieves item information for a given ComboBoxEx item.

CBEM_GETITEM
    wParam = 0;
    lParam = (LPARAM)(PCOMBOBOXEXITEM) pCBItem;

Parameters

pCBItem
Address of a COMBOBOXEXITEM structure that will receive the item information.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

When the message is sent, the iItem and mask members of the structure must be set to indicate the index of the target item and the type of information to be retrieved. Other members are set as needed. For example, to retrieve text, you must set the CBEIF_TEXT flag in mask, and assign a value to cchTextMax. Setting the iItem member to -1 will retrieve the item displayed in the edit control.

If the CBEIF_TEXT flag is set in the mask member of the COMBOBOXEXITEM structure, the control may change the pszText member of the the structure to point to the new text instead of filling the buffer with the requested text. Applications should not assume that the text will always be placed in the requested buffer.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control.

CBEM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

CBEM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_HASEDITCHANGED

Determines whether or not the user has changed the text of a ComboBoxEx edit control.

CBEM_HASEDITCHANGED
    wParam = 0;
    lParam = 0;

Return Values

Returns TRUE if the text in the control's edit box has been changed, or FALSE otherwise.

Remarks

A ComboBoxEx control uses an edit box control when it is set to the CBS_DROPDOWN style. You can retrieve the edit box control's window handle by sending a CBEM_GETEDITCONTROL message.

When the user begins editing, you will receive a CBEN_BEGINEDIT notification. When editing is complete, or the focus changes, you will receive a CBEN_ENDEDIT notification. The CBEM_HASEDITCHANGED message is only useful for determining whether or not the text has been changed if it is sent before the CBEN_ENDEDIT notification. If the message is sent afterwards, it will return FALSE. For example, suppose the user starts to edit the text in the edit box but changes focus, generating a CBEN_ENDEDIT notification. If you then send a CBEM_HASEDITCHANGED message, it will return FALSE, even though the text has been changed.

The CBS_SIMPLE style does not work correctly with CBEM_HASEDITCHANGED.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_INSERTITEM

Inserts a new item in a ComboBoxEx control.

CBEM_INSERTITEM
    wParam = 0;
    lParam = (LPARAM)(const COMBOBOXEXITEM FAR *) lpcCBItem;

Parameters

lpcCBItem
Address of a COMBOBOXEXITEM structure that contains information about the item to be inserted. When the message is sent, the iItem member must be set to indicate the zero-based index at which to insert the item. To insert an item at the end of the list, set the iItem member to -1.

Return Values

Returns the index at which the new item was inserted if successful, or -1 otherwise.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_SETEXTENDEDSTYLE

Sets extended styles within a ComboBoxEx control.

CBEM_SETEXTENDEDSTYLE
    wParam = (WPARAM)(DWORD) dwExMask;
    lParam = (LPARAM)(DWORD) dwExStyle;

Parameters

dwExMask
A DWORD value that indicates which styles in dwExStyle are to be affected. Only the extended styles in dwExMask will be changed. If this parameter is zero, then all of the styles in dwExStyle will be affected.
dwExStyle
A DWORD value that contains the ComboBoxEx control extended styles to set for the control.

Return Values

Returns a DWORD value that contains the extended styles previously used for the control.

Remarks

dwExMask enables you to modify one or more extended styles without having to retrieve the existing styles first. For example, if you pass CBES_EX_NOEDITIMAGE for dwExMask and 0 for dwExStyle, the CBES_EX_NOEDITIMAGE style will be cleared, but all other styles will remain the same.

If you try to set an extended style for a ComboBoxEx control created with the CBS_SIMPLE style, it may not repaint properly.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_SETIMAGELIST

Sets an image list for a ComboBoxEx control.

CBEM_SETIMAGELIST
    wParam = 0;
    lParam = (LPARAM)(HIMAGELIST) himl;

Parameters

himl
Handle to the image list to be set for the control.

Return Values

Returns the handle to the image list previously associated with the control, or returns NULL if no image list was previously set.

Remarks

Note The height of images within your image list might change the size requirements of the ComboBoxEx control. It is recommended that you resize the control after sending this message to ensure that it is displayed properly.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_SETITEM

Sets the attributes for an item in a ComboBoxEx control.

CBEM_SETITEM
    wParam = 0;
    lParam = (LPARAM) (const COMBOBOXEXITEM FAR *) lpcCBItem;

Parameters

lpcCBItem
Address of a COMBOBOXEXITEM structure that contains the item information to be set. When the message is sent, the mask member of the structure must be set to indicate which attributes are valid and the iItem member must specify the zero-based index of the item to be modified. Setting the iItem member to -1 will modify the item displayed in the edit control.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message enables you to change the character set used by the control at run time rather than having to re-create the control.

CBEM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

CBEM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEN_BEGINEDIT

Sent when the user activates the drop-down list or clicks in the control's edit box. This notification is sent in the form of a WM_NOTIFY message.

CBEN_BEGINEDIT
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains information about the notification.

Return Values

The application processing this notification must return zero.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEN_DELETEITEM

Sent when an item has been deleted. This notification is sent in the form of a WM_NOTIFY message.

CBEN_DELETEITEM
    pCBEx= (PNMCOMBOBOXEX) lParam;

Parameters

pCBEx
Address of an NMCOMBOBOXEX structure that contains information about the notification and the deleted item.

Return Values

The application processing this notification must return zero.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEN_DRAGBEGIN

Sent when the user begins dragging the image of the item displayed in the edit portion of the control. This notification is sent in the form of a WM_NOTIFY message.

CBEN_DRAGBEGIN
    lpnmdb = (LPNMCBEDRAGBEGIN) lParam;

Parameters

lpnmdb
Address of a NMCBEDRAGBEGIN structure that contains information about the notification.

Return Values

The return value is ignored.

Remarks

If the receiving application implements drag-and-drop functionality from the control, the application will begin the drag-and-drop operation in response to this notification.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEN_ENDEDIT

Sent when the user has concluded an operation within the edit box or has selected an item from the control's drop-down list. This notification is sent in the form of a WM_NOTIFY message.

CBEN_ENDEDIT
    pnmEditInfo = (PNMCBEENDEDIT) lParam;

Parameters

pnmEditInfo
Address of an NMCBEENDEDIT structure that contains information about how the user concluded the edit operation.

Return Values

To accept the notification and allow the control to display the selected item, return FALSE. To abort the edit selection, return TRUE.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEN_GETDISPINFO

Sent to retrieve display information about a callback item. This notification is sent in the form of a WM_NOTIFY message.

CBEN_GETDISPINFO
    pDispInfo = (PNMCOMBOBOXEX) lParam;

Parameters

pDispInfo
Address of an NMCOMBOBOXEX structure that contains information about the notification.

Return Values

The application processing this notification must return zero.

Remarks

The NMCOMBOBOXEX structure contains a COMBOBOXEXITEM structure. The mask member specifies the information being requested by the control.

Fill the appropriate members of the structure to return the requested information to the control. If your message handler sets the mask member of the COMBOBOXEXITEM structure to CBEIF_DI_SETITEM, the header control stores the information and will not request it again.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


CBEN_INSERTITEM

Sent when a new item has been inserted in the control. This notification is sent in the form of a WM_NOTIFY message.

CBEN_INSERTITEM
    pNMInfo = (PNMCOMBOBOXEX) lParam;

Parameters

pNMInfo
Address of an NMCOMBOBOXEX structure containing information about the notification and the item that was inserted.

Return Values

The application processing this notification must return zero.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_SETCURSOR (ComboBoxEx)

Notifies a ComboBoxEx control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.

NM_SETCURSOR
    lpnmm = (LPNMMOUSE) lParam;

Parameters

lpnmm
Address of an NMMOUSE structure that contains additional information about this notification message.

Return Values

Return zero to enable the control to set the cursor or nonzero to prevent the control from setting the cursor.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


COMBOBOXEXITEM

Contains information about an item in a ComboBoxEx control.

typedef struct {
    UINT    mask;
    INT_PTR iItem;
    LPTSTR  pszText;
    int     cchTextMax;
    int     iImage;
    int     iSelectedImage;
    int     iOverlay;
    int     iIndent;
    LPARAM  lParam;
} COMBOBOXEXITEM, *PCOMBOBOXEXITEM;

Members

mask
Set of bit flags that specify attributes of this structure or of an operation that is using this structure. The flags specify members that are valid or must be filled in. This member can be a combination of the following values:
Flag | Description
CBEIF_DI_SETITEM | Set this flag when processing CBEN_GETDISPINFO; the ComboBoxEx control will retain the supplied information and will not request it again.
CBEIF_IMAGE | The iImage member is valid or must be filled in.
CBEIF_INDENT | The iIndent member is valid or must be filled in.
CBEIF_LPARAM | The lParam member is valid or must be filled in.
CBEIF_OVERLAY | The iOverlay member is valid or must be filled in.
CBEIF_SELECTEDIMAGE | The iSelectedImage member is valid or must be filled in.
CBEIF_TEXT | The pszText member is valid or must be filled in.
iItem
Zero-based index of the item.
pszText
Address of a character buffer that contains or receives the item's text. If text information is being retrieved, this member must be set to the address of a character buffer that will receive the text. The size of this buffer must also be indicated in cchTextMax. If this member is set to LPSTR_TEXTCALLBACK, the control will request the information by using the CBEN_GETDISPINFO notification messages.
cchTextMax
Length of pszText, in characters. If text information is being set, this member is ignored.
iImage
Zero-based index of an image within the image list. The specified image will be displayed for the item when it is not selected. If this member is set to I_IMAGECALLBACK, the control will request the information by using CBEN_GETDISPINFO notification messages.
iSelectedImage
Zero-based index of an image within the image list. The specified image will be displayed for the item when it is selected. If this member is set to I_IMAGECALLBACK, the control will request the information by using CBEN_GETDISPINFO notification messages.
iOverlay
One-based index of an overlay image within the image list. If this member is set to I_IMAGECALLBACK, the control will request the information by using CBEN_GETDISPINFO notification messages.
iIndent
Number of indent spaces to display for the item. Each indentation equals 10 pixels. If this member is set to I_INDENTCALLBACK, the control will request the information by using CBEN_GETDISPINFO notification messages.
lParam
A value specific to the item.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMCBEDRAGBEGIN

Contains information used with the CBEN_DRAGBEGIN notification message.

typedef struct {
    NMHDR hdr;
    int iItemid;
    TCHAR szText[CBEMAXSTRLEN];
}NMCBEDRAGBEGIN, *LPNMCBEDRAGBEGIN;

Members

hdr
NMHDR structure that contains information about the notification message.
iItemid
Zero-based index of the item being dragged. This value will always be -1, indicating that the item being dragged is the item displayed in the edit portion of the control.
szText
Character buffer that contains the text of the item being dragged.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMCBEENDEDIT

Contains information about the conclusion of an edit operation within a ComboBoxEx control. This structure is used with the CBEN_ENDEDIT notification message.

typedef struct {
    NMHDR  hdr;
    BOOL   fChanged;
    int    iNewSelection;
    TCHAR  szText[CBEMAXSTRLEN]; // CBEMAXSTRLEN is 260
    int    iWhy;
} NMCBEENDEDIT, *PNMCBEENDEDIT;

Members

hdr
NMHDR structure that contains information about the notification message.
fChanged
Value indicating whether the contents of the control's edit box have changed. This value is nonzero if the contents have been modified, or zero otherwise.
iNewSelection
Zero-based index of the item that will be selected after completing the edit operation. This value can be CB_ERR if no item will be selected.
szText
Zero-terminated string that contains the text from within the control's edit box.
iWhy
Value that specifies the action that generated the CBEN_ENDEDIT notification message. This value can be one of the following:
CBENF_DROPDOWN | The user activated the drop-down list.
CBENF_ESCAPE | The user pressed ESC.
CBENF_KILLFOCUS | The edit box lost the keyboard focus.
CBENF_RETURN | The user completed the edit operation by pressing ENTER.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMCOMBOBOXEX

Holds information specific to ComboBoxEx items for use with notification messages.

typedef struct {
    NMHDR hdr;
    COMBOBOXEXITEM ceItem;
} NMCOMBOBOXEX, *PNMCOMBOBOXEX;

Members

hdr
NMHDR structure that contains information about the notification message.
ceItem
COMBOBOXEXITEM structure that holds item information specific to the current notification. Upon receiving a notification message, the COMBOBOXEXITEM structure holds information required for the owner to respond. The members of this structure are often used as fields for the owner to return values in response to the notification.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Date and Time Picker Controls

A date and time picker (DTP) control provides a simple and intuitive interface through which to exchange date and time information with a user. For example, with a DTP control you can ask the user to enter a date and then retrieve his or her selection with ease.

  • About Date and Time Picker Controls
  • Using Date and Time Picker Controls
  • Date and Time Picker Control Reference

About Date and Time Picker Controls

Date and time picker controls are implemented in version 4.70 and later of Comctl32.dll. To create a DTP control call CreateWindowEx and specify DATETIMEPICK_CLASS as the window class. The class is registered when the date and time picker class is loaded from the common control dynamic-link library (DLL). Register this class by calling the InitCommonControlsEx function, while specifying the ICC_DATE_CLASSES bit flag in the accompanying INITCOMMONCONTROLSEX structure.

Notes:

  • Windows does not support dates prior to 1601. See FILETIME for details.
  • The DTP control is based on the Gregorian calendar, which was introduced in 1753. It will not calculate dates that are consistent with the Julian calendar that was in use prior to 1753.

Date and Time Picker User Interface

The client area of a date and time picker (DTP) control displays date and time information and acts as the interface through which users modify the information. The control's display consists of fields that are defined by the control's format string. Additionally, the control will display a check box when the DTS_SHOWNONE style is in use.

Each field in the control displays a portion of the date and time information that the control stores internally. The user can click a field to set keyboard focus and then provide keyboard input to change the information represented by that field. The DTP control automatically updates internal information based on the user's input. The control recognizes the following as valid input.
Input Category | Description
Arrow Keys | The control accepts arrow keys to navigate the fields in the control and change values. The user can press the LEFT ARROW or RIGHT ARROW keys to move through the control. If the user attempts to move past the last field in a given direction, the keyboard focus "wraps around" to the field on the opposite side of the control. The UP ARROW and DOWN ARROW keys change values in the current field incrementally.
End and Home | The control accepts the VK_END and VK_HOME virtual keys to change the value within the current field to its upper and lower limits, respectively.
Function Keys | The F2 key activates edit mode. The F4 key causes the control to display a drop-down month calendar control (pressing ALT+DOWN ARROW does this as well).
Numbers | The control accepts numeric input in two-character segments. If the value entered by the user is invalid (like setting the month to 14), the control rejects it and resets the display to the previous value.
Plus and Minus | The control accepts the VK_ADD and VK_SUBTRACT virtual keys from the numeric keypad to increment and decrement the value in the current field.

DTP controls that do not use the DTS_UPDOWN style display an arrow button. If the user clicks this button, a month calendar control drops down. The user can select a specific date by clicking an area of the calendar.

Date and Time Picker Control Styles and Formats

Date and time picker (DTP) controls have several styles that determine a control's appearance and behavior. Specify the style when creating the control with the dwStyle parameter of CreateWindowEx. To retrieve or change the window style after you have created the control, use GetWindowLong and SetWindowLong.

Preset Formats

There are three preset formats available for displaying the date and one for displaying time. Set these formats by choosing one of the following window styles:

DTS_LONGDATEFORMAT
The display will look like: "Friday, April 19, 1996".
DTS_SHORTDATEFORMAT
The display will look like: "4/19/96".
DTS_SHORTDATECENTURYFORMAT
Version 5.80. The display will look like: "4/19/1996".
DTS_TIMEFORMAT
The display will look like: "5:31:42 PM".

Custom formats

A DTP control relies on a format string to determine how it will display fields of information. If the preset formats are not sufficient, you can create a custom format by defining your own format string. Custom formats provide greater flexibility for an application. They enable you to specify the order in which the control will display fields of information. You can include body text as well as callback fields for requesting information from the user. Once the string is created, you assign it to the DTP control with a DTM_SETFORMAT message.

Format Strings

A DTP format string consists of a series of elements that represent a particular piece of information and define its display format. The elements will be displayed in the order they appear in the format string.

Date and time format elements will be replaced by the actual date and time. They are defined by the following groups of characters:

Element | Description
"d" | The one- or two-digit day.
"dd" | The two-digit day. Single-digit day values are preceded by a zero.
"ddd" | The three-character weekday abbreviation.
"dddd" | The full weekday name.
"h" | The one- or two-digit hour in 12-hour format.
"hh" | The two-digit hour in 12-hour format. Single-digit values are preceded by a zero.
"H" | The one- or two-digit hour in 24-hour format.
"HH" | The two-digit hour in 24-hour format. Single-digit values are preceded by a zero.
"m" | The one- or two-digit minute.
"mm" | The two-digit minute. Single-digit values are preceded by a zero.
"M" | The one- or two-digit month number.
"MM" | The two-digit month number. Single-digit values are preceded by a zero.
"MMM" | The three-character month abbreviation.
"MMMM" | The full month name.
"t" | The one-letter AM/PM abbreviation (that is, AM is displayed as "A").
"tt" | The two-letter AM/PM abbreviation (that is, AM is displayed as "AM").
"yy" | The last two digits of the year (that is, 1996 would be displayed as "96").
"yyyy" | The full year (that is, 1996 would be displayed as "1996").

To make the information more readable, you can add body text to the format string by enclosing it in single quotes. Spaces and punctuation marks do not need to be quoted.

Note Nonformat characters that are not delimited by single quotes will result in unpredictable display by the DTP control.

For example, to display the current date with the format "'Today is: 04:22:31 Tuesday Mar 23, 1996", the format string is "'Today is: 'hh':'m':'s dddd MMM dd', 'yyyy". To include a single quote in your body text, use two consecutive single quotes. For example, "'Don''t forget' MMM dd',' yyyy" produces output that looks like: Don't forget Mar 23, 1996. It is not necessary to use quotes with the comma, so "'Don''t forget' MMM dd, yyyy" is also valid, and produces the same output.

Callback fields

In addition to the standard format characters and body text, you can also define certain parts of the display as callback fields. These fields can be used to query the user for information. To declare a callback field, include one or more "X" characters (ASCII Code 88) anywhere in the format string. You can create callback fields that have a unique identity by repeating the "X" character. Thus, the format string "XX dddd MMM dd', 'yyy XXX" contains two unique callback fields, "XX" and "XXX". Like other DTP control fields, callback fields are displayed in left-to-right order based on their location in the format string.

When the DTP control parses the format string and encounters a callback field, it sends DTN_FORMAT and DTN_FORMATQUERY notification messages. The format string element corresponding to the callback field is included with the notifications to allow the receiving application to determine which callback field is being queried. The owner of the control must respond to these notifications to ensure that the custom information is properly displayed.

Date and Time Picker Control Notification Messages

A date and time picker (DTP) control sends notification messages when it receives user input or processes and reacts to callback fields. The parent of the control receives these notification messages in the form of WM_NOTIFY messages.

The following notification messages are used with DTP controls.
Notification | Description
DTN_CLOSEUP | Indicates that the drop-down month calendar is about to be removed.
DTN_DATETIMECHANGE | Signals a change within the DTP control.
DTN_DROPDOWN | Indicates that the drop-down month calendar is about to be displayed.
DTN_FORMAT | Requests text to display in a portion of the format string described as a callback field.
DTN_FORMATQUERY | Requests information about the maximum allowable size of the text to be displayed in a callback field.
DTN_USERSTRING | Signals the end of a user's edit operation within the control. This notification is sent only by DTP controls that use the DTS_APPCANPARSE style.
DTN_WMKEYDOWN | Signals that the user has pressed a key in a callback field of the DTP control.

Using Date and Time Picker Controls

This section provides information and sample code for implementing a date and time picker control.

Creating a Date and Time Picker Control

To create a date and time picker (DTP) control, use the CreateWindowEx function, specifying DATETIMEPICK_CLASS as the window class. You must first register the window class by calling the InitCommonControlsEx function, while specifying the ICC_DATE_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.

The following example creates a DTP control in an existing modeless dialog box. It uses the DTS_SHOWNONE style to enable the user to simulate deactivation of the date within the control.

//  CreateDatePick creates a DTP control within a dialog box.
//  Returns the handle to the new DTP control if successful, or NULL
//  otherwise.
//
//    hwndMain - The handle to the main window.
//    g_hinst - global handle to the program instance.
HWND WINAPI CreateDatePick(hwndMain)
{
    HWND hwndDP = NULL;
    HWND hwndDlg = NULL;
    INITCOMMONCONTROLSEX icex;

    icex.dwSize = sizeof(icex);
    icex.dwICC = ICC_DATE_CLASSES;

    InitCommonControlsEx(&icex);

    hwndDlg = CreateDialog  (g_hinst,
                             MAKEINTRESOURCE(IDD_DIALOG1),
                             hwndMain,
                             DlgProc);

    if(hwnDlg)
        hwndDP = CreateWindowEx(0,
                             DATETIMEPICK_CLASS,
                             "DateTime",
                             WS_BORDER|WS_CHILD|WS_VISIBLE|DTS_SHOWNONE,
                             20,50,220,20,
                             hwndDlg,
                             NULL,
                             g_hinst,
                             NULL);
    return (hwndDP);
}

Processing Date and Time Picker Notifications

The following example processes the DTN_DATETIMECHANGE, DTN_FORMAT, DTN_FORMATQUERY, and DTN_WMKEYDOWN notifications by calling the DoDateTimeChange, DoFormatQuery, DoFormat, and DoWMKeydown application-defined functions.

Other topics in this chapter provide additional information on these notifications. See Supporting Callback Fields and Processing the DTN_DATETIMECHANGE Notification Message for additional information.

BOOL WINAPI DoNotify(HWND hwnd, WPARAM wParam, LPARAM lParam)
{
    LPNMHDR hdr = (LPNMHDR)lParam;

    switch(hdr->code){
        case DTN_DATETIMECHANGE:{
            LPNMDATETIMECHANGE lpChange = (LPNMDATETIMECHANGE)lParam;
            DoDateTimeChange(lpChange);
        }
        break;

        case DTN_FORMATQUERY:{
            LPNMDATETIMEFORMATQUERY lpDTFQuery = (LPNMDATETIMEFORMATQUERY)lParam;

            // Process DTN_FORMATQUERY to ensure that the control
            // displays callback information properly.
            DoFormatQuery(hdr->hwndFrom, lpDTFQuery);
        }
        break;

        case DTN_FORMAT:{
            LPNMDATETIMEFORMAT lpNMFormat = (LPNMDATETIMEFORMAT) lParam;

            // Process DTN_FORMAT to supply information about callback
            // fields (fields) in the DTP control.
            DoFormat(hdr->hwndFrom, lpNMFormat);
        }
        break;

        case DTN_WMKEYDOWN:{
            LPNMDATETIMEWMKEYDOWN lpDTKeystroke =
                            (LPNMDATETIMEWMKEYDOWN)lParam;

            // Process DTN_WMKEYDOWN to respond to a user's keystroke in
            // a callback field.
            DoWMKeydown(hdr->hwndFrom, lpDTKeystroke);
        }
        break;
    }
    // All of the above notifications require the owner to return zero.
    return FALSE;
}

Processing the DTN_DATETIMECHANGE Notification

A date and time picker (DTP) control sends the DTN_DATETIMECHANGE message whenever a change occurs. This message will be generated if the user changes one of the fields in the control or changes the state of the control's check box (DTS_SHOWNONE only).

The following example is an application-defined function designed to update a static control within a dialog box. The text within the static control is changed to reflect the current state of the DTP control.

void WINAPI DoDateTimeChange(LPNMDATETIMECHANGE lpChange)
{
    // If the user has unchecked the DTP's check box, change the
    // text in a static control to show the appropriate message.
    //
    // g_hwndDlg - a program-global address of a dialog box.

    if(lpChange->dwFlags == GDT_NONE)
        SetDlgItemText(g_hwndDlg, IDC_STATUS, "Disabled");
    else
        SetDlgItemText(g_hwndDlg, IDC_STATUS, "Active");
}

Supporting Callback Fields in a DTP control

If you plan to use callback fields with the date and time picker (DTP) controls in your application, you must be prepared to handle DTN_FORMATQUERY, DTN_FORMAT, and DTN_WMKEYDOWN notification messages. For additional information about callback fields, see Callback fields.

This section contains information about how your application can process these notification messages. There are several examples of source code for application-defined functions. The following list shows notification messages with sample functions that process them.
Notification Message | Sample Function
DTN_FORMATQUERY | DoFormatQuery
DTN_FORMAT | DoFormat
DTN_WMKEYDOWN | DoWMKeydown

The DoFormatQuery application-defined function

A date and time picker (DTP) control sends a DTN_FORMATQUERY notification message to request information about the maximum possible size of a callback field within the control. Handling this message ensures that all fields are displayed properly. The following DoFormatQuery application-defined function processes the DTN_FORMATQUERY notification message by calculating the width of the widest possible string for a given callback field.

//
//  DoFormatQuery processes DTN_FORMATQUERY messages to ensure that the
//  DTP control displays callback fields properly.
//
void WINAPI DoFormatQuery(
 HWND hwndDP,
 LPNMDATETIMEFORMATQUERY lpDTFQuery)
{
    HDC hdc;
    HFONT hFont, hOrigFont;

    //  Prepare the device context for GetTextExtentPoint32 call.
    hdc = GetDC(hwndDP);

    hFont = FORWARD_WM_GETFONT(hwndDP, SendMessage);

    if(!hFont)
        hFont = (HFONT)GetStockObject(DEFAULT_GUI_FONT);

    hOrigFont = SelectObject(hdc, hFont);

    // Check to see if this is the callback segment desired. If so,
    // use the longest text segment to determine the maximum
    // width of the callback field, and then place the information into
    // the NMDATETIMEFORMATQUERY structure.
    if(!lstrcmp("XX",lpDTFQuery->pszFormat))
    GetTextExtentPoint32 (hdc,
                          "366",  // widest date string
                          3,
                          &lpDTFQuery->szMax);

    // Reset the font in the device context; then release the context.
    SelectObject(hdc,hOrigFont);
    ReleaseDC(hwndDP, hdc);
}

The DoFormat application-defined function

A date and time picker (DTP) control sends the DTN_FORMAT notification to request text that will be displayed in a callback field of the control. By handling this notification message, you allow the DTP control to display information that it does not natively support.

The following DoFormat application-defined function processes DTN_FORMAT notification messages by providing a text string for a callback field. DoFormat calls the GetDayNum application-defined function to request the day number to be used in the callback string.

//  DoFormat processes DTN_FORMAT to provide the text for a callback
//  field in a DTP control. In this example, the callback field
//  contains a value for the day of year. The function calls the
//  application-defined function GetDayNum (below) to retrieve
//  the correct value.
//
void WINAPI DoFormat(HWND hwndDP, LPNMDATETIMEFORMAT lpDTFormat)
{
    wsprintf(lpDTFormat->szDisplay,"%d",GetDayNum(&lpDTFormat->st));
}

The GetDayNum application-defined function

The application-defined sample function DoFormat calls the following GetDayNum application-defined function to request the day number based on the current date. GetDayNum returns an INT value that represents the current day of the year, from 0 to 366. This function calls another application-defined function, IsLeapYr, during processing.

//
//  GetDayNum is an application-defined function that retrieves the
//  correct day of year value based on the contents of a given
//  SYSTEMTIME structure. This function calls the IsLeapYr function to
//  check if the current year is a leap year. The function returns an
//  integer value that represents the day of year.
//
int WINAPI GetDayNum(SYSTEMTIME *st)
{
    int iNormYearAccum[ ] = {31,59,90,120,151,181,
                            212,243,273,304,334,365};

    int iLeapYearAccum[ ] = {31,60,91,121,152,182,
                            213,244,274,305,335,366};
    int iDayNum;

    if(IsLeapYr(st->wYear))
        iDayNum=iLeapYearAccum[st->wMonth-2]+st->wDay;
    else
        iDayNum=iNormYearAccum[st->wMonth-2]+st->wDay;

    return (iDayNum);
}

The IsLeapYr application-defined function

The application-defined sample function GetDayNum calls the IsLeapYr function to determine whether the current year is a leap year. IsLeapYr returns a BOOL value that is TRUE if it is a leap year and FALSE otherwise.

//
//  IsLeapYr determines if a given year value is a leap year. The
//  function returns TRUE if the current year is a leap year, and
//  FALSE otherwise.
//
BOOL WINAPI IsLeapYr(int iYear)
{
    int iQuotient;
    BOOL fLeapYr = FALSE;

    // If the year is evenly divisible by 4 and not by 100, then this
    // is a leap year.
    if(!(iYear%4) && (iYear%100))
        fLeapYr = TRUE;
    else{
        // If the year is evenly divisible by 4 and 100, then check to
        // see if the quotient of year divided by 100 is also evenly
        // divisible by 4. If it is, then this is a leap year.
        if(!(iYear%4) && !(iYear%100)){
            iQuotient = iYear/100;
            if(!(iQuotient%4)) fLeapYr = TRUE;
        }
    }
    return (fLeapYr);
}

The DoWMKeydown application-defined function

Date and time picker (DTP) controls send the DTN_WMKEYDOWN message to report that the user has typed input in a callback field. Handling this message allows you to emulate the same keyboard responses supported for standard DTP fields or provide custom responses. The following DoWMKeydown application-defined function provides an example of how DTN_WMKEYDOWN notifications can be handled.

//
//  DoWMKeydown increments or decrements the day of month according
//  to user keyboard input.
//
void WINAPI DoWMKeydown(
 HWND hwndDP,
 LPNMDATETIMEWMKEYDOWN lpDTKeystroke)
{
    int delta =1;

    if(!lstrcmp(lpDTKeystroke->pszFormat,"XX")){
        switch(lpDTKeystroke->nVirtKey){
            case VK_DOWN:
            case VK_SUBTRACT:
                delta = -1;  // fall through

            case VK_UP:
            case VK_ADD:
                lpDTKeystroke->st.wDay += delta;
                break;
        }
    }
}


Date and Time Picker Control Styles

The window styles listed here are specific to date and time picker controls. The DTS_XXXFORMAT styles that define the display format cannot be combined. If none of the format styles are suitable, use a DTM_SETFORMAT message to define a custom format.
DTS_APPCANPARSE | Allows the owner to parse user input and take necessary action. It enables users to edit within the client area of the control when they press the F2 key. The control sends DTN_USERSTRING notification messages when users are finished.
DTS_LONGDATEFORMAT | Displays the date in long format. The default format string for this style is defined by LOCALE_SLONGDATEFORMAT, which produces output like "Friday, April 19, 1996".
DTS_RIGHTALIGN | The drop-down month calendar will be right-aligned with the control instead of left-aligned, which is the default.
DTS_SHOWNONE | It is possible to have no date currently selected in the control. With this style, the control displays a check box that users can check once they have entered or selected a date. Until this check box is checked, the application will not be able to retrieve the date from the control because, in essence, the control has no date. This state can be set with the DTM_SETSYSTEMTIME message or queried with the DTM_GETSYSTEMTIME message.
DTS_SHORTDATEFORMAT | Displays the date in short format. The default format string for this style is defined by LOCALE_SSHORTDATE, which produces output like "4/19/96".
DTS_SHORTDATECENTURYFORMAT | Version 5.80. Similar to the DTS_SHORTDATEFORMAT style, except the year is a four-digit field. The default format string for this style is based on LOCALE_SSHORTDATE. The output looks like: "4/19/1996".
DTS_TIMEFORMAT | Displays the time. The default format string for this style is defined by LOCALE_STIMEFORMAT, which produces output like "5:31:42 PM".
DTS_UPDOWN | Places an up-down control to the right of the DTP control to modify date-time values. This style can be used in place of the drop-down month calendar, which is the default style.


DTM_GETMCCOLOR

Retrieves the color for a given portion of the month calendar within a date and time picker (DTP) control. You can send this message explicitly or use the DateTime_GetMonthCalColor macro.

DTM_GETMCCOLOR
    wParam = (WPARAM)(INT)iColor;
    lParam = 0;

Parameters

iColor
INT value specifying which month calendar color to retrieve. This value can be one of the following:
MCSC_BACKGROUND | Retrieve the background color displayed between months.
MCSC_MONTHBK | Retrieve the background color displayed within the month.
MCSC_TEXT | Retrieve the color used to display text within a month.
MCSC_TITLEBK | Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT | Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. The message returns -1 if unsuccessful.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_GETMCFONT

Retrieves the font that the date and time picker (DTP) control's child month calendar control is currently using. You can send this message explicitly or use the DateTime_GetMonthCalFont macro.

DTM_GETMCFONT
    wParam = 0;
    lParam = 0;

Return Values

Returns an HFONT value that is the handle to the current font.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


DTM_GETMONTHCAL

Retrieves the handle to a date and time picker's (DTP) child month calendar control. You can send this message explicitly or use the DateTime_GetMonthCal macro.

DTM_GETMONTHCAL
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to a DTP control's child month calendar control if successful, or NULL otherwise.

Remarks

DTP controls create a child month calendar control when the user clicks the drop-down arrow. When the month calendar is no longer needed, it is destroyed. So your application must not rely on a static handle to the DTP control's child month calendar.

See Also

DTN_CLOSEUP, DTN_DROPDOWN

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_GETRANGE

Retrieves the current minimum and maximum allowable system times for a date and time picker (DTP) control. You can send this message explicitly or use the DateTime_GetRange macro.

DTM_GETRANGE
    wParam = 0;
    lParam = (LPARAM) lpSysTimeArray;

Parameters

lpSysTimeArray
Address of a two-element array of SYSTEMTIME structures.

Return Values

Returns a DWORD value that is a combination of GDTR_MIN or GDTR_MAX. The first element of the SYSTEMTIME array contains the minimum allowable time if GDTR_MIN is set. The second element of the SYSTEMTIME array contains the maximum allowable time if GDTR_MAX is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_GETSYSTEMTIME

Retrieves the currently selected time from a date and time picker (DTP) control and places it in a specified SYSTEMTIME structure. You can send this message explicitly or use the DateTime_GetSystemtime macro.

DTM_GETSYSTEMTIME
    wParam = 0;
    lParam = (LPARAM) lpSysTime;

Parameters

lpSysTime
Pointer to a SYSTEMTIME structure. If DTM_GETSYSTEMTIME returns GDT_VALID, this structure will contain the system time. Otherwise, it will not contain valid information. This parameter must be a valid pointer; it cannot be NULL.

Return Values

Returns GDT_VALID if the time information was successfully placed in lpSysTime. Returns GDT_NONE if the control was set to the DTS_SHOWNONE style and the control check box was not selected. Returns GDT_ERROR if an error occurs.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_SETFORMAT

Sets the display of a date and time picker (DTP) control based on a given format string. You can send this message explicitly or use the DateTime_SetFormat macro.

DTM_SETFORMAT
    wParam = 0;
    lParam = (LPARAM) lpszFormat;

Parameters

lpszFormat
Address of a zero-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

It is acceptable to include extra characters within the format string to produce a more rich display. However, any nonformat characters must be enclosed within single quotes. For example, the format string "'Today is: 'hh':'m':'s ddddMMMdd', 'yyy" would produce output like "Today is: 04:22:31 Tuesday Mar 23, 1996".

Note A DTP control tracks locale changes when it is using the default format string. If you set a custom format string, it will not be updated in response to locale changes.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_SETMCCOLOR

Sets the color for a given portion of the month calendar within a date and time picker (DTP) control. You can send this message explicitly or use the DateTime_SetMonthCalColor macro.

DTM_SETMCCOLOR
    wParam = (WPARAM)(INT) iColor;
    lParam = (LPARAM)(COLORREF) clr;

Parameters

iColor
INT value specifying which month calendar color to set. This value can be one of the following:
MCSC_BACKGROUND | Set the background color displayed between months.
MCSC_MONTHBK | Set the background color displayed within the month.
MCSC_TEXT | Set the color used to display text within a month.
MCSC_TITLEBK | Set the background color displayed in the calendar's title.
MCSC_TITLETEXT | Set the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Set the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.
clr
COLORREF value representing the color that will be set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, the message returns -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_SETMCFONT

Sets the font to be used by the date and time picker (DTP) control's child month calendar control. You can send this message explicitly or use the DateTime_SetMonthCalFont macro.

DTM_SETMCFONT
    wParam = (WPARAM)(HFONT) hFont;
    lParam = (LPARAM) MAKELONG(fRedraw, 0);

Parameters

hFont
Handle to the font that will be set.
fRedraw
Specifies whether the control should be redrawn immediately upon setting the font. Setting this parameter to TRUE causes the control to redraw itself.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


DTM_SETRANGE

Sets the minimum and maximum allowable system times for a date and time picker (DTP) control. You can send this message explicitly or use the DateTime_SetRange macro.

DTM_SETRANGE
    wParam = (WPARAM) flags;
    lParam = (LPARAM) lpSysTimeArray;

Parameters

flags
Value specifying which range values are valid. This parameter can be a combination of the following values:
GDTR_MIN | The first element in the SYSTEMTIME structure array is valid and will be used to set the minimum allowable system time.
GDTR_MAX | The second element in the SYSTEMTIME structure array is valid and will be used to set the maximum allowable system time.
lpSysTimeArray
Address of a two-element array of SYSTEMTIME structures. The first element of the SYSTEMTIME array contains the minimum allowable time. The second element of the SYSTEMTIME array contains the maximum allowable time. It is not necessary to fill an array element that is not specified in the flags parameter.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTM_SETSYSTEMTIME

Sets the time in a date and time picker (DTP) control. You can send this message explicitly or use the DateTime_SetSystemtime macro.

DTM_SETSYSTEMTIME
    wParam = (WPARAM) flag;
    lParam = (LPARAM) lpSysTime;

Parameters

flag
Value specifying the action that should be performed. This value must be set to one of the following:
GDT_VALID | Set the DTP control according to the data within the structure that lpSysTime points to.
GDT_NONE | Set the DTP control to "no date" and clear its check box. When this flag is specified, lpSysTime is ignored. This flag applies only to DTP controls that are set to the DTS_SHOWNONE style.
lpSysTime
Address of a SYSTEMTIME structure containing the system time used to set the DTP control.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_GetMonthCal

Retrieves the handle to a date and time picker's (DTP) child month calendar control. You can use this macro or send the DTM_GETMONTHCAL message explicitly.

HWND DateTime_GetMonthCal(
    HWND hwndDP);

Parameters

hwndDP
Handle to a DTP control.

Return Values

Returns the handle to a DTP control's child month calendar control.

Remarks

DTP controls create a child month calendar control when the user clicks the drop-down arrow. When the month calendar is no longer needed, it is destroyed. So your application must not rely on a static handle to the DTP's child month calendar.

See Also

DTN_CLOSEUP, DTN_DROPDOWN

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_GetMonthCalColor

Retrieves the color for a given portion of the month calendar within a date and time picker (DTP) control. You can use this macro or send the DTM_GETMCCOLOR message explicitly.

COLORREF DateTime_GetMonthCalColor(
    HWND hwndDP,
    int iColor);

Parameters

hwndDP
Handle to a DTP control.
iColor
INT value specifying which month calendar color to retrieve. This value can be one of the following:
MCSC_BACKGROUND | Retrieve the background color displayed between months.
MCSC_MONTHBK | Retrieve the background color displayed within the month.
MCSC_TEXT | Retrieve the color used to display text within a month.
MCSC_TITLEBK | Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT | Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. Otherwise, the macro returns -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_GetMonthCalFont

Retrieves the font that the date and time picker (DTP) control's child month calendar control is currently using. You can use this macro or send the DTM_GETMCFONT message explicitly.

HFONT DateTime_GetMonthCalFont(
    HWND hwndDP);

Parameters

hwndDP
Handle to a DTP control.

Return Values

Returns an HFONT value that is the handle to the current font.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


DateTime_GetRange

Retrieves the current minimum and maximum allowable system times for a date and time picker (DTP) control. You can use this macro, or send the DTM_GETRANGE message explicitly.

DWORD DateTime_GetRange(
    HWND hwndDT,
    LPSYSTEMTIME lpSysTimeArray);

Parameters

hwndDT
Address of a DTP control.
lpSysTimeArray
Address of a two-element array of SYSTEMTIME structures.

Return Values

Returns a DWORD value that is a combination of GDTR_MIN or GDTR_MAX. The first element of the SYSTEMTIME array contains the minimum allowable time. The second element of the SYSTEMTIME array contains the maximum allowable time.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_GetSystemtime

Retrieves the currently selected time from a date and time picker (DTP) control and places it in a specified SYSTEMTIME structure. You can use this macro, or send the DTM_GETSYSTEMTIME message explicitly.

DWORD DateTime_GetSystemtime(
    HWND hwndDP,
    LPSYSTEMTIME lpSysTime);

Parameters

hwndDP
Handle to a DTP control.
lpSysTime
Pointer to a SYSTEMTIME structure. If DTM_GETSYSTEMTIME returns GDT_VALID, this structure will contain the system time. Otherwise, it will not contain valid information. This parameter must be a valid pointer; it cannot be NULL.

Return Values

Returns GDT_VALID if the time information was successfully placed in lpSysTime. Returns GDT_NONE if the control was set to the DTS_SHOWNONE style and the control check box was not selected. Returns GDT_ERROR if an error occurs.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_SetFormat

Sets the display of a date and time picker (DTP) control based on a given format string. You can use this macro or send the DTM_SETFORMAT message explicitly.

void DateTime_SetFormat(
    HWND hwndDT,
    LPCTSTR lpszFormat);

Parameters

hwndDT
Handle to a DTP control.
lpszFormat
Address of a zero-terminated format string that defines the desired display. Setting this parameter to NULL will reset the control to the default format string for the current style.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

It is acceptable to include extra characters within the format string to produce a more rich display. However, any nonformat characters must be enclosed within single quotes. For example, the format string "'Today is: 'hh':'m':'s ddddMMMdd', 'yyy" would produce output like "Today is: 04:22:31 Tuesday Mar 23, 1996".

Note A DTP control tracks locale changes when it is using the default format string. If you set a custom format string, it will not be updated in response to locale changes.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_SetMonthCalColor

Sets the color for a given portion of the month calendar within a date and time picker (DTP) control. You can use this macro or send the DTM_SETMCCOLOR message explicitly.

COLORREF DateTime_SetMonthCalColor(
    HWND     hwndDP,
    int      iColor,
    COLORREF clr);

Parameters

hwndDP
Handle to a DTP control.
iColor
INT value specifying which month calendar color to set. This value can be one of the following:
Value | Meaning
MCSC_BACKGROUND | Set the background color displayed between months.
MCSC_MONTHBK | Set the background color displayed within the month.
MCSC_TEXT | Set the color used to display text within a month.
MCSC_TITLEBK | Set the background color displayed in the calendar's title.
MCSC_TITLETEXT | Set the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Set the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.
clr
COLORREF value that represents the color that will be set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, this message returns -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_SetMonthCalFont

Sets the font to be used by the date and time picker (DTP) control's child month calendar control. You can use this macro or explicitly send the DTM_SETMCFONT message.

void DateTime_SetMonthCalFont(
    HWND   hwndDP,
    HFONT  hFont,
    LPARAM MAKELONG(fRedraw,0);

Parameters

hwndDP
Handle to a DTP control.
hFont
Handle to the font that will be set.
fRedraw
Specifies whether the control should be redrawn immediately upon setting the font. Setting this parameter to TRUE causes the control to redraw itself.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


DateTime_SetRange

Sets the minimum and maximum allowable system times for a date and time picker (DTP) control. You can use this macro or send the DTM_SETRANGE message explicitly.

BOOL DateTime_SetRange(
    HWND hwndDT,
    DWORD flags,
    LPSYSTEMTIME lpSysTimeArray);

Parameters

hwndDT
Handle to a DTP control.
flags
Value that specifies which range values are valid. This value can be a combination of the following:
GDTR_MIN | The first element in the SYSTEMTIME structure array is valid and will be used to set the minimum allowable system time.
GDTR_MAX | The second element in the SYSTEMTIME structure array is valid and will be used to set the maximum allowable system time.
lpSysTimeArray
Address of a two-element array of SYSTEMTIME structures. The first element of the SYSTEMTIME array contains the minimum allowable time. The second element of the SYSTEMTIME array contains the maximum allowable time. It is not necessary to fill an array element that is not specified in the flags parameter.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DateTime_SetSystemtime

Sets a date and time picker (DTP) control to a given date and time. You can use this macro or send the DTM_SETSYSTEMTIME message explicitly.

BOOL DateTime_SetSystemtime(
    HWND hwndDT,
    DWORD flag,
    LPSYSTEMTIME lpSysTime);

Parameters

hwndDT
Handle to a DTP control.
flag
Value that specifies the action that should be performed. This should be set to one of the following values:
GDT_VALID | Set the DTP control according to the data within the SYSTEMTIME structure pointed to by lpSysTime.
GDT_NONE | Set the DTP control to "no date" and clear its check box. When this flag is specified, lpSysTime is ignored. This flag applies only to DTP controls that are set to the DTS_SHOWNONE style.
lpSysTime
Address of a SYSTEMTIME structure that contains the system time information by which to set the DTP control.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTN_CLOSEUP

Sent by a date and time picker (DTP) control when the user closes the drop-down month calendar. The month calendar is closed when the user chooses a date from the month calendar or clicks the drop-down arrow while the calendar is open.

DTN_CLOSEUP
    lpNmhdr = (LPMNHDR)lParam;

Parameters

lpNmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

The return value for this notification is not used.

Remarks

DTP controls do not maintain a static child month calendar control. The DTP control destroys the child month calendar control prior to sending this notification. So your application must not rely on a static window handle for the control's child month calendar.

See Also

DTN_DROPDOWN, DTM_GETMONTHCAL

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


DTN_DATETIMECHANGE

Sent by a date and time picker (DTP) control whenever a change occurs. This notification message is sent in the form of a WM_NOTIFY message.

DTN_DATETIMECHANGE
    lpChange = (LPNMDATETIMECHANGE) lParam;

Parameters

lpChange
Address of an NMDATETIMECHANGE structure containing information about the change that took place in the control.

Return Values

The owner of the control must return zero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTN_DROPDOWN

Sent by a date and time picker (DTP) control when the user activates the drop-down month calendar.

DTN_DROPDOWN
    lpNmhdr = (LPNMHDR)lParam;

Parameters

lpNmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

The return value for this notification is not used.

Remarks

One task that your notification handler may need to perform is to customize the dropdown month-calendar control. For instance, if you don't want "Go To Today," you need to set the control's MCS_NOTODAY style. To retrieve a handle to the month-calendar control, send the DTP control a DTM_GETMONTHCAL message. You can then use this handle and SetWindowLong to set the desired month-calendar style.

DTP controls do not maintain a static child month calendar control. The DTP control creates a new month calendar control before sending this notification message. Additionally, the DTP control destroys the child control when it is not active (visible). So your application must not rely on a static window handle for the control's child month calendar.

See Also

DTN_CLOSEUP, DTM_GETMONTHCAL

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTN_FORMAT

Sent by a date and time picker (DTP) control to request text to be displayed in a callback field. This notification message is sent in the form of a WM_NOTIFY message.

DTN_FORMAT
    lpNMFormat = (LPNMDATETIMEFORMAT) lParam;

Parameters

lpNMFormat
Address of an NMDATETIMEFORMAT structure containing information regarding this instance of the notification message. The structure contains the substring that defines the callback field and receives the formatted string that the control will display.

Return Values

The owner of the control must return zero.

Remarks

Handling this message allows the owner of the control to provide a custom string that the control will display. (For additional information about callback fields, see Callback fields.)

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTN_FORMATQUERY

Sent by a date and time picker (DTP) control to retrieve the maximum allowable size of the string that will be displayed in a callback field. This notification message is sent in the form of a WM_NOTIFY message.

DTN_FORMATQUERY
    lpDTFormatQuery = (LPNMDATETIMEFORMATQUERY) lParam;

Parameters

lpDTFormatQuery
Address of an NMDATETIMEFORMATQUERY structure containing information about the callback field. The structure contains a substring that defines a callback field and receives the maximum allowable size of the string that will be displayed in the callback field.

Return Values

The owner of the control must calculate the maximum possible width of the text that will be displayed in the callback field, set the szMax member of the NMDATETIMEFORMATQUERY structure, and return zero.

Remarks

Handling this message prepares the control to adjust for the maximum size of the string that will be displayed in a particular callback field. This enables the control to properly display output at all times, reducing flicker within the control's display. (For additional information about callback fields, see Callback fields.)

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTN_USERSTRING

Sent by a date and time picker (DTP) control when a user finishes editing a string in the control. This notification message is only sent by DTP controls that are set to the DTS_APPCANPARSE style. This message is sent in the form of a WM_NOTIFY message.

DTN_USERSTRING
    lpDTstring = (LPNMDATETIMESTRING) lParam;

Parameters

lpDTstring
Address of an NMDATETIMESTRING structure that contains information about the instance of the notification message.

Return Values

The owner of the control must return zero.

Remarks

Handling this message allows the owner to provide custom responses to strings entered into the control by the user. The owner must be prepared to parse the input string and take action if necessary.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


DTN_WMKEYDOWN

Sent by a date and time picker (DTP) control when the user types in a callback field. This message is sent in the form of a WM_NOTIFY message.

DTN_WMKEYDOWN
    lpDTKeystroke = (LPNMDATETIMEWMKEYDOWN)lParam;

Parameters

lpDTKeystroke
Address of an NMDATETIMEWMKEYDOWN structure containing information about this instance of the notification. The structure includes information about the key that the user typed, the substring that defines the callback field, and the current system date and time.

Return Values

The owner of the control must return zero.

Remarks

Handling this message allows the owner of the control to provide specific responses to keystrokes within the callback fields of the control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_KILLFOCUS (date time)

Notifies a date and time picker control's parent window that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.

NM_KILLFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_SETFOCUS (date time)

Notifies a date and time picker control's parent window that the control has received the input focus. NM_SETFOCUS is sent in the form of a WM_NOTIFY message.

NM_SETFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMDATETIMECHANGE

Contains information about a change that has taken place in a date and time picker (DTP) control. This structure is used with the DTN_DATETIMECHANGE notification message.

typedef struct tagNMDATETIMECHANGE {
    NMHDR       nmhdr;
    DWORD       dwFlags;
    SYSTEMTIME  st;
} NMDATETIMECHANGE, FAR * LPNMDATETIMECHANGE;

Members

nmhdr
NMHDR structure that contains information about the notification message.
dwFlags
Value that indicates if the control was set to "no date" status (for DTS_SHOWNONE only). This flag also specifies whether the contents of the st member are valid and contain current time information. This value can be one of the following:
GDT_NONE | The control is set to "no date" status. The "no date" status applies only to controls that are set to the DTS_SHOWNONE style.
GDT_VALID | The control is not set to the "no date" status. The st member contains the current date and time.
st
SYSTEMTIME structure that contains information about the current system date and time.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMDATETIMEFORMAT

Contains information about a portion of the format string that defines a callback field within a date and time picker (DTP) control. It carries the substring that defines the callback field and contains a buffer to receive the string that will be displayed in the callback field. This structure is used with the DTN_FORMAT notification message.

typedef struct tagNMDATETIMEFORMAT{
    NMHDR nmhdr;
    LPCTSTR pszFormat;
    SYSTEMTIME st;
    LPCTSTR pszDisplay;
    TCHAR szDisplay[64];
} NMDATETIMEFORMAT, FAR * LPNMDATETIMEFORMAT;

Members

nmhdr
NMHDR structure that contains information about the notification message.
pszFormat
Address of the substring that defines a DTP control callback field. The substring comprises one or more "X" characters followed by a NULL character. (For more information about callback fields, see Callback fields.)
st
SYSTEMTIME structure that contains the date and time to be formatted.
pszDisplay
Address of a null-terminated string that contains the display text of the control. By default, this is the address of the szDisplay member of this structure.

It is acceptable to have pszDisplay point to an existing string. In this case, you don't need to assign a value to szDisplay. However, the string that pszDisplay points to must remain valid until another DTN_FORMAT notification is sent, or until the control is destroyed.

szDisplay
64-character buffer that is to receive the zero-terminated string that the DTP control will display. It is not necessary to fill the entire buffer.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMDATETIMEFORMATQUERY

Contains information about a date and time picker (DTP) control callback field. It contains a substring (taken from the control's format string) that defines a callback field. The structure receives the maximum allowable size of the text that will be displayed in the callback field. This structure is used with the DTN_FORMATQUERY notification message.

typedef struct tagNMDATETIMEFORMATQUERY{
    NMHDR nmhdr;
    LPCTSTR pszFormat;
    SIZE szMax;
} NMDATETIMEFORMATQUERY, FAR * LPNMDATETIMEFORMATQUERY;

Members

nmhdr
NMHDR structure that contains information about this notification message.
pszFormat
Address of a substring that defines a DTP control callback field. The substring is one or more "X" characters followed by a NULL. (For additional information about callback fields, see Callback fields.)
szMax
SIZE structure that must be filled with the maximum size of the text that will be displayed in the callback field.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMDATETIMESTRING

Contains information specific to an edit operation that has taken place in a date and time picker (DTP) control. This message is used with the DTN_USERSTRING notification message.

typedef struct tagNMDATETIMESTRING{
    NMHDR      nmhdr;
    LPCTSTR    pszUserString;
    SYSTEMTIME st;
    DWORD      dwFlags;
} NMDATETIMESTRING, FAR * LPNMDATETIMESTRING;

Members

nmhdr
NMHDR structure that contains information about this notification message.
pszUserString
Address of the zero-terminated string that the user entered.
st
SYSTEMTIME structure that must be filled in by the owner when handling the DTN_USERSTRING notification message.
dwFlags
Return field. Set this member to GDT_VALID to indicate that the st member is valid or to GDT_NONE to set the control to "no date" status (DTS_SHOWNONE style only).

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMDATETIMEWMKEYDOWN

Carries information used to describe and handle a DTN_WMKEYDOWN notification message.

typedef struct tagNMDATETIMEWMKEYDOWN{
    NMHDR      nmhdr;
    int        nVirtKey;
    LPCTSTR    pszFormat;
    SYSTEMTIME st;
} NMDATETIMEWMKEYDOWN, FAR * LPNMDATETIMEWMKEYDOWN;

Members

nmhdr
NMHDR structure that contains information about the notification message.
nVirtKey
Virtual key code that represents the key that the user pressed.
pszFormat
Zero-terminated substring, taken from the format string, that defines the callback field. The substring is one or more "X" characters, followed by a NULL.
st
SYSTEMTIME structure containing the current date and time from the DTP control. The owner of the control must modify the time information based on the user's keystroke.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Drag List Boxes

A drag list box is a special type of list box that enables the user to drag items from one position to another. An application can use a drag list box to display strings in a particular sequence and enable the user to change the sequence by dragging the items into position.

  • Using Drag List Boxes
  • Drag List Box Reference

    • Using Drag List Boxes

    Drag list boxes have the same window styles and process the same messages as standard list boxes. To create a drag list box, first create a standard list box and then call the MakeDragList function. To convert a list box in a dialog box to a drag list box, you can call MakeDragList when the WM_INITDIALOG message is processed.

    Drag List Box Messages

    A drag list box notifies the parent window of drag events by sending it a drag list message. The parent window must process the drag list message.

    The drag list box registers this message when the MakeDragList function is called. To retrieve the message identifier (numeric value) of the drag list message, call the RegisterWindowMessage function and specify the DRAGLISTMSGSTRING value.

    The wParam parameter of the drag list message is the control identifier for the drag list box. The lParam parameter is the address of a DRAGLISTINFO structure, which contains the notification code for the drag event and other information. The return value of the message depends on the notification.

    Drag List Box Notification Messages

    The drag list notification message, which is identified by the uNotification member of the DRAGLISTINFO structure included with the drag list message, can be DL_BEGINDRAG, DL_DRAGGING, DL_CANCELDRAG, or DL_DROPPED.

    The DL_BEGINDRAG notification message is sent when the cursor is on a list item and the user clicks the left mouse button. The parent window can return TRUE to begin the drag operation or FALSE to disallow dragging. In this way, the parent window can enable dragging for some list items and disable it for others. You can determine which list item is at the specified location by using the LBItemFromPt function.

    If dragging is in effect, the DL_DRAGGING notification message is sent whenever the mouse is moved, or at regular intervals if the mouse is not being moved. The parent window should first determine the list item under the cursor by using LBItemFromPt and then draw the insert icon by using the DrawInsert function. By specifying TRUE for the bAutoScroll parameter of LBItemFromPt, you can cause the list box to scroll by one line if the cursor is above or below its client area. The value you return for this notification specifies the type of mouse cursor that the drag list box should set.

    The DL_CANCELDRAG notification message is sent if the user cancels a drag operation by clicking the right mouse button or pressing the ESC key. The DL_DROPPED notification message is sent if the user completes a drag operation by releasing the left mouse button, even if the cursor is not over a list item. The drag list box releases the mouse capture before sending either notification. The return value of these two notifications is ignored.


DrawInsert

Draws the insert icon in the parent window of the specified drag list box.

void DrawInsert(
    HWND handParent,
    HWND hLB,
    int nItem
   );

Parameters

handParent
Handle to the parent window of the drag list box.
hLB
Handle to the drag list box.
nItem
Identifier of the icon item to be drawn.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


LBItemFromPt

Retrieves the index of the item at the specified point in a list box.

int LBItemFromPt(
    HWND hLB,
    POINT pt,
    BOOL bAutoScroll
   );

Parameters

hLB
Handle to the list box to check.
pt
POINT structure that contains the screen coordinates to check.
bAutoScroll
Scroll flag. If this parameter is TRUE and the point is directly above or below the list box, the function scrolls the list box by one line and returns -1. Otherwise, the function does not scroll the list box.

Return Values

Returns the item identifier if the point is over a list item, or -1 otherwise.

Remarks

The LBItemFromPt function only scrolls the list box if a minimum amount of time has passed since it last did so. Timing prevents the list box from scrolling too quickly if the function is called repeatedly in rapid succession—for example, when DL_DRAGGING notification messages or WM_MOUSEMOVE messages are processed.

If the specified point is outside the client area of the list box and bAutoScroll is TRUE, the function scrolls the list box instead of returning an item identifier.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


MakeDragList

Changes the specified single-selection list box to a drag list box.

BOOL MakeDragList(
    HWND hLB
   );

Parameters

hLB
Handle to the single-selection list box.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


DL_BEGINDRAG

Notifies the drag list box's parent window that the user has clicked the left mouse button on an item. A drag list box sends DL_BEGINDRAG in the form of a drag list message.

DL_BEGINDRAG
    idCtl = (WPARAM)(int) wParam;
    pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;

Parameters

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_BEGINDRAG notification code, the handle to the drag list box, and the cursor position.

Return Values

Return TRUE to begin the drag operation, or FALSE to prevent the drag operation.

Remarks

When processing this notification message, a window procedure typically determines the list item at the specified cursor position by using the LBItemFromPt function. It then returns TRUE or FALSE, depending on whether the item should be dragged. Before returning TRUE, the window procedure should save the index of the list item so the application knows which item to move or copy when the drag operation is completed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


DL_CANCELDRAG

Signals that the user has canceled a drag operation by clicking the right mouse button or pressing the ESC key. A drag list box sends DL_CANCELDRAG to its parent window in the form of a drag list message.

DL_CANCELDRAG
    idCtl = (WPARAM)(int) wParam;
    pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;

Parameters

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_CANCELDRAG notification code, the handle to the drag list box, and the cursor position.

Return Values

No return value.

Remarks

By processing the DL_CANCELDRAG notification message, an application can reset its internal state to indicate that dragging is not in effect.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


DL_DRAGGING

Signals that the user has moved the mouse while dragging an item. DL_DRAGGING is also sent periodically during dragging even if the mouse is not moved. A drag list box sends this notification to its parent window in the form of a drag list message.

DL_DRAGGING
    idCtl = (WPARAM)(int) wParam;
    pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;

Parameters

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_DRAGGING notification code, the handle to the drag list box, and the cursor position.

Return Values

The return value determines the type of mouse cursor that the drag list should set; it can be the DL_STOPCURSOR, DL_COPYCURSOR, or DL_MOVECURSOR value. If any other value is returned, the cursor does not change.

Remarks

A window procedure typically processes the DL_DRAGGING notification message by determining the item under the cursor and then drawing an insert icon. To retrieve the item under the cursor, use the LBItemFromPt function, specifying TRUE for the bAutoScroll parameter. This option causes the drag list box to scroll periodically if the cursor is above or below its client area. To draw the insert icon, use the DrawInsert function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


DL_DROPPED

Signals that the user has completed a drag operation by releasing the left mouse button. A drag list box sends DL_DROPPED to its parent window in the form of a drag list message.

DL_BEGINDRAG
    idCtl = (WPARAM)(int) wParam;
    pDragInfo = (LPARAM)(LPDRAGLISTINFO) lParam;

Parameters

idCtl
Control identifier of the drag list box.
pDragInfo
Address of a DRAGLISTINFO structure that contains the DL_DROPPED notification code, the handle to the drag list box, and the cursor position.

Return Values

No return value.

Remarks

This notification is normally processed by inserting the item being dragged into the list in front of the item under the cursor. To retrieve the index of the item at the cursor position, use the LBItemFromPt function. Note that the DL_DROPPED notification message is sent even if the cursor is not on a list item. In that case, LBItemFromPt returns -1.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


DRAGLISTINFO

Contains information about a drag event. The pointer to DRAGLISTINFO is passed as the lParam parameter of the drag list message.

Typedef struct {
    UINT uNotification;
    HWND hWnd;
    POINT ptCursor;
} DRAGLISTINFO, FAR *LPDRAGLISTINFO;

Members

uNotification
Notification code that specifies the type of drag event. This member can be one of the following values:
DL_BEGINDRAG | The user has clicked the left mouse button on a list item.
DL_CANCELDRAG | The user has canceled the drag operation by clicking the right mouse button or pressing the ESC key.
DL_DRAGGING | The user has moved the mouse while dragging an item.
DL_DROPPED | The user has released the left mouse button, completing a drag operation.
hWnd
Handle to the drag list box.
ptCursor
POINT structure that contains the current x- and y-coordinates of the mouse cursor.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Flat Scroll Bars

Microsoft® Internet Explorer Version 4.0 introduces a new visual technology called flat scroll bars. Functionally, flat scroll bars behave just like standard scroll bars. The difference is that you can customize their appearance to a greater extent than standard scroll bars.

The following illustration shows a window that contains flat scroll bars.

Window that contains flat scroll bars.

Note Flat scroll bar APIs are implemented in version 4.71 and later of Comctl32.dll.

  • Using Flat Scroll Bars
  • Flat Scroll Bars Reference

Using Flat Scroll Bars

This section describes how to implement flat scroll bars in your application.

Before You Begin

To use the flat scroll bar APIs, you must include Commctrl.h in your source files and link with Comctl32.lib.

Adding Flat Scroll Bars to a Window

To add flat scroll bars to a window, call InitializeFlatSB, passing the handle to the window. Instead of using the standard scroll bar functions to manipulate your scroll bars, you must use the equivalent FlatSB_XXX function. There are flat scroll bar functions for setting and retrieving the scroll information, range, and position. If flat scroll bars haven't been initialized for your window, the flat scroll bar API will defer to the corresponding standard functions, if any are used. This allows you to turn flat scroll bars on and off without having to write conditional code.

Because an application may have set custom metrics for its flat scroll bars, they are not automatically updated when system metrics change. When the system scroll bar metrics change, a WM_SETTINGCHANGE message is broadcast, with its wParam set to SPI_SETNONCLIENTMETRICS. To update flat scroll bars to the new system metrics, applications must handle this message and change the flat scroll bar's metric-dependent properties explicitly.

To update your scroll bar properties, use FlatSB_SetScrollProp. The following code fragment changes a flat scroll bar's metric dependent properties to the current system values.

void FlatSB_UpdateMetrics(HWND hWnd)
{
FlatSB_SetScrollProp(hWnd, WSB_PROP_CXVSCROLL, GetSystemMetrics(SM_CXVSCROLL), FALSE);
FlatSB_SetScrollProp(hWnd, WSB_PROP_CXHSCROLL, GetSystemMetrics(SM_CXHSCROLL), FALSE);
FlatSB_SetScrollProp(hWnd, WSB_PROP_CYVSCROLL, GetSystemMetrics(SM_CYVSCROLL), FALSE);
FlatSB_SetScrollProp(hWnd, WSB_PROP_CYHSCROLL, GetSystemMetrics(SM_CYHSCROLL), FALSE);
FlatSB_SetScrollProp(hWnd, WSB_PROP_CXHTHUMB, GetSystemMetrics(SM_CXHTHUMB), FALSE);
FlatSB_SetScrollProp(hWnd, WSB_PROP_CYVTHUMB, GetSystemMetrics(SM_CYVTHUMB), TRUE);
}

Enhancing Flat Scroll Bars

FlatSB_SetScrollProp allows you to modify the flat scroll bars to customize the look of your window. For vertical scroll bars, you can change the width of the bar and the height of the direction arrows. For horizontal scroll bars, you can change the height of the bar and the width of the direction arrows. You can also change the background color of both the horizontal and vertical scroll bars.

FlatSB_SetScrollProp also allows you to customize how the flat scroll bars are displayed. By changing the WSB_PROP_VSTYLE and WSB_PROP_HSTYLE properties, you can set the type of scroll bar that you wish to use. Three styles are available.

FSB_ENCARTA_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in 3-D.
FSB_FLAT_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in inverted colors.
FSB_REGULAR_MODE | A normal, nonflat scroll bar is displayed. No special visual effects will be applied.

Removing Flat Scroll Bars

If you wish to remove flat scroll bars from your window, call the UninitializeFlatSB API, passing the handle to the window. This API only removes flat scroll bars from your window at run time. You do not need to call this API when your window is destroyed.


InitializeFlatSB

Initializes flat scroll bars for a particular window.

BOOL InitializeFlatSB(
    HWND hwnd
);

Parameters

hwnd
Handle to the window that will receive flat scroll bars.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

This API must be called before any other flat scroll bar APIs are called. The window will receive flat scroll bars by default. The scroll bar style can be changed with the FlatSB_SetScrollProp API.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_EnableScrollBar

Enables or disables one or both flat scroll bar direction buttons. If flat scroll bars are not initialized for the window, this function calls the standard EnableScrollBar API.

BOOL FlatSB_EnableScrollBar(
    HWND hwnd,
    int wSBflags,
    UINT wArrows
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
wSBflags
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_BOTH | Enables or disables the direction buttons on the horizontal and vertical scroll bars.
SB_HORZ | Enables or disables the direction buttons on the horizontal scroll bar.
SB_VERT | Enables or disables the direction buttons on the vertical scroll bar.
wArrows
Parameter that specifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled. It can be one of the following values:
ESB_DISABLE_BOTH | Disables both direction buttons on the specified scroll bar.
ESB_DISABLE_DOWN | Disables the down direction button on the vertical scroll bar.
ESB_DISABLE_LEFT | Disables the left direction button on the horizontal scroll bar.
ESB_DISABLE_LTUP | Disables the left direction button on the horizontal scroll bar or the up direction button on the vertical scroll bar.
ESB_DISABLE_RIGHT | Disables the right direction button on the horizontal scroll bar.
ESB_DISABLE_RTDN | Disables the right direction button on the horizontal scroll bar or the down direction button on the vertical scroll bar.
ESB_DISABLE_UP | Disables the up direction button on the vertical scroll bar.
ESB_ENABLE_BOTH | Enables both direction buttons on the specified scroll bar.

Return Values

Returns nonzero if the scroll bar changes, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_GetScrollInfo

Retrieves the information for a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard GetScrollInfo API.

BOOL FlatSB_GetScrollInfo(
    HWND hwnd,
    int fnBar,
    LPSCROLLINFO lpsi
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
fnBar
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ | Retrieves the information for the horizontal scroll bar.
SB_VERT | Retrieves the information for the vertical scroll bar.
lpsi
Address of a SCROLLINFO structure that will receive the information for the specified scroll bar. The cbSize and fMask members of the structure must be filled out prior to calling FlatSB_GetScrollInfo. The fMask member specifies which properties should be retrieved and can be any combination of the following values:
SIF_PAGE | Retrieves the page information for the flat scroll bar. This will be placed in the nPage member of the SCROLLINFO structure.
SIF_POS | Retrieves the position information for the flat scroll bar. This will be placed in the nPos member of the SCROLLINFO structure.
SIF_RANGE | Retrieves the range information for the flat scroll bar. This will be placed in the nMin and nMax members of the SCROLLINFO structure.
SIF_ALL | A combination of SIF_PAGE, SIF_POS, and SIF_RANGE.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_GetScrollPos

Retrieves the thumb position in a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard GetScrollPos API.

int FlatSB_GetScrollPos(
    HWND hwnd,
    int code
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ | Retrieves the thumb position of the horizontal scroll bar.
SB_VERT | Retrieves the thumb position of the vertical scroll bar.

Return Values

Returns the current thumb position of the specified flat scroll bar.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_GetScrollProp

Retrieves the properties for a flat scroll bar. This function can also be used to determine if InitializeFlatSB has been called for this window.

BOOL FlatSB_GetScrollProp(
    HWND hwnd,
    UINT index,
    LPINT pValue
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
index
Parameter that determines what pValue represents and which property is being retrieved. It can be one of the following values:
WSB_PROP_CXHSCROLL | pValue is an address of an INT value that receives the width, in pixels, of the direction buttons in a horizontal scroll bar.
WSB_PROP_CXHTHUMB | pValue is an address of an INT value that receives the width, in pixels, of the thumb in a horizontal scroll bar.
WSB_PROP_CXVSCROLL | pValue is an address of an INT value that receives the width, in pixels, of a vertical scroll bar.
WSB_PROP_CYHSCROLL | pValue is an address of an INT value that receives the height, in pixels, of a horizontal scroll bar.
WSB_PROP_CYVSCROLL | pValue is an address of an INT value that receives the height, in pixels, of the direction buttons in a vertical scroll bar.
WSB_PROP_CYVTHUMB | pValue is an address of an INT value that receives the height, in pixels, of the thumb in a vertical scroll bar.
WSB_PROP_HBKGCOLOR | pValue is an address of a COLORREF value that receives the background color in a horizontal scroll bar.
WSB_PROP_HSTYLE pValue is an address of an INT value that receives one of the following visual effects for the horizontal scroll bar.
FSB_ENCARTA_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in 3-D.
FSB_FLAT_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in inverted colors.
FSB_REGULAR_MODE | A normal, nonflat scroll bar is displayed. No special visual effects are applied.
WSB_PROP_PALETTE | pValue is an address of an HPALETTE value that receives the palette that a scroll bar uses when drawing.
WSB_PROP_VBKGCOLOR | pValue is an address of a COLORREF value that receives the background color in a vertical scroll bar.
WSB_PROP_VSTYLE pValue is an address of an INT value that receives one of the following visual effects for the vertical scroll bar.
FSB_ENCARTA_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in 3-D.
FSB_FLAT_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar is displayed in inverted colors.
FSB_REGULAR_MODE | A normal, nonflat scroll bar is displayed. No special visual effects are applied.
WSB_PROP_WINSTYLE | pValue is an address of an INT value that receives the WS_HSCROLL and WS_VSCROLL style bits contained by the current window.
pValue
Address that receives the requested data. This parameter depends on the flag passed in index.

Return Values

Returns nonzero if successful, or zero otherwise. If index is WSB_PROP_HSTYLE, the return is nonzero if InitializeFlatSB has been called for this window, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_GetScrollRange

Retrieves the scroll range for a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard GetScrollRange API.

BOOL FlatSB_GetScrollRange(
    HWND hwnd,
    int code,
    LPINT lpMinPos,
    LPINT lpMaxPos
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ | Retrieves the scroll range of the horizontal scroll bar.
SB_VERT | Retrieves the scroll range of the vertical scroll bar.
lpMinPos
Address of an INT value that receives the minimum scroll range value.
lpMaxPos
Address of an INT value that receives the maximum scroll range value.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_SetScrollInfo

Sets the information for a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard SetScrollInfo API.

int FlatSB_SetScrollInfo(
    HWND hwnd,
    int fnBar,
    LPSCROLLINFO lpsi,
    BOOL fRedraw
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
fnBar
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ | Sets the information for the horizontal scroll bar.
SB_VERT | Sets the information for the vertical scroll bar.
lpsi
Address of a SCROLLINFO structure that contains the new information for the specified scroll bar. The cbSize and fMask members of the structure must be filled in prior to calling FlatSB_SetScrollInfo. The fMask member specifies which members of the structure contain valid information and can be any combination of the following values:
SIF_DISABLENOSCROLL | Disables the scroll bar if the new information would cause the scroll bar to be removed.
SIF_PAGE | Sets the page information for the flat scroll bar. The nPage member of the SCROLLINFO structure must contain the new page value.
SIF_POS | Sets the position information for the flat scroll bar. The nPos member of the SCROLLINFO structure must contain the new position value.
SIF_RANGE | Sets the range information for the flat scroll bar. The nMin and nMax members of the SCROLLINFO structure must contain the new range values.
SIF_ALL | A combination of SIF_PAGE, SIF_POS, and SIF_RANGE.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Return Values

Returns the current scroll position. If the call to FlatSB_SetScrollInfo changes the scroll position, then the previous position is returned.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_SetScrollPos

Sets the current position of the thumb in a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard SetScrollPos API.

int FlatSB_SetScrollPos(
    HWND hwnd,
    int code,
    int nPos,
    BOOL fRedraw
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ | Sets the thumb position of the horizontal scroll bar.
SB_VERT | Sets the thumb position of the vertical scroll bar.
nPos
Parameter that specifies the new thumb position.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Return Values

Returns the previous position of the thumb in the specified flat scroll bar.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_SetScrollProp

Sets the properties for a flat scroll bar.

BOOL FlatSB_SetScrollProp(
    HWND    hwnd,
    UINT    index,
    INT_PTR newValue,
    BOOL    fRedraw
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
index
Parameter that determines what newValue represents and which property is being set. This parameter can be one of the following values:
WSB_PROP_CXHSCROLL | newValue is an INT_PTR value that represents the width, in pixels, of the direction buttons in a horizontal scroll bar.
WSB_PROP_CXHTHUMB | newValue is an INT_PTR value that represents the width, in pixels, of the thumb in a horizontal scroll bar.
WSB_PROP_CXVSCROLL | newValue is an INT_PTR value that represents the width, in pixels, of the vertical scroll bar.
WSB_PROP_CYHSCROLL | newValue is an INT_PTR value that represents the height, in pixels, of the horizontal scroll bar.
WSB_PROP_CYVSCROLL | newValue is an INT_PTR value that represents the height, in pixels, of the direction buttons in a vertical scroll bar.
WSB_PROP_CYVTHUMB | newValue is an INT_PTR value that represents the height, in pixels, of the thumb in a vertical scroll bar.
WSB_PROP_HBKGCOLOR | newValue is a COLORREF value that represents the background color in a horizontal scroll bar.
WSB_PROP_HSTYLE newValue is one of the following values that changes the visual effects for the horizontal scroll bar.
FSB_ENCARTA_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in 3-D.
FSB_FLAT_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in inverted colors.
FSB_REGULAR_MODE | A normal, nonflat scroll bar is displayed. No special visual effects will be applied.
WSB_PROP_PALETTE | newValue is an HPALETTE value that represents the new palette that the scroll bar should use when drawing.
WSB_PROP_VBKGCOLOR | newValue is a COLORREF value that represents the background color in a vertical scroll bar.
WSB_PROP_VSTYLE newValue is one of the following values that changes the visual effects for the vertical scroll bar:
FSB_ENCARTA_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in 3-D.
FSB_FLAT_MODE | A standard flat scroll bar is displayed. When the mouse moves over a direction button or the thumb, that portion of the scroll bar will be displayed in inverted colors.
FSB_REGULAR_MODE | A normal, nonflat scroll bar is displayed. No special visual effects will be applied.
newValue
New value to set. This parameter depends on the flag passed in index.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_SetScrollRange

Sets the scroll range of a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard SetScrollRange API.

int FlatSB_SetScrollRange(
    HWND hwnd,
    int code,
    int nMinPos,
    int nMaxPos,
    BOOL fRedraw
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_HORZ | Sets the scroll range of the horizontal scroll bar.
SB_VERT | Sets the scroll range of the vertical scroll bar.
nMinPos
Parameter that specifies the new minimum scroll range value.
nMaxPos
Parameter that specifies the new maximum scroll range value.
fRedraw
Parameter that specifies whether the scroll bar should be redrawn immediately to reflect the change. If this parameter is TRUE, the scroll bar is redrawn; if it is FALSE, the scroll bar is not redrawn.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


FlatSB_ShowScrollBar

Shows or hides a flat scroll bar. If flat scroll bars are not initialized for the window, this function calls the standard ShowScrollBar API.

BOOL FlatSB_ShowScrollBar(
    HWND hwnd,
    int code,
    BOOL fShow
);

Parameters

hwnd
Handle to the window that contains the flat scroll bar. This window handle must have been passed previously in a call to InitializeFlatSB.
code
Parameter that specifies the scroll bar type. It can be one of the following values:
SB_BOTH | Shows or hides the horizontal and vertical scroll bars.
SB_HORZ | Shows or hides the horizontal scroll bar.
SB_VERT | Shows or hides the vertical scroll bar.
fShow
Parameter that specifies whether the scroll bar should be shown or hidden. If this parameter is nonzero, the scroll bar will be shown; if it is zero, the scroll bar will be hidden.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


UninitializeFlatSB

Uninitializes flat scroll bars for a particular window. The specified window will revert to having standard scroll bars.

HRESULT UninitializeFlatSB(
    HWND hwnd
);

Parameters

hwnd
Handle to the window with the flat scroll bars that will be uninitialized.

Return Values

Returns one of the following values:
E_FAIL | One of the window's scroll bars is currently in use. The operation cannot be completed at this time.
S_FALSE | The window doesn't have flat scroll bars initialized.
S_OK | The operation was successful.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


Header Controls

A header control is a window that is usually positioned above columns of text or numbers. It contains a title for each column, and it can be divided into parts. The user can drag the dividers that separate the parts to set the width of each column. The following illustration shows a header control that has labeled columns that give detailed information about files in a directory.

Header control with labeled columns.

  • Using Header Controls
  • Header Control Updates in Internet Explorer
  • Header Control Reference

Using Header Controls

You can create a header control by using the CreateWindowEx function, specifying the WC_HEADER window class and the appropriate header styles. This window class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, use the InitCommonControlsEx function. After you create a header control, you can divide it into parts, set the text in each part, and control the appearance of the window by using header window messages.

Header Control Size and Position

Typically, you must set the size and position of a header control to fit within the boundaries of a particular rectangle, such as the client area of a window. By using the HDM_LAYOUT message, you can retrieve the appropriate size and position values from the header control.

When sending HDM_LAYOUT, you specify the address of an HDLAYOUT structure that contains the coordinates of the rectangle that the header control is to occupy and provides a pointer to a WINDOWPOS structure. The control fills the WINDOWPOS structure with size and position values appropriate for positioning the control along the top of the specified rectangle. The height value is the sum of the heights of the control's horizontal borders and the average height of characters in the font currently selected into the control's device context.

If you want to use HDM_LAYOUT to set the initial size and position of a header control, set the initial visibility state of the control so that it is hidden. After sending HDM_LAYOUT to retrieve the size and position values, you can use the SetWindowPos function to set the new size, position, and visibility state.

Items

A header control typically has several header items that define the columns of the control. You add an item to a header control by sending the HDM_INSERTITEM message to the control. The message includes the address of an HDITEM structure. This structure defines the properties of the header item, which can include a string, a bitmapped image, an initial size, and an application-defined 32-bit value.

The fmt member of an item's HDITEM structure can include either the HDF_STRING or HDF_BITMAP flag to indicate whether the control displays the item's string or bitmap. If you want to display both a string and a bitmap, create an owner-drawn item by setting the fmt member to include the HDF_OWNERDRAW flag. The HDITEM structure also specifies formatting flags that tell the control whether to center, left-align, or right-align the string or bitmap in the item's rectangle.

HDM_INSERTITEM returns the index of the newly added item. You can use the index in other messages to set properties or retrieve information about the item. You can delete an item by using the HDM_DELETEITEM message, specifying the index of the item to delete.

You can use the HDM_SETITEM message to set the properties of an existing header item and the HDM_GETITEM message to retrieve the current properties of an item. To retrieve a count of the items in a header control, use the HDM_GETITEMCOUNT message.

Owner-Drawn Header Controls

You can define individual items of a header control to be owner-drawn items. Using this technique gives you more control than you would otherwise have over the appearance of a header item.

You can use the HDM_INSERTITEM message to insert a new owner-drawn item into a header control or the HDM_SETITEM message to change an existing item to an owner-drawn item. Both messages include the address of an HDITEM structure, which should have the fmt member set to the HDF_OWNERDRAW value.

When a header control must draw an owner-drawn item, it sends the WM_DRAWITEM message to the parent window. The wParam parameter of the message is the child window identifier of the header control, and the lParam parameter is an address of a DRAWITEMSTRUCT structure. The parent window uses the information in the structure to draw the item. For an owner-drawn item in a header control, the DRAWITEMSTRUCT structure contains the following information.
Member | Description
CtlType | ODT_HEADER owner-drawn control type.
CtlID | Child-window identifier of the header control.
itemID | Index of the item to be drawn.
itemAction | ODA_DRAWENTIRE drawing-action flag.
itemState | ODS_SELECTED drawing-action flag if the cursor is on the item and the mouse button is down. Otherwise, this member is zero.
hwndItem | Handle to the header control.
hDC | Handle to the device context of the header control.
rcItem | Coordinates of the header item to be drawn. The coordinates are relative to the upper-left corner of the header control.
itemData | Application-defined 32-bit value associated with the item.

Header Control Notification Messages

A header control sends notification messages to its parent window when the user clicks or double-clicks an item, when the user drags an item divider, and when the attributes of an item change. The parent window receives the notifications in the form of WM_NOTIFY messages. The following notifications are used with header controls.
Notification | Description
HDN_BEGINTRACK | Signals the start of divider dragging.
HDN_DIVIDERDBLCLICK | Indicates that the user double-clicked a divider.
HDN_ENDTRACK | Signals the end of divider dragging.
HDN_ITEMCHANGED | Indicates a change in the attributes of an item.
HDN_ITEMCHANGING | Indicates that the attributes of an item are about to change.
HDN_ITEMCLICK | Indicates that the user clicked an item.
HDN_ITEMDBLCLICK | Indicates that the user double-clicked an item.
HDN_TRACK | Indicates that the user dragged a divider.

Default Header Control Message Processing

This section describes the window messages handled by the window procedure for the WC_HEADER window class.
Message | Processing performed
WM_CREATE | Initializes the header control.
WM_DESTROY | Uninitializes the header control.
WM_ERASEBKGND | Fills the background of the header control using the control's current background color.
WM_GETDLGCODE | Returns a combination of the DLGC_WANTTAB and DLGC_WANTARROWS values.
WM_GETFONT | Returns the handle to the current font, which is used by the header control to draw its text.
WM_LBUTTONDBLCLK | Captures mouse input. If the mouse cursor is on a divider, the control sends the HDN_BEGINTRACK notification message and begins dragging the divider. If the cursor is on an item, the item is displayed in the pressed state.
WM_LBUTTONDOWN | Same as the WM_LBUTTONDBLCLK message.
WM_LBUTTONUP | Releases the mouse capture. If the control was tracking mouse movement, it sends the HDN_ENDTRACK notification message and redraws the header control. Otherwise, the control sends the HDN_ITEMCLICK notification message and redraws the header item that was clicked.
WM_MOUSEMOVE | If a divider is being dragged, the control sends the HDN_TRACK notification message and displays the item at the new position. If the left mouse button is down and the cursor is on an item, the item is displayed in the pressed state.
WM_NCCREATE | Allocates and initializes an internal data structure.
WM_NCDESTROY | Frees the resources allocated by the header control after the header control is uninitialized.
WM_PAINT | Paints the invalid region of the header control. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETCURSOR | Sets the cursor shape, depending on whether the cursor is on a divider or in a header item.
WM_SETFONT | Selects a new font handle into the device context for the header control.

Creating a Header Control

The following example demonstrates how to create a header control and position it along the top of the parent window's client area. The control is initially hidden. The HDM_LAYOUT message is used to calculate the size and position of the control within the parent window. The control is then repositioned and made visible.

// DoCreateHeader - creates a header control that is positioned along
//     the top of the parent window's client area.
// Returns the handle to the header control.
// hwndParent - handle to the parent window.
//
// Global variable
//    g_hinst - handle to the application instance
extern HINSTANCE g_hinst;

HWND DoCreateHeader(HWND hwndParent)
{
        HWND hwndHeader;
        RECT rcParent;
        HDLAYOUT hdl;
        WINDOWPOS wp;

        // Ensure that the common control DLL is loaded, and then create
        // the header control.
        InitCommonControlsEx();

        if ((hwndHeader = CreateWindowEx(0, WC_HEADER, (LPCTSTR) NULL,
                WS_CHILD | WS_BORDER | HDS_BUTTONS | HDS_HORZ,
                0, 0, 0, 0, hwndParent, (HMENU) ID_HEADER, g_hinst,
                (LPVOID) NULL)) == NULL)
            return (HWND) NULL;

        // Retrieve the bounding rectangle of the parent window's
        // client area, and then request size and position values
        // from the header control.
        GetClientRect(hwndParent, &rcParent);

        hdl.prc = &rcParent;
        hdl.pwpos = &wp;
        if (!SendMessage(hwndHeader, HDM_LAYOUT, 0, (LPARAM) &hdl))
            return (HWND) NULL;

        // Set the size, position, and visibility of the header control.
        SetWindowPos(hwndHeader, wp.hwndInsertAfter, wp.x, wp.y,
            wp.cx, wp.cy, wp.flags | SWP_SHOWWINDOW);

        return hwndHeader;
}

Adding an Item to a Header Control

The following example demonstrates how to use the HDM_INSERTITEM message and the HDITEM structure to add an item to a header control. The new item consists of a string that is left-justified within the item rectangle.

// DoInsertItem - inserts an item into a header control.
// Returns the index of the new item.
// hwndHeader - handle to the header control.
// iInsertAfter - index of the previous item.
// nWidth - width of the new item.
// lpsz - address of the item string.
int DoInsertItem(HWND hwndHeader, int iInsertAfter,
    int nWidth, LPSTR lpsz)
{
    HDITEM hdi;
    int index;

    hdi.mask = HDI_TEXT | HDI_FORMAT | HDI_WIDTH;
    hdi.pszText = lpsz;
    hdi.cxy = nWidth;
    hdi.cchTextMax = lstrlen(hdi.pszText);
    hdi.fmt = HDF_LEFT | HDF_STRING;

    index = SendMessage(hwndHeader, HDM_INSERTITEM,
        (WPARAM) iInsertAfter, (LPARAM) &hdi);

    return index;

}

Header Control Updates in Internet Explorer

Header controls in Microsoft® Internet Explorer support the following new features.

Image Lists
New messages for this feature include HDM_GETIMAGELIST and HDM_SETIMAGELIST. The header control structure HDITEM has been updated to support image lists. Image lists can be used with current bitmap support.
Callback Items
Currently, callback support includes header item text and images. Setting a header item's text to the LPSTR_TEXTCALLBACK value or its image to the I_IMAGECALLBACK value will cause the control to send an HDN_GETDISPINFO message to request callback information as needed. HDN_GETDISPINFO is supported by the new NMHDDISPINFO structure.
Custom Item Ordering
The new messages that support this feature are: HDM_GETORDERARRAY, HDM_SETORDERARRAY, and HDM_ORDERTOINDEX.
Drag-and-Drop Manipulation
Drag-and-drop reordering of header items is now available. Implement drag-and-drop support by including the HDS_DRAGDROP style when creating the control. By default, the header control automatically handles drag-and-drop overhead and graphic effects. However, the owner of the control can manually support drag-and-drop manipulation by handling the HDN_BEGINDRAG and HDN_ENDDRAG notification messages. While handling these notifications, the owner might need to send HDM_CREATEDRAGIMAGE and HDM_SETHOTDIVIDER messages.
Hot Tracking
When this feature is enabled, the item under the pointer will be highlighted. You can check whether or not hot tracking is enabled by calling SystemParametersInfo. To enable hot tracking in a header control, create it with the HDS_HOTTRACK style.
Text, Bitmaps, and Images
Items can simultaneously display item text, a bitmap, and an image.


Header Control Reference

This section contains information about the programming elements used with header controls.

Header Control Styles

Messages
HDM_CLEARFILTER
HDM_CREATEDRAGIMAGE
HDM_DELETEITEM
HDM_EDITFILTER
HDM_GETBITMAPMARGIN
HDM_GETIMAGELIST
HDM_GETITEM
HDM_GETITEMCOUNT
HDM_GETITEMRECT
HDM_GETORDERARRAY
HDM_GETUNICODEFORMAT
HDM_HITTEST
HDM_INSERTITEM
HDM_LAYOUT
HDM_ORDERTOINDEX
HDM_SETBITMAPMARGIN
HDM_SETFILTERCHANGETIMEOUT
HDM_SETHOTDIVIDER
HDM_SETIMAGELIST
HDM_SETITEM
HDM_SETORDERARRAY
HDM_SETUNICODEFORMAT

Utility Macros
Header_ClearAllFilters
Header_ClearFilter
Header_CreateDragImage
Header_DeleteItem
Header_EditFilter
Header_GetBitmapMargin
Header_GetImageList
Header_GetItem
Header_GetItemCount
Header_GetItemRect
Header_GetOrderArray
Header_GetUnicodeFormat
Header_InsertItem
Header_Layout
Header_OrderToIndex
Header_SetBitmapMargin
Header_SetFilterChangeTimeout
Header_SetHotDivider
Header_SetImageList
Header_SetItem
Header_SetOrderArray
Header_SetUnicodeFormat

Notifications
HDN_BEGINDRAG
HDN_BEGINTRACK
HDN_DIVIDERDBLCLICK
HDN_ENDDRAG
HDN_ENDTRACK
HDN_FILTERBTNCLICK
HDN_FILTERCHANGE
HDN_GETDISPINFO
HDN_ITEMCHANGED
HDN_ITEMCHANGING
HDN_ITEMCLICK
HDN_ITEMDBLCLICK
HDN_TRACK
NM_CUSTOMDRAW (header)
NM_RCLICK (header)
NM_RELEASEDCAPTURE (header)

Structures
HD_HITTESTINFO
HD_ITEM
HD_LAYOUT
HDTEXTFILTER
HD_NOTIFY
HDHITTESTINFO
HDITEM
HDLAYOUT
NMHDDISPINFO
NMHDFILTERBTNCLICK
NMHEADER


Header Control Styles

Header controls have a number of styles, described below, that determine the control's appearance and behavior. You set the initial styles when you create the header control. To retrieve and change the styles after creating the control, use the GetWindowLong and SetWindowLong functions.

HDS_BUTTONS
Each item in the control looks and behaves like a push button. This style is useful if an application carries out a task when the user clicks an item in the header control. For example, an application could sort information in the columns differently depending on which item the user clicks.
HDS_DRAGDROP
Version 4.70. Allows drag-and-drop reordering of header items.
HDS_FILTERBAR
Version 5.80. Include a filter bar as part of the standard header control. This bar allows users to conveniently apply a filter to the display. Calls to HDM_LAYOUT will yield a new size for the control and cause the list view to update.
HDS_FULLDRAG
Version 4.70. Causes the header control to display column contents even while the user resizes a column.
HDS_HIDDEN
Indicates a header control that is intended to be hidden. This style does not hide the control. Instead, when you send the HDM_LAYOUT message to a header control with the HDS_HIDDEN style, the control returns zero in the cy member of the WINDOWPOS structure. You would then hide the control by setting its height to zero. This can be useful when you want to use the control as an information container instead of a visual control.
HDS_HORZ
Creates a header control with a horizontal orientation.
HDS_HOTTRACK
Version 4.70. Enables hot tracking.


HDM_CLEARFILTER

Clears the filter for a given header control. You can send this message explicitly or use the Header_ClearFilter macro.

HDM_CLEARFILTER
    wParam = (WPARAM) (HWND) hwnd;
    lParam = (LPARAM) (int) i;

Parameters

hwnd
Handle to the header control.
i
Column value indicating which filter to clear.

Return Values

Returns the index of the filter control being cleared.

Remarks

If the column value is specified as -1, all the filters will be cleared, and the HDN_FILTERCHANGE notification will be sent only once.

See Also

Header_ClearAllFilters

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDM_CREATEDRAGIMAGE

Creates a semi-transparent version of an item's image for use as a dragging image. You can send this message explicitly or use the Header_CreateDragImage macro.

HDM_CREATEDRAGIMAGE
    wParam = (WPARAM) (int) iIndex;
    lParam = 0;

Parameters

iIndex
Zero-based index of the item within the header control. The image assigned to this item is the basis for the transparent image.

Return Values

Returns a handle to an image list that contains the new image as its only element.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_DELETEITEM

Deletes an item from a header control. You can send this message explicitly or use the Header_DeleteItem macro.

HDM_DELETEITEM
    wParam = (WPARAM) (int) index;
    lParam = 0;

Parameters

index
Index of the item to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_EDITFILTER

Starts editing the specified filter.

HDM_EDITFILTER
    wParam = (WPARAM) (int) i;
    lParam = MAKELPARAM(fDiscardChanges, 0)

Parameters

i
Value specifying the column to edit.
fDiscardChanges
Flag that specifies how to handle the user's editing changes. Use this flag to specify what to do if the user is in the process of editing the filter when the message is sent.
TRUE
Discard the changes made by the user.
FALSE
Accept the changes made by the user.

Return Values

Returns the index of the filter being edited.

See Also

HDM_CLEARFILTER

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDM_GETBITMAPMARGIN

Retrieves the width of the bitmap margin for a header control. You can send this message explicitly or use the Header_GetBitmapMargin macro.

HDM_GETBITMAPMARGIN
    wParam = 0;
    lParam = 0;

Return Values

Returns the width of the bitmap margin in pixels. If the bitmap margin was not previously specified, the default value of 3*GetSystemMetrics(CX_EDGE) is returned.

See Also

HDM_SETBITMAPMARGIN

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDM_GETIMAGELIST

Retrieves the handle to the image list that has been set for an existing header control. You can send this message explicitly or use the Header_GetImageList macro.

HDM_GETIMAGELIST
    wParam = 0;
    lParam = 0;

Return Values

Returns a handle to the image list set for the header control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_GETITEM

Retrieves information about an item in a header control. You can send this message explicitly or use the Header_GetItem macro.

HDM_GETITEM
    wParam = (WPARAM) (int) index;
    lParam = (LPARAM) (LPHDITEM) phdi;

Parameters

index
Index of the item for which information is to be retrieved.
phdi
Address of an HDITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the HDI_TEXT flag is set in the mask member of the HDITEM structure, the control may change the pszText member of the the structure to point to the new text instead of filling the buffer with the requested text. Applications should not assume that the text will always be placed in the requested buffer.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_GETITEMCOUNT

Retrieves a count of the items in a header control. You can send this message explicitly or use the Header_GetItemCount macro.

HDM_GETITEMCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of items if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_GETITEMRECT

Retrieves the bounding rectangle for a given item in a header control. You can send this message explicitly or use the Header_GetItemRect macro.

HDM_GETITEMRECT
    wParam = (WPARAM) (int) iIndex;
    lParam = (LPARAM) lpItemRect;

Parameters

iIndex
Zero-based index of the header control item for which to retrieve the bounding rectangle.
lpItemRect
Address of a RECT structure that receives the bounding rectangle information.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_GETORDERARRAY

Retrieves the current left-to-right order of items in a header control. You can send this message explicitly or use the Header_GetOrderArray macro.

HDM_GETORDERARRAY
    wParam = (WPARAM) (int) iSize;
    lParam = (LPARAM) (LPINT) lpiArray;

Parameters

iSize
Number of integer elements that lpiArray can hold. This value must be equal to the number of items in the control (see HDM_GETITEMCOUNT).
lpiArray
Address of an array of integers that receive the index values for items in the header. The number of elements in this array is specified in iSize and must be equal to or greater than the number of items in the control. For example, the following code fragment will reserve enough memory to hold the index values.
int iItems,
    *lpiArray;

// Get memory for buffer.
(iItems = SendMessage(hwndHD, HDM_GETITEMCOUNT, 0,0))!=-1)
    if(!(lpiArray = calloc(iItems,sizeof(int))))
MessageBox(hwnd, "Out of memory.","Error", MB_OK);

Return Values

Returns nonzero if successful, and the buffer at lpiArray receives the item number for each item in the header control in the order in which they appear from left to right. Otherwise, the message returns zero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the Header_GetUnicodeFormat macro.

HDM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

HDM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_HITTEST

Tests a point to determine which header item, if any, is at the specified point.

HDM_HITTEST
    wParam = 0;
    lParam = (LPARAM) (LPHDHITTESTINFO) phdhti;

Parameters

phdhti
Address of an HDHITTESTINFO structure that contains the position to test and receives information about the results of the test.

Return Values

Returns the index of the item at the specified position, if any, or – 1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_INSERTITEM

Inserts a new item into a header control. You can send this message explicitly or use the Header_InsertItem macro.

HDM_INSERTITEM
    wParam = (WPARAM) (int) index;
    lParam = (LPARAM) (const LPHDITEM) phdi;

Parameters

index
Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.
phdi
Address of an HDITEM structure that contains information about the new item.

Return Values

Returns the index of the new item if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_LAYOUT

Retrieves the correct size and position of a header control within the parent window. You can send this message explicitly or use the Header_Layout macro.

HDM_LAYOUT
    wParam = 0;
    lParam = (LPARAM) (LPHDLAYOUT) playout;

Parameters

playout
Address of an HDLAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_ORDERTOINDEX

Retrieves an index value for an item based on its order in the header control. You can send this message explicitly or use the Header_OrderToIndex macro.

HDM_ORDERTOINDEX
    wParam = (WPARAM) iOrder;
    lParam = 0;

Parameters

iOrder
Order in which the item appears within the header control, from left to right. For example, the index value of the item in the far left column would be 0. The value for the next item to the right would be 1, and so on.

Return Values

Returns INT that indicates the item index. If iOrder is invalid (negative or too large), the return equals iOrder.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_SETBITMAPMARGIN

Sets the width of the margin, specified in pixels, of a bitmap in an existing header control. You can send this message explicitly or use the Header_SetBitmapMargin macro.

HDM_SETBITMAPMARGIN
    wParam = (WPARAM) (int) iWidth;
    lParam = 0;

Parameters

iWidth
Width, specified in pixels, of the margin that surrounds a bitmap within an existing header control.

Return Values

Returns the width of the bitmap margin, in pixels. If the bitmap margin was not previously specified, the default value of 3*GetSystemMetrics(CX_EDGE) is returned.

See Also

HDM_GETBITMAPMARGIN

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDM_SETFILTERCHANGETIMEOUT

Sets the timeout interval between the time a change takes place in the filter attributes and the posting of an HDN_FILTERCHANGED notification. You can send this message explicitly or use the Header_SetFilterChangeTimeout macro.

HDM_SETFILTERCHANGETIMEOUT
    wParam = 0;
    lParam = (LPARAM) i;

Parameters

i
Timeout value, in milliseconds.

Return Values

Returns the index of the filter control being modified.

See Also

HDN_FILTERCHANGE

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDM_SETHOTDIVIDER

Changes the color of a divider between header items to indicate the destination of an external drag-and-drop operation. You can send this message explicitly or use the Header_SetHotDivider macro.

HDM_SETHOTDIVIDER
    wParam = (WPARAM) flag;
    lParam = (LPARAM) dwInputValue;

Parameters

flag
Value specifying the type of value represented by dwInputValue. This value can be one of the following:
TRUE | Indicates that dwInputValue holds the client coordinates of the pointer.
FALSE | Indicates that dwInputValue holds a divider index value.
dwInputValue
Value held in dwInputValue is interpreted depending on the value of flag.

If flag is TRUE, dwInputValue represents the x- and y-coordinates of the pointer. The x-coordinate is in the low word, and the y-coordinate is in the high word. When the header control receives the message, it highlights the appropriate divider based on the dwInputValue coordinates.

If flag is FALSE, dwInputValue represents the integer index of the divider to be highlighted.

Return Values

Returns a value equal to the index of the divider that the control highlighted.

Remarks

This message creates an effect that a header control automatically produces when it has the HDS_DRAGDROP style. The HDM_SETHOTDIVIDER message is intended to be used when the owner of the control handles drag-and-drop operations manually.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_SETIMAGELIST

Assigns an image list to an existing header control. You can send this message explicitly or use the Header_SetImageList macro.

HDM_SETIMAGELIST
    wParam = 0;
    lParam = (LPARAM) himl;

Parameters

himl
Handle to an image list.

Return Values

Returns the handle to the image list previously associated with the control. Returns NULL upon failure or if no image list was set previously.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_SETITEM

Sets the attributes of the specified item in a header control. You can send this message explicitly or use the Header_SetItem macro.

HDM_SETITEM
    wParam = (WPARAM)(int) iIndex;
    lParam = (LPARAM)(const LPHDITEM) phdItem;

Parameters

iIndex
Current index of the item whose attributes are to be changed.
phdItem
Address of an HDITEM structure that contains item information. When this message is sent, the mask member of the structure must be set to indicate which attributes are being set.

Return Values

Returns nonzero upon success, or zero otherwise.

Remarks

The HDITEM structure that supports this message supports item order and image list information. By using these members, you can control the order in which items are displayed and specify images to appear with items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDM_SETORDERARRAY

Sets the left-to-right order of header items. You can send this message explicitly or use the Header_SetOrderArray macro.

HDM_SETORDERARRAY
    wParam = (WPARAM) (int) iSize;
    lParam = (LPARAM) lpiArray;

Parameters

iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Address of an array that specifies the order in which items should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays item 2, item 0, and item 1, from left to right.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the Header_SetUnicodeFormat macro.

HDM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

See also HDM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_ClearAllFilters

Clears all of the filters for a given header control. You can use this macro or send the HDM_CLEARFILTER message explicitly.

int Header_ClearAllFilters(
    HWND hwnd
);

Parameters

hwnd
Handle to the header control.

Remarks

When all the filters are cleared, the HDN_FILTERCHANGE notification will be sent only once.

See Also

Header_ClearFilter

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


Header_ClearFilter

Clears the filter for a given header control. You can use this macro or send the HDM_CLEARFILTER message explicitly.

int Header_ClearFilter(
    HWND hwnd,
    int i
);

Parameters

hwnd
Handle to the header control.
i
Value specifying the column of the filter to be cleared. Specifying -1 will clear all of the filters.

Remarks

If the column value is specified as -1, all the filters will be cleared and the HDN_FILTERCHANGE notification will be sent only once.

See Also

Header_ClearAllFilters

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


Header_CreateDragImage

Creates a transparent version of an item image within an existing header control. You can use this macro or send the HDM_CREATEDRAGIMAGE message explicitly.

HIMAGELIST Header_CreateDragImage(
    HWND hwndHD,
    int iIndex
);

Parameters

hwndHD
Handle to a header control.
iIndex
Zero-based index of the item within the header control. The image assigned to this item is used as the basis for the transparent image.

Return Values

Returns a handle to an image list that contains the new image as its only element.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_DeleteItem

Deletes an item from a header control. You can use this macro or send the HDM_DELETEITEM message explicitly.

BOOL Header_DeleteItem(
    HWND hwndHD,
    int index
   );

Parameters

hwndHD
Handle to the header control.
index
Index of the item to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The Header_DeleteItem macro is defined as follows:

#define Header_DeleteItem(hwndHD, index)     \
      (BOOL)SendMessage((hwndHD), HDM_DELETEITEM, (WPARAM)(int)(index), 0L)

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_EditFilter

Starts editing the specified filter control.

int Header_EditFilter(
    HWND hwnd,
    int i,
    fDiscardChanges
);

Parameters

hwnd
Handle to the header control.
i
Value specifying the column to edit.
fDiscardChanges
Flag that specifies how to handle the user's editing changes. Use this flag to specify what to do if the user is in the process of editing the filter when the message is sent.
TRUE
Discard the changes made by the user.
FALSE
Accept the changes made by the user.

Return Values

Returns the index of the filter control being edited.

See Also

HDM_EDITFILTER

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


Header_GetBitmapMargin

Retrieves the width of the margin (in pixels) of a bitmap in an existing header control. You can use this macro or send the HDM_GETBITMAPMARGIN message explicitly.

int Header_GetBitmapMargin(
    HWND hwnd
);

Parameters

hwnd
Handle to a header control.

Return Values

Returns the width of the bitmap margin in pixels. If the bitmap margin was not previously specified, the default value of 3*GetSystemMetrics(CX_EDGE) is returned.

See Also

Header_SetBitmapMargin

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


Header_GetImageList

Retrieves the handle to the image list that has been set for an existing header control. You can use this macro or send the HDM_GETIMAGELIST message explicitly.

HIMAGELIST Header_GetImageList(HWND hwndHD);

Parameters

hwndHD
Handle to a header control.

Return Values

Returns the handle to the image list that is set for the header control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_GetItem

Retrieves information about an item in a header control. You can use this macro or send the HDM_GETITEM message explicitly.

BOOL Header_GetItem(
    HWND hwndHD,
    int index,
    LPHDITEM phdi
   );

Parameters

hwndHD
Handle to the header control.
index
Index of the item for which information is to be retrieved.
phdi
Address of an HDITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the HDI_TEXT flag is set in the mask member of the HDITEM structure, the control may change the pszText member of the the structure to point to the new text instead of filling the buffer with the requested text. Applications should not assume that the text will always be placed in the requested buffer.

The Header_GetItem macro is defined as follows:

#define Header_GetItem(hwndHD, index, phdi)      \
    (BOOL)SendMessage((hwndHD), HDM_GETITEM,   \
    (WPARAM)(int)(index), (LPARAM)(LPHDITEM)(phdi))

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_GetItemCount

Retrieves a count of the items in a header control. You can use this macro or send the HDM_GETITEMCOUNT message explicitly.

int Header_GetItemCount(
    HWND hwndHD
   );

Parameters

hwndHD
Handle to the header control.

Return Values

Returns the number of items if successful, or -1 otherwise.

Remarks

The Header_GetItemCount macro is defined as follows:

#define Header_GetItemCount(hwndHD)   \
       (int)SendMessage((hwndHD), HDM_GETITEMCOUNT, 0, 0L)

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_GetItemRect

Retrieves the bounding rectangle for a given item in a header control. You can use this macro or send the HDM_GETITEMRECT message explicitly.

BOOL Header_GetItemRect(
    HWND hwndHD,
    int iIndex,
    LPRECT lpItemRect
);

Parameters

hwndHD
Handle to a header control.
iIndex
Zero-based index of the header control item for which to retrieve the bounding rectangle.
lpItemRect
Address of a RECT structure that receives the bounding rectangle information.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_GetOrderArray

Retrieves the current left-to-right order of items in a header control. You can use this macro or send the HDM_GETORDERARRAY message explicitly.

BOOL Header_GetOrderArray(
    HWND hwndHD,
    int iSize,
    int *lpiArray
);

Parameters

hwndHD
Handle to a header control.
iSize
Number of integer elements that lpiArray can hold. This value must be equal to or greater than the number of items in the control (see HDM_GETITEMCOUNT).
lpiArray
Address of an array of integers that receive the index values for items in the header. The number of elements in this array is specified in iSize and must be equal to or greater than the number of items in the control. For example, the following code fragment will reserve enough memory to hold the index values.
int iItems,
    *lpiArray;

// Get memory for buffer
if((iItems = SendMessage(hwndHD, HDM_GETITEMCOUNT, 0,0))!=-1)
    if(!(lpiArray = calloc(iItems,sizeof(int))))
MessageBox(hwnd, "Out of memory.","Error", MB_OK);

Return Values

Returns nonzero if successful, and the buffer at lpiArray receives the item number of each item in the header control in the order in which they appear from left to right. Returns zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_GetUnicodeFormat

Retrieves the UNICODE character format flag for the control. You can use this macro or send the HDM_GETUNICODEFORMAT message explicitly.

BOOL Header_GetUnicodeFormat(
    HWND hwnd
);

Parameters

hwnd
Handle to the control.

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

See Also

Header_SetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_InsertItem

Inserts a new item into a header control. You can use this macro or send the HDM_INSERTITEM message explicitly.

int Header_InsertItem(
    HWND hwndHD,
    int index,
    LPHDITEM phdi
   );

Parameters

hwndHD
Handle to the header control.
index
Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.
phdi
Address of an HDITEM structure that contains information about the new item.

Return Values

Returns the index of the new item if successful, or -1 otherwise.

Remarks

The Header_InsertItem macro is defined as follows:

#define Header_InsertItem(hwndHD, index, phdi) \
    (int)SendMessage((hwndHD), HDM_INSERTITEM, (WPARAM)(int)(index), \
    (LPARAM)(const LPHDITEM)(phdi))

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_Layout

Retrieves the correct size and position of a header control within the parent window. You can use this macro or send the HDM_LAYOUT message explicitly.

BOOL Header_Layout(
    HWND hwndHD,
    LPHDLAYOUT playout
   );

Parameters

hwndHD
Handle to the header control.
playout
Address of an HDLAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The Header_Layout macro is defined as follows:

#define Header_Layout(hwndHD, playout) \
    (BOOL)SendMessage((hwndHD), HDM_LAYOUT, 0, \
    (LPARAM)(PLHDLAYOUT)(playout))

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_OrderToIndex

Retrieves an index value for an item based on its order in the header control. You can use this macro or send the HDM_ORDERTOINDEX message explicitly.

int Header_OrderToIndex(
    HWND hwndHD,
    int iOrder
);

Parameters

hwndHD
Handle to a header control.
iOrder
Order that the item appears within the header control, from left to right. The index value of the item in the far left column would be 0, the next item to the right would be 1, and so on.

Return Values

Returns an INT that specifies the index of the item. If iOrder is invalid (negative or too large), the return equals iOrder.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_SetBitmapMargin

Sets the width of the margin for a bitmap in an existing header control. You can use this macro or send the HDM_SETBITMAPMARGIN message explicitly.

int Header_SetBitmapMargin(
    HWND hwnd,
    int iWidth
);

Parameters

hwnd
Handle to a header control.
iWidth
Width, specified in pixels, of the margin that surrounds a bitmap within an existing header control.

Return Values

Returns width of the bitmap margin in pixels. If the bitmap margin was not previously specified, the default value of 3*GetSystemMetrics(CX_EDGE) is returned.

See Also

Header_GetBitmapMargin

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


Header_SetFilterChangeTimeout

Sets the timeout interval between the time a change takes place in the filter attributes and the posting of an HDN_FILTERCHANGED notification. You can use this macro or send the HDM_SETFILTERCHANGETIMEOUT message explicitly.

int Header_SetFilterChangeTimeout(
    HWND hwnd,
    int i
);

Parameters

hwnd
Handle to the header control.
i
Timeout value, in milliseconds.

Return Values

Returns the index of the filter control being modified.

See Also

HDN_FILTERCHANGE, HDM_SETFILTERCHANGETIMEOUT

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


Header_SetHotDivider

Changes the color of a divider between header items to indicate the destination of an external drag-and-drop operation. You can use this macro or send the HDM_SETHOTDIVIDER message explicitly.

int Header_SetHotDivider(
    HWND hwndHD,
    BOOL flag,
    DWORD dwInputValue
);

Parameters

hwndHD
Handle to a header control.
flag
Value specifying how dwInputValue is to be interpreted. The value in this field can be one of the following:
TRUE | Indicates that dwInputValue holds client coordinates of the pointer.
FALSE | Indicates that dwInputValue holds a divider index value.
dwInputValue
Value held here is interpreted depending on the value of flag.

If flag is TRUE, dwInputValue represents the x- and y- client coordinates of the pointer. The x-coordinate is in the low word, and the y-coordinate is in the high word. Upon receiving the message, the header control highlights the appropriate divider based on the dwInputValue coordinates.

If flag is FALSE, dwInputValue represents the integer index of the divider that will be highlighted.

Return Values

Returns the index of the divider that the control highlighted.

Remarks

A header control set to the HDS_DRAGDROP style produces this effect automatically. This message is intended to be used when the owner of the control handles drag-and-drop operations manually.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_SetImageList

Assigns an image list to an existing header control. You can use this macro or send the HDM_SETIMAGELIST message explicitly.

HIMAGELIST Header_SetImageList(
    HWND hwndHD,
    HIMAGELIST himl
);

Parameters

hwndHD
Handle to a header control.
himl
Handle to an image list.

Return Values

Returns the handle to the image list previously assigned to the header control, or NULL if there is no previous image list.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_SetItem

Sets the attributes of the specified item in a header control. You can use this macro or send the HDM_SETITEM message explicitly.

BOOL Header_SetItem(
    HWND hwndHD,
    int iIndex;
    LPHDITEM phdItem
);

Parameters

hwndHD
Handle to a header control.
iIndex
Current index of the item whose attributes are to be changed.
phdItem
Address of an HDITEM structure that contains item information. When this message is sent, the mask member of the structure must be set to indicate which attributes are being set.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

The HDITEM structure that supports this macro supports item order and image list information. By using these members, you can control the order in which items are displayed and specify images to appear with items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Header_SetOrderArray

Sets the left-to-right order of header items. You can use this macro or send the HDM_SETORDERARRAY message explicitly.

BOOL Header_SetOrderArray(
    HWND hwndHD,
    int iSize,
    int *lpiArray
);

Parameters

hwndHD
Handle to a header control.
iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Address of an array that specifies the order in which items should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays item 2, item 0, and item 1, from left to right.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Header_SetUnicodeFormat

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the HDM_SETUNICODEFORMAT message explicitly.

BOOL Header_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Parameters

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

See Also

Header_GetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_BEGINDRAG

Sent by a header control when a drag operation has begun on one of its items. This notification message is sent only by header controls that are set to the HDS_DRAGDROP style. This notification is sent in the form of a WM_NOTIFY message.

HDN_BEGINDRAG
   pNMHeader = (LPNMHEADER) lParam;

Parameters

pNMHeader
Address of an NMHEADER structure containing information about the header item that is being dragged.

Return Values

To allow the header control to automatically manage drag-and-drop operations, return FALSE. If the owner of the control is manually performing drag-and-drop reordering, return TRUE.

Remarks

A header control defaults to automatically managing drag-and-drop reordering. Returning TRUE to indicate external (manual) drag-and-drop management allows the owner of the control to provide custom services as part of the drag-and-drop process.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDN_BEGINTRACK

Notifies a header control's parent window that the user has begun dragging a divider in the control (that is, the user has pressed the left mouse button while the mouse cursor is on a divider in the header control). This notification message is sent in the form of a WM_NOTIFY message.

HDN_BEGINTRACK
    phdn = (LPNMHEADER) lParam;

Parameters

phdn
Address of an NMHEADER structure that contains information about the header control and the item whose divider is to be dragged.

Return Values

Returns FALSE to allow tracking of the divider, or TRUE to prevent tracking.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_DIVIDERDBLCLICK

Notifies a header control's parent window that the user double-clicked the divider area of the control. This notification message is sent in the form of a WM_NOTIFY message.

HDN_DIVIDERDBLCLICK
    phdn = (LPNMHEADER) lParam;

Parameters

phdn
Address of an NMHEADER structure that contains information about the header control and the item whose divider was double-clicked.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_ENDDRAG

Sent by a header control when a drag operation has ended on one of its items. This notification is sent as a WM_NOTIFY message. Only header controls that are set to the HDS_DRAGDROP style send this notification.

HDN_ENDDRAG
   pNMHeader = (LPNMHEADER) lParam;

Parameters

pNMHeader
Address of an NMHEADER structure containing information about the header item that was being dragged.

Return Values

To allow the control to automatically place and reorder the item, return FALSE. To prevent the item from being placed, return TRUE.

Remarks

If the owner is performing external (manual) drag-and-drop management, it must return FALSE. The owner then must reorder header items manually by sending HDM_SETITEM or HDM_SETORDERARRAY.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDN_ENDTRACK

Notifies a header control's parent window that the user has finished dragging a divider. This notification message sent in the form of a WM_NOTIFY message.

HDN_ENDTRACK
    phdn = (LPNMHEADER) lParam;

Parameters

phdn
Address of an NMHEADER structure that contains information about the header control and the item whose divider was dragged.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_FILTERBTNCLICK

Notifies the header control's parent window when the filter button is clicked or in response to an HDM_SETITEM message.

HDN_FILTERBTNCLICK
    phdr = (LPNMHDFILTERBTNCLICK) lParam;

Parameters

phdr
Address of an NMHDFILTERBTNCLICK structure that contains information about the header control and the header filter button.

Return Values

If you return TRUE, an HDN_FILTERCHANGED notification will be sent to the header control's parent window. This notification gives the parent window an opportunity to synchronize its user interface elements. Return FALSE if you don't want the notification sent.

See Also

NMHDFILTERBTNCLICK

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDN_FILTERCHANGE

Notifies the header control's parent window that the attributes of a header control filter are being changed or edited.

HDN_FILTERCHANGE
    phdr = (LPNMHEADER) lParam;

Parameters

phdr
Address of an NMHEADER structure that contains information about the header control and the header item, including the attributes that are about to change.

Return Values

No return value.

See Also

HDM_SETFILTERCHANGETIMEOUT

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


HDN_GETDISPINFO

Sent to the owner of a header control when the control needs information about a callback header item. This notification is sent as a WM_NOTIFY message.

HDN_GETDISPINFO
   pDispInfo = (LPNMHDDISPINFO) lParam;

Parameters

pDispInfo
Address of an NMHDDISPINFO structure. On input, the fields of the structure specify what information is required and the item of interest.

Remarks

Fill the appropriate members of the structure to return the requested information to the header control. If your message handler sets the mask member of the NMHDDISPINFO structure to HDI_DI_SETITEM, the header control stores the information and will not request it again.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


HDN_ITEMCHANGED

Notifies a header control's parent window that the attributes of a header item have changed. This notification message is sent in the form of a WM_NOTIFY message.

HDN_ITEMCHANGED
    phdr = (LPNMHEADER) lParam;

Parameters

phdr
Address of an NMHEADER structure that contains information about the header control, including the attributes that have changed.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_ITEMCHANGING

Notifies a header control's parent window that the attributes of a header item are about to change. This notification message is sent in the form of a WM_NOTIFY message.

HDN_ITEMCHANGING
    phdr = (LPNMHEADER) lParam;

Parameters

phdr
Address of an NMHEADER structure that contains information about the header control and the header item, including the attributes that are about to change.

Return Values

Returns FALSE to allow the changes, or TRUE to prevent them.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_ITEMCLICK

Notifies a header control's parent window that the user clicked the control. This notification message is sent in the form of a WM_NOTIFY message.

HDN_ITEMCLICK
    phdr = (LPNMHEADER) lParam;

Parameters

phdr
Address of an NMHEADER structure that identifies the header control and specifies the index of the header item that was clicked and the mouse button used to click the item. The pItem member is set to NULL.

Return Values

No return value.

Remarks

A header control sends this notification message after the user releases the left mouse button.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_ITEMDBLCLICK

Notifies a header control's parent window that the user double-clicked the control. This notification message is sent in the form of a WM_NOTIFY message. Only header controls that are set to the HDS_BUTTONS style send this notification.

HDN_ITEMDBLCLICK
    pnmhdr = (LPNMHEADER) lParam;

Parameters

pnmhdr
Address of an NMHEADER structure that contains information about this notification.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDN_TRACK

Notifies a header control's parent window that the user is dragging a divider in the header control. This notification message is sent in the form of a WM_NOTIFY message.

HDN_TRACK
    phdr = (LPNMHEADER) lParam;

Parameters

phdr
Address of an NMHEADER structure that contains information about the header control and the item whose divider is being dragged.

Return Values

Returns FALSE to continue tracking the divider, or TRUE to end tracking.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (header)

Sent by a header control to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Address of an NMCUSTOMDRAW structure that contains information about the drawing operation. The dwItemSpec member of this structure contains the index of the item being drawn and the lItemlParam member of this structure contains the item's lParam.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:

CDRF_DODEFAULT | The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW | The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE | The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE | The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT | The control will notify the parent after painting an item.
CDRF_NOTIFYSUBITEMDRAW | Version 4.71. The control will notify the parent when a list-view sub-item is being drawn.

When dwDrawStage equals CDDS_ITEMPREPAINT:

CDRF_NEWFONT | Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing fonts and colors.
CDRF_SKIPDEFAULT | Your application drew the item manually. The control will not draw the item.

Remarks

See Using Custom Draw for further discussion.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.02 or later).
Header: Declared in commctrl.h.


NM_RCLICK (header)

Notifies a tree-view control's parent window that the user has clicked the right mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to not allow the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (header)

Notifies a header control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


HDHITTESTINFO

Contains information about a hit test. This structure is used with the HDM_HITTEST message. This structure supersedes the HD_HITTESTINFO structure.

typedef struct _HD_HITTESTINFO {
    POINT pt;
    UINT flags;
    int iItem;
} HDHITTESTINFO, FAR *LPHDHITTESTINFO;

Members

pt
POINT structure that contains the point to be hit test, in client coordinates.
flags
Variable that receives information about the results of a hit test. This member can be one or more of the following values:
HHT_ABOVE | The point is above the header control's bounding rectangle.
HHT_BELOW | The point is below the header control's bounding rectangle.
HHT_NOWHERE | The point is inside the header control's bounding rectangle but is not over a header item.
HHT_ONDIVIDER | The point is on the divider between two header items.
HHT_ONDIVOPEN | The point is on the divider of an item that has a width of zero. Dragging the divider reveals the item instead of resizing the item to the left of the divider.
HHT_ONHEADER | The point is inside the header control's bounding rectangle.
HHT_ONFILTER | Version 5.80 The point is over the filter area.
HHT_ONFILTERBUTTON | Version 5.80 The point is on the filter button.
HHT_TOLEFT | The point is to the left of the header control's bounding rectangle.
HHT_TORIGHT | The point is to the right of the header control's bounding rectangle.

Two of these values can be combined, such as when the position is above and to the left of the client area.

iItem
If the hit test is successful, contains the index of the item at the hit test point.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDITEM

Contains information about an item in a header control. This structure supersedes the HD_ITEM structure.

typedef struct _HDITEM {
    UINT    mask;
    int     cxy;
    LPTSTR  pszText;
    HBITMAP hbm;
    int     cchTextMax;
    int     fmt;
    LPARAM  lParam;
#if (_WIN32_IE >= 0x0300)
    int     iImage;
    int     iOrder;
#endif
#if (_WIN32_IE >= 0x0500)
    UINT    type;
    LPVOID  pvFilter;
#endif
} HDITEM, FAR * LPHDITEM;

Members

mask
Flags indicating which other structure members contain valid data or must be filled in. This member can be a combination of the following values:
Flag | Description
HDI_BITMAP | The hbm member is valid.
HDI_FORMAT | The fmt member is valid.
HDI_FILTER | Version 5.80. The type and pvFilter members are valid. This is used to filter out the values specified in the type member.
HDI_HEIGHT | The cxy member is valid and specifies the item's height.
HDI_IMAGE | Version 4.70. The iImage member is valid and specifies the image to be displayed with the item.
HDI_LPARAM | The lParam member is valid.
HDI_ORDER | Version 4.70. The iOrder member is valid and specifies the item's order value.
HDI_TEXT | The pszText and cchTextMax members are valid.
HDI_WIDTH | The cxy member is valid and specifies the item's width.
cxy
Width or height of the item.
pszText
Address of an item string. If the text is being retrieved from the control, this member must be initialized to point to a character buffer. If this member is set to LPSTR_TEXTCALLBACK, the control will request text information for this item by sending an HDN_GETDISPINFO notification message.
hbm
Handle to the item bitmap.
cchTextMax
Length of the item string, in characters. If the text is being retrieved from the control, this member must contain the number of characters at the address specified by pszText.
fmt
Flags that specify the item's format.

Set one of the following flags to specify text justification:

Flag | Description
HDF_CENTER | The item's contents are centered.
HDF_LEFT | The item's contents are left-aligned.
HDF_RIGHT | The item's contents are right-aligned.

Set one of the following flags to control the display:

Flag | Description
HDF_BITMAP | The item displays a bitmap.
HDF_BITMAP_ON_RIGHT | Version 4.70. The bitmap appears to the right of text.
HDF_OWNERDRAW | The header control's owner draws the item.
HDF_STRING | The item displays a string.

The preceding value can be combined with:

Flag | Description
HDF_IMAGE | Version 4.70. Display an image from an image list. Specify the image list by sending an HDM_SETIMAGELIST message. Specify the index of the image in the iImage member of this structure.
HDF_JUSTIFYMASK | Isolate the bits corresponding to the three justification flags listed in the preceding table.
HDF_RTLREADING | Typically, windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Usually, header text is read in the same direction as the the text in its parent window. If HDF_RTLREADING is set, header text will read in the opposite direction from the text in the parent window.
lParam
Application-defined item data.
iImage
Version 4.70. Zero-based index of an image within the image list. The specified image will be displayed in the header item in addition to any image specified in the hbm field. If iImage is set to I_IMAGECALLBACK, the control requests text information for this item by using an HDN_GETDISPINFO notification message.
iOrder
Version 4.70. Order in which the item appears within the header control, from left to right. That is, the value for the far left item is 0. The value for the next item to the right is 1, and so on.
type
Version 5.80. Type of filter specified by pvFilter. The possible types include:
Flag | Description
HDFT_ISTRING | String data.
HDFT_ISNUMBER | Numerical data.
HDFT_HASNOVALUE | Ignore pvFilter.
pvFilter
Version 5.80. Address of an application-defined data item. The data filter type is determined by setting the flag value of the type member.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


HDLAYOUT

Contains information used to set the size and position of a header control. HDLAYOUT is used with the HDM_LAYOUT message. This structure supersedes the HD_LAYOUT structure.

typedef struct _HD_LAYOUT {
    RECT FAR*      prc;
    WINDOWPOS FAR* pwpos;
} HDLAYOUT, FAR *LPHDLAYOUT;

Members

prc
Address of a RECT structure that contains the coordinates of a rectangle that the header control will occupy.
pwpos
Address of a WINDOWPOS structure that receives information about the appropriate size and position of the header control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HDTEXTFILTER

HDTEXTFILTER Structure

Contains information about header control text filters.

typedef struct _HDTEXTFILTER {
    LPTSTR pszText;
    INT cchTextMax;
} HDTEXTFILTER, FAR * LPHD_TEXTFILTER;

Members

pszText
[in] Address of the buffer containing the filter.
cchTextMax
[in] Value specifying the maximum size, in characters, for an edit control buffer.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


NMHDDISPINFO

Contains information used in handling HDN_GETDISPINFO notification messages.

typedef struct tagNMHDDISPINFO {
    NMHDR   hdr;
    int     iItem;
    UINT    mask;
    LPTSTR  pszText;
    int     cchTextMax;
    int     iImage;
    LPARAM  lParam;
} NMHDDISPINFO, FAR* LPNMHDDISPINFO;

Members

hdr
NMHDR structure containing information about this notification message.
iItem
Zero-based index of the item in the header control.
mask
Set of bit flags specifying which members of the structure must be filled in by the owner of the header control. This value can be a combination of the following values:
HDI_TEXT | The pszText field must be filled in.
HDI_IMAGE | Version 4.70. The iImage field must be filled in.
HDI_LPARAM | The lParam field must be filled in.
HDI_DI_SETITEM | Version 4.70. A return value. Indicates that the header control should store the item information and not ask for it again.
pszText
Address of a null-terminated string containing the text that will be displayed for the header item.
cchTextMax
Size of the buffer that pszText points to.
iImage
Zero-based index of an image within the image list. The specified image will be displayed with the header item, but it does not take the place of the item's bitmap. If iImage is set to I_IMAGECALLBACK, the control requests image information for this item by using an HDN_GETDISPINFO notification message.
lParam
An application-defined value to associate with the item.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMHDFILTERBTNCLICK

NMHDFILTERBTNCLICK Structure

Specifies or receives the attributes of a filter button click.

typedef struct tagNMHDFILTERBTNCLICK {
    NMHDR hdr;
    INT iItem;
    RECT rc;
} NMHDFILTERBTNCLICK, FAR* LPNMHDFILTERBTNCLICK;

Members

hdr
Handle of an NMHDR structure that contains additional information.
iItem
Zero-based index of the control to which this structure refers.
rc
Address of a RECT structure that contains the client rectangle for the filter button.

See Also

HDN_FILTERBTNCLICK

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


NMHEADER

Contains information about header control notification messages. This structure supersedes the HD_NOTIFY structure.

typedef struct tagNMHEADER{
    NMHDR    hdr;
    int      iItem;
    int      iButton;
    HDITEM  FAR* pitem;
} NMHEADER, FAR* LPNMHEADER;

Members

hdr
NMHDR structure that contains information about the notification message.
iItem
Zero-based index of the header item that is the focus of the notification message.
iButton
Value specifying the index of the mouse button used to generate the notification message. This member can be one of the following values:
0 | Left button
1 | Right button
2 | Middle button
pitem
Optional pointer to an HDITEM structure containing information about the item specified by iItem. The mask member of the HDITEM structure indicates which of its members are valid.

Remarks

While most header control notifications pass a pointer to an NMHEADER structure, only some of them use the pItem member to pass an HDITEM structure. Those that do use pItem may not provide complete information about the item. To obtain more information about an item, use HDM_GETITEM.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


Hot Key Controls

A hot key control is a window that enables the user to enter a combination of keystrokes to be used as a hot key. A hot key is a key combination that the user can press to perform an action quickly. For example, a user can create a hot key that activates a given window and brings it to the top of the z-order. The hot key control displays the user's choices and ensures that the user selects a valid key combination.

  • Using Hot Key Controls
  • Hot Key Control Reference

Using Hot Key Controls

When the user enters a key combination to be used as a hot key, the names of the keys appear in the hot key control. A key combination can consist of a modifier key (such as CTRL, ALT, or SHIFT) and an accompanying key (such as a character key, an arrow key, a function key, and so on).

After the user has chosen a key combination, the application retrieves the key combination from the hot key control and uses it to set up a hot key in the system. The information retrieved from the hot key control includes a flag indicating the modifier key and the virtual key code of the accompanying key.

The application can use the information provided by a hot key control to set up a global hot key or a thread-specific hot key. A global hot key is associated with a particular window; it allows the user to activate the window from any part of the system. An application sets a global hot key by using the WM_SETHOTKEY message. Whenever the user presses a global hot key, the window specified in WM_SETHOTKEY receives a WM_SYSCOMMAND message that specifies the SC_HOTKEY value. This message activates the window that receives it. The hot key remains valid until the application that called WM_SETHOTKEY exits.

A thread-specific hot key generates a WM_HOTKEY message that is posted to the beginning of a particular thread so that it is removed by the next iteration of the message loop. An application sets a thread-specific hot key by using the RegisterHotKey function.

Hot Key Control Creation

You create a hot key control by using the CreateWindowEx function, specifying the HOTKEY_CLASS window class. When the function returns a handle to the hot key control, an application typically sets some rules about invalid hot key combinations and may provide a default key combination. If an application does not set any rules, the user can choose any key or key combination as a hot key. Most applications, however, do not allow the user to use a common key (for example, the letter A) as a hot key.

The following function creates a hot key control, uses the HKM_SETRULES and HKM_SETHOTKEY messages to initialize it, and returns a handle to the control. This hot key control does not allow the user to choose a hot key that is a single unmodified key, nor does it permit the user to choose only SHIFT and a key. (These rules effectively prevent the user from choosing a hot key that might be entered accidentally while typing text.)

// InitializeHotkey - creates a hot key control and sets rules
//    and default settings for it.
// Returns the handle of the hot key control.
// hwndDlg - handle of the parent window (dialog box).
//
// Global variable
//     g_hinst - handle of the application instance.
extern HINSTANCE g_hinst;
HWND WINAPI InitializeHotkey(HWND hwndDlg)
{
    HWND hwndHot = NULL;

    // Ensure that the common control DLL is loaded.
    InitCommonControls();

    hwndHot = CreateWindowEx(
        0,                             // no extended styles
        HOTKEY_CLASS,                  // class name
        "",                            // no title (caption)
        WS_CHILD | WS_VISIBLE,         // style
        10, 10,                        // position
        200, 20,                       // size
        hwndDlg,                       // parent window
        NULL,                          // uses class menu
        g_hinst,                       // instance
        NULL                           // no WM_CREATE parameter
        );

    SetFocus(hwndHot);

    // Set rules for invalid key combinations. If the user
    // does not supply a modifier key, use ALT as a modifier.
    // If the user supplies SHIFT as a modifier key, use
    // SHIFT + ALT instead.
    SendMessage(hwndHot, HKM_SETRULES,
        (WPARAM) HKCOMB_NONE | HKCOMB_S, // invalid key combinations
        MAKELPARAM(HOTKEYF_ALT, 0));     // add ALT to invalid entries

    // Set CTRL + ALT + A as the default hot key for this window.
    // 0x41 is the virtual key code for 'A'.
    SendMessage(hwndHot, HKM_SETHOTKEY,
        MAKEWORD(0x41, HOTKEYF_CONTROL | HOTKEYF_ALT), 0);

    return hwndHot;
}

Hot Key Control Messages

After creating a hot key control, an application interacts with it by using three messages: HKM_SETRULES, HKM_SETHOTKEY, and HKM_GETHOTKEY.

An application can send the HKM_SETRULES message to specify a set of CTRL, ALT, and SHIFT key combinations that are considered invalid hot keys. If the application specifies an invalid key combination, it should also specify a default modifier combination to use when the user selects the invalid combination. When the user enters the invalid combination, the system performs a logical OR operation on the invalid combination and the default combination. The result is considered a valid combination; it is converted to a string and displayed in the control.

The HKM_SETHOTKEY message allows an application to set the hot key combination for a hot key control. This message is also typically used when the hot key control is created.

Applications use the HKM_GETHOTKEY message to retrieve the virtual key code and modifier flags of the hot key chosen by the user.

Hot Key Control Notifications

The hot key control does not send any notification messages via the WM_NOTIFY message. It will, however, send the EN_CHANGE notification via the WM_COMMAND message when the user changes the contents of the control.

Retrieving and Setting a Hot Key

After the user has chosen a hot key, an application should retrieve it from the hot key control by using the HKM_GETHOTKEY message. This message retrieves a 16-bit value that contains the virtual key code and modifier keys describing the hot key.

The following function retrieves a key combination from a hot key control and then uses the WM_SETHOTKEY message to set a global hot key. Note that you cannot set a global hot key for a window that has the WS_CHILD window style.

// ProcessHotkey - retrieves the hot key from the hot key control and
//     sets it as the hot key for the application's main window.
// Returns TRUE if successful, or FALSE otherwise.
// hwndHot - handle of the hot key control.
// hwndMain - handle of the main window.
BOOL WINAPI ProcessHotkey(HWND hwndHot, HWND hwndMain)
{
WORD wHotkey;
UINT iSetResult;

// Retrieve the hot key (virtual key code and modifiers).
wHotkey = SendMessage(hwndHot, HKM_GETHOTKEY, 0, 0);

// Use the result as wParam for WM_SETHOTKEY.
iSetResult = SendMessage(hwndMain, WM_SETHOTKEY, wHotkey, 0);

switch (iSetResult)
    {
    case 2:            // WM_SETHOTKEY succeeded.
        MessageBox(NULL, "Hot key previously assigned",
            "Okay", MB_OK);
        return TRUE;

    case 1:            // WM_SETHOTKEY succeeded.
        return TRUE;

    case 0:
        MessageBox(NULL, "Invalid window for hot key",
            "Error", MB_OK);
        return FALSE;

    case -1:
        MessageBox(NULL, "Invalid hot key",
            "Error", MB_OK);
        return FALSE;

    default:
        MessageBox(NULL, "Unknown error", "Error", MB_OK);
        return FALSE;
    }
}

Default Hot Key Message Processing

This section describes the window messages handled by the window procedure for the pre defined HOTKEY_CLASS window class used with hot key controls.
Message | Processing performed
WM_CHAR | Retrieves the virtual key code.
WM_CREATE | Initializes the hot key control, clears any hot key rules, and uses the system font.
WM_ERASEBKGND | Hides the caret, calls the DefWindowProc function, and shows the caret again.
WM_GETDLGCODE | Returns a combination of the DLGC_WANTCHARS and DLGC_WANTARROWS values.
WM_GETFONT | Retrieves the font.
WM_KEYDOWN | Calls the DefWindowProc function if the key is ENTER, TAB, SPACE BAR, DEL, ESC, or BACKSPACE. If the key is SHIFT, CTRL, or ALT, it checks whether the combination is valid and, if it is, sets the hot key using the combination. All other keys are set as hot keys without their validity being checked first.
WM_KEYUP | Retrieves the virtual key code.
WM_KILLFOCUS | Destroys the caret.
WM_LBUTTONDOWN | Sets the focus to the window.
WM_NCCREATE | Sets the WS_EX_CLIENTEDGE window style.
WM_PAINT | Paints the hot key control.
WM_SETFOCUS | Creates and shows the caret.
WM_SETFONT | Sets the font.
WM_SYSCHAR | Retrieves the virtual key code.
WM_SYSKEYDOWN | Calls the DefWindowProc function if the key is ENTER, TAB, SPACE BAR, DEL, ESC, or BACKSPACE. If the key is SHIFT, CTRL, or ALT, it checks whether the combination is valid and, if it is, sets the hot key using the combination. All other keys are set as hot keys without their validity being checked first.
WM_SYSKEYUP | Retrieves the virtual key code.


HKM_GETHOTKEY

Retrieves the virtual key code and modifier flags of a hot key from a hot key control.

HKM_GETHOTKEY
    wParam = 0;
    lParam = 0;

Return Values

Returns the virtual key code and modifier flags. The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:
HOTKEYF_ALT | ALT key
HOTKEYF_CONTROL | CTRL key
HOTKEYF_EXT | Extended key
HOTKEYF_SHIFT | SHIFT key

Remarks

The 16-bit value returned by this message can be used as the wParam parameter in the WM_SETHOTKEY message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HKM_SETHOTKEY

Sets the hot key combination for a hot key control.

HKM_SETHOTKEY
    wParam = MAKEWORD(bVKHotKey, bfMods);
    lParam = 0;

Parameters

bVKHotKey
Virtual key code of the hot key.
bfMods
Modifier flags indicating the keys that, when used in combination with bVKHotKey, define a hot key combination. For a list of modifier flag values, see the description of the HKM_GETHOTKEY message.

Return Values

No return value.

See Also

WM_GETHOTKEY

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


HKM_SETRULES

Defines the invalid combinations and the default modifier combination for a hot key control.

HKM_SETRULES
    wParam = (WPARAM) fwCombInv;
    lParam = MAKELPARAM(fwModInv, 0);

Parameters

fwCombInv
Array of flags that specify invalid key combinations. This parameter can be a combination of the following values:
HKCOMB_A | ALT
HKCOMB_C | CTRL
HKCOMB_CA | CTRL+ALT
HKCOMB_NONE | Unmodified keys
HKCOMB_S | SHIFT
HKCOMB_SA | SHIFT+ALT
HKCOMB_SC | SHIFT+CTRL
HKCOMB_SCA | SHIFT+CTRL+ALT
fwModInv
Array of flags that specify the key combination to use when the user enters an invalid combination. For a list of modifier flag values, see the description of the HKM_GETHOTKEY message.

Return Values

No return value.

Remarks

When a user enters an invalid key combination, as defined by flags specified in fwCombInv, the system uses the bitwise-OR operator to combine the keys entered by the user with the flags specified in fwModInv. The resulting key combination is converted into a string and then displayed in the hot key control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Image Lists

An image list is a collection of images of the same size, each of which can be referred to by its index. Image lists are used to efficiently manage large sets of icons or bitmaps. All images in an image list are contained in a single, wide bitmap in screen device format. An image list can also include a monochrome bitmap that contains masks used to draw images transparently (icon style).

  • Using Image Lists
  • Image List Updates in Internet Explorer
  • Image List Reference

Using Image Lists

The Microsoft® Win32® application programming interface (API) provides image list functions that enable you to create and destroy image lists, add and remove images, replace and merge images, draw images, and drag images.

To use the image list functions, include the common control header file in your source code files and link with the common control export library. In addition, before calling any image list function, use the InitCommonControls function to ensure that the common control dynamic-link library (DLL) is loaded.

Types

There are two types of image lists: nonmasked and masked. A nonmasked image list consists of a color bitmap that contains one or more images. A masked image list consists of two bitmaps of equal size. The first is a color bitmap that contains the images, and the second is a monochrome bitmap that contains a series of masks—one for each image in the first bitmap.

When a nonmasked image is drawn, it is simply copied into the target device context; that is, it is drawn over the existing background color of the device context. When a masked image is drawn, the bits of the image are combined with the bits of the mask, typically producing transparent areas in the bitmap where the background color of the target device context shows through. There are several drawing styles that you can specify when drawing a masked image. For example, you can specify that the image be dithered to indicate a selected object.

Creating and Destroying Image Lists

You create an image list by calling the ImageList_Create function. The parameters include the type of image list to create, the dimensions of each image, and the number of images you intend to add to the list. For a nonmasked image list, the function creates a single bitmap large enough to hold the specified number of images of the given dimensions. Then it creates a screen-compatible device context and selects the bitmap into it. For a masked image list, the function creates two bitmaps and two screen-compatible device contexts. It selects the image bitmap into one device context and the mask bitmap into the other. The common control DLL contains the executable code for the image list functions.

In ImageList_Create, you specify the initial number of images that will be in an image list as well as the number of images by which the list can grow. So if you attempt to add more images than you initially specified, the image list automatically grows to accommodate the new images.

If ImageList_Create succeeds, it returns a handle to the HIMAGELIST type. You use this handle in other image list functions to access the image list and manage the images. You can add and remove images, copy images from one image list to another, and merge images from two different image lists. When you no longer need an image list, you can destroy it by specifying its handle in a call to the ImageList_Destroy function.

The following example creates a masked image list and uses the ImageList_AddIcon function to add two icons to the list.

// AddIconsToImageList - creates a masked image list and adds some
//     icons to it.
// Returns the handle to the new image list.
// hinst - handle to the application instance.
//
// Global variables and constants
//     g_nBird and g_nTree - indexes of the images.
//     cx_icon and cy_icon - width and height of the icon.
//     num_icons - number of icons to add to the image list.
extern int g_nBird, g_nTree;

#define CX_ICON  32
#define CY_ICON  32
#define NUM_ICONS 3

HIMAGELIST AddIconsToImageList(HINSTANCE hinst)
{
    HIMAGELIST himlIcons;  // handle to new image list
    HICON hicon;           // handle to icon

    // Ensure that the common control DLL is loaded.
    InitCommonControls();

    // Create a masked image list large enough to hold the icons.
    himlIcons = ImageList_Create(CX_ICON, CY_ICON, ILC_MASK, NUM_ICONS, 0);

    // Load the icon resources, and add the icons to the image list.
    hicon = LoadIcon(hinst, MAKEINTRESOURCE(IDI_BIRD));
    g_nBird = ImageList_AddIcon(himlIcons, hicon);

    hicon = LoadIcon(hinst, MAKEINTRESOURCE(IDI_TREE));
    g_nTree = ImageList_AddIcon(himlIcons, hicon);

    return himlIcons;
}

Adding and Removing Images

You can add bitmapped images, icons, or cursors to an image list. You add bitmapped images by specifying the handles to two bitmaps in a call to the ImageList_Add function. The first bitmap contains one or more images to add to the image bitmap, and the second bitmap contains the masks to add to the mask bitmap. For nonmasked image lists, the second bitmap handle is ignored; it can be set to NULL.

The ImageList_AddMasked function also adds bitmapped images to a masked image list. This function is similar to ImageList_Add, except that you do not specify a mask bitmap. Instead, you specify a color that the system combines with the image bitmap to automatically generate the masks. Each pixel of the specified color in the image bitmap is changed to black, and the corresponding bit in the mask is set to 1. As a result, any pixel in the image that matches the specified color is transparent when the image is drawn.

The ImageList_AddIcon function adds an icon or cursor to an image list. If the image list is masked, ImageList_AddIcon adds the mask provided with the icon or cursor to the mask bitmap. If the image list is nonmasked, the mask for the icon or cursor is not used when drawing the image.

You can create an icon based on an image and mask in an image list by using the ImageList_GetIcon function. The function returns the handle to the new icon.

ImageList_Add, ImageList_AddMasked, and ImageList_AddIcon assign an index to each image as it is added to an image list. The indexes are zero-based; that is, the first image in the list has an index of zero, the next has an index of one, and so on. After adding a single image, the functions return the index of the image. When more than one image is added at a time, the functions return the index of the first image.

The ImageList_Remove function removes an image from an image list.

Replacing and Merging Images

The ImageList_Replace and ImageList_ReplaceIcon functions replace an image in an image list with a new image. ImageList_Replace replaces an image with a bitmapped image and mask, and ImageList_ReplaceIcon replaces an image with an icon or cursor.

The ImageList_Merge function merges two images, storing the new image in a new image list. The new image is created by drawing the second image transparently over the first. The mask for the new image is the result of performing a logical OR operation on the bits of the masks for the two existing images.

Drawing Images

To draw an image, you use the ImageList_Draw or ImageList_DrawEx function. You specify the handle to an image list, the index of the image to draw, the handle to the destination device context, a location within the device context, and one or more drawing styles.

When you specify the ILD_TRANSPARENT style, ImageList_Draw or ImageList_DrawEx uses a two-step process to draw a masked image. First, it performs a logical AND operation on the bits of the image and the bits of the mask. Then it performs a logical XOR operation on the results of the first operation and the background bits of the destination device context. This process creates transparent areas in the resulting image; that is, each white bit in the mask causes the corresponding bit in the resulting image to be transparent.

Before drawing a masked image on a solid color background, you should use the ImageList_SetBkColor function to set the background color of the image list to the same color as the destination. Setting the color eliminates the need to create transparent areas in the image and enables ImageList_Draw or ImageList_DrawEx to simply copy the image to the destination device context, resulting in a significant increase in performance. To draw the image, specify the ILD_NORMAL style in a call to ImageList_Draw or ImageList_DrawEx.

You can set the background color for a masked image list at any time so that it draws correctly on any solid background. Setting the background color to CLR_NONE causes images to be drawn transparently by default. To retrieve the background color of an image list, use the ImageList_GetBkColor function.

The ILD_BLEND25 and ILD_BLEND50 styles dither the image with the system highlight color. These styles are useful if you use a masked image to represent an object that the user can select. For example, you can use the ILD_BLEND50 style to draw the image when the user selects it.

A nonmasked image is copied to the destination device context using the SRCCOPY raster operation. The colors in the image appear the same regardless of the background color of the device context. The drawing styles specified in ImageList_Draw or ImageList_DrawEx also have no effect on the appearance of a nonmasked image.

Drawing the image

The following function draws an image and saves the client coordinates of the image's bounding rectangle. A subsequent function uses the bounding rectangle to determine whether the user has clicked the image.

// DrawTheImage - draws an image transparently and saves
//     the bounding rectangle of the drawn image.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window in which to draw the image.
// himl - handle to the image list that contains the image.
// cx and cy - client coordinates for the upper-left corner of the image.
//
// Global variables and constants
//     g_nImage - index of the image to draw.
//     g_rcImage - bounding rectangle of the image.
//     CX_IMAGE and CY_IMAGE - width and height of the image.
extern int g_nImage;
extern RECT g_rcImage;

#define CX_IMAGE 32
#define CY_IMAGE 32

BOOL DrawTheImage(HWND hwnd, HIMAGELIST himl, int cx, int cy)
{
    HDC hdc;

    if ((hdc = GetDC(hwnd)) == NULL)
        return FALSE;
    if (!ImageList_Draw(himl, g_nImage, hdc, cx, cy, ILD_TRANSPARENT))
        return FALSE;
    ReleaseDC(hwnd, hdc);

    SetRect(&g_rcImage, cx, cy, CX_IMAGE + cx, CY_IMAGE + cy);

    return TRUE;
}

Dragging Images

The Win32 API includes functions for dragging an image on the screen. The dragging functions move an image smoothly, in color, and without any flashing of the cursor. Both masked and unmasked images can be dragged.

The ImageList_BeginDrag function begins a drag operation. The parameters include the handle to the image list, the index of the image to drag, and the location of the hot spot within the image. The hot spot is a single pixel that the dragging functions recognize as the exact screen location of the image. Typically, an application sets the hot spot so that it coincides with the hot spot of the mouse cursor. The ImageList_DragMove function moves the image to a new location.

The ImageList_DragEnter function sets the initial position of the drag image within a window and draws the image at the position. The parameters include the handle to the window in which to draw the image and the coordinates of the initial position within the window. The coordinates are relative to the window's upper-left corner, not the client area. The same is true for all of the image dragging functions that take coordinates as parameters. This means you must compensate for the widths of window elements such as the border, title bar, and menu bar when specifying the coordinates. If you specify a NULL window handle when calling ImageList_DragEnter, the dragging functions draw the image in the device context associated with the desktop window, and the coordinates are relative to the upper-left corner of the screen.

ImageList_DragEnter locks all other updates to the given window during the drag operation. If you need to do any drawing during a drag operation, such as highlighting the target of the operation, you can temporarily hide the dragged image by using the ImageList_DragLeave function. Another method is to use the GetDCEx function with the DCX_LOCKWINDOWUPDATE value to retrieve a device context that allows you to draw. Be careful, however, not to obliterate the dragged image.

The ImageList_SetDragCursorImage function creates a new drag image by combining the given image (typically a mouse cursor image) with the current drag image. Because the dragging functions use the new image during a drag operation, you should use the ShowCursor function to hide the actual mouse cursor after calling ImageList_SetDragCursorImage. Otherwise, the system may appear to have two mouse cursors for the duration of the drag operation.

When an application calls ImageList_BeginDrag, the system creates a temporary, internal image list and then copies the specified drag image to the internal list. You can retrieve the handle to the temporary drag image list by using the ImageList_GetDragImage function. The function also retrieves the current drag position and the offset of the drag image relative to the drag position.

Beginning the drag operation

The following function is intended to be called in response to a mouse button-down message, such as WM_LBUTTONDOWN. The function determines whether the user has clicked within the bounding rectangle of the image. If the user has clicked, the function captures the mouse input, erases the image from the client area, and calculates the position for the hot spot within the image. The function sets the hot spot to coincide with the hot spot of the mouse cursor. Then the function begins the drag operation by calling ImageList_BeginDrag.

// StartDragging - begins dragging a bitmap.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window in which the bitmap is dragged.
// ptCur - coordinates of the cursor.
// himl - handle to the image list.
//
// Global variables
//     g_rcImage - bounding rectangle of the image to drag.
//     g_nImage - index of the image.
//     g_ptHotSpot - location of the image's hot spot.
//     g_cxBorder and g_cyBorder - width and height of border.
//     g_cyCaption and g_cyMenu - height of title bar and menu bar.
extern RECT g_rcImage;
extern int g_nImage;
extern POINT g_ptHotSpot;

BOOL StartDragging(HWND hwnd, POINT ptCur, HIMAGELIST himl)
{
    // Return if the cursor is not in the bounding rectangle of
    // the image.
    if (!PtInRect(&g_rcImage, ptCur))
        return FALSE;

    // Capture the mouse input.
    SetCapture(hwnd);

    // Erase the image from the client area.
    InvalidateRect(hwnd, &g_rcImage, TRUE);
    UpdateWindow(hwnd);

    // Calculate the location of the hot spot, and save it.
    g_ptHotSpot.x = ptCur.x - g_rcImage.left;
    g_ptHotSpot.y = ptCur.y - g_rcImage.top;

    // Begin the drag operation.
    if (!ImageList_BeginDrag(himl, g_nImage,
            g_ptHotSpot.x, g_ptHotSpot.y))
        return FALSE;

    // Set the initial location of the image, and make it visible.
    // Because the ImageList_DragEnter function expects coordinates to
    // be relative to the upper-left corner of the given window, the
    // width of the border, title bar, and menu bar need to be taken
    // into account.
    ImageList_DragEnter(hwnd, ptCur.x + g_cxBorder,
        ptCur.y + g_cyBorder + g_cyCaption + g_cyMenu);

    g_fDragging = TRUE;

    return TRUE;
}

Moving the image

The following function, which drags the image to a new location, is intended to be called in response to the WM_MOUSEMOVE message.

// MoveTheImage - drags an image to the specified coordinates.
// Returns TRUE if successful, or FALSE otherwise.
// ptCur - new coordinates for the image.
BOOL MoveTheImage(POINT ptCur)
{
    if (!ImageList_DragMove(ptCur.x, ptCur.y))
        return FALSE;

    return TRUE;
}

Ending the drag operation

The following function ends the drag operation and draws the image in its final location. It also releases the mouse capture.

// StopDragging - ends a drag operation and draws the image
//     at its final location.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window in which the bitmap is dragged.
// himl - handle to the image list.
// ptCur - coordinates of the cursor.
//
// Global variable
//     g_ptHotSpot - location of the image's hot spot.

extern POINT g_ptHotSpot;

BOOL StopDragging(HWND hwnd, HIMAGELIST himl, POINT ptCur)
{
    ImageList_EndDrag();
    ImageList_DragLeave(hwnd)

    g_fDragging = FALSE;

    DrawTheImage(hwnd, himl, ptCur.x - g_ptHotSpot.x,
        ptCur.y - g_ptHotSpot.y);

    ReleaseCapture();
    return TRUE;
}

Image Information

There are a number of functions that retrieve information from an image list. The ImageList_GetImageInfo function fills an IMAGEINFO structure with information about a single image, including the handles of the image and mask bitmaps, the number of color planes and bits per pixel, and the bounding rectangle of the image within the image bitmap. You can use this information to directly manipulate the bitmaps for the image. The ImageList_GetImageCount function retrieves the number of images in an image list.

Image Overlays

Every image list includes a list of indexes to use as overlays. An overlay is an image that is drawn transparently over another image. Any image currently in the image list can be used as an overlay. You can specify up to four overlays per image list. This limit has been expanded to 15 in version 4.71.

You add the index of an image to the list of overlays by using the ImageList_SetOverlayImage function, specifying the handle to the image list, the index of the existing image, and the desired overlay index. This, in effect, tells the image list that "the image at index x can be used as an overlay, and I want to refer to the overlay as overlay index y." The overlay indexes are one-based rather than zero-based because an overlay index of zero means that no overlay will be used.

You specify an overlay when drawing an image with the ImageList_Draw or ImageList_DrawEx function. The overlay is specified by performing a logical OR operation between the desired drawing flags and the result of the INDEXTOOVERLAYMASK macro. The INDEXTOOVERLAYMASK macro takes the overlay index and formats it for inclusion with the flags for these functions. This will draw the image with the specified overlay. The following example demonstrates how an overlay is added and specified when drawing the image.

ImageList_SetOverlayImage(himl, 0, 3);
ImageList_Draw(himl, 1, hdc, 0, 0, ILD_MASK | INDEXTOOVERLAYMASK(3));

This will draw image 1 and then overlay that image with image 0. Because 3 is the overlay index that you specified in the ImageList_SetOverlayImage call, 3 is placed in the INDEXTOOVERLAYMASK macro.

Image List Updates in Internet Explorer

The following features were added to the image list by Microsoft® Internet Explorer.

Copying Images
Copy or swap images within an image list using the ImageList_Copy function. This function allows you to indicate whether the source image should be copied to the destination index or the source and destination images should be swapped. Currently, this is allowed only within a single image list.
Duplicating Image Lists
Take an existing image list and duplicate all of its parameters and contents into a new image list using the ImageList_Duplicate function. The image list returned by this function is an exact duplicate of the original image list and must be destroyed separately. Changes made to one image list do not affect the other.
Dynamic Resizing of Image Lists
Modify the number of images in an image list on the fly using the ImageList_SetImageCount function. If the number of images is increased, you must use the ImageList_Replace function to place images in the added slots. If the number of images is reduced, the images beyond the new size are freed and are no longer available.
Extended Drawing of Images
You now have more control over the drawing of images with the ImageList_DrawIndirect function. This function takes an IMAGELISTDRAWPARAMS structure that specifies the details that will be used when drawing the image. With this function, you can now specify things like ROP codes when drawing.


HImageList_QueryInterface Function

This is preliminary documentation and is subject to change.

Calls IQueryInterface for a specified ImageList control.

Syntax

HRESULT HImageList_QueryInterface(
    HIMAGELIST himl,
    REFIID riid,
    void **ppv
);

Parameters

himl
Handle to an ImageList.
riid
Interface identifier of the desired interface.
ppv
Pointer to an interface reference variable.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The ability to call IQueryInterface on an ImageList allows you to access any additional interfaces the control supports internally. These currently include IUnknown, ImageList Online link, IPersistStream.

Function Information

Stock Implementation | comctl32.dll version 6.0 or later
Custom Implementation | No
Header | commctrl.h
Import library | None
Minimum operating systems | Whistler

See Also

IQueryInterface


ImageList_Add

Adds an image or images to an image list.

int ImageList_Add(
    HIMAGELIST himl,
    HBITMAP hbmImage,
    HBITMAP hbmMask
   );

Parameters

himl
Handle to the image list.
hbmImage
Handle to the bitmap that contains the image or images. The number of images is inferred from the width of the bitmap.
hbmMask
Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Values

Returns the index of the first new image if successful, or -1 otherwise.

Remarks

The ImageList_Add function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_AddMasked

Adds an image or images to an image list, generating a mask from the specified bitmap.

int ImageList_AddMasked(
    HIMAGELIST himl,
    HBITMAP hbmImage,
    COLORREF crMask
   );

Parameters

himl
Handle to the image list.
hbmImage
Handle to the bitmap that contains one or more images. The number of images is inferred from the width of the bitmap.
crMask
Color used to generate the mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to 1.

Return Values

Returns the index of the first new image if successful, or -1 otherwise.

Remarks

The ImageList_AddMasked function copies the bitmap to an internal data structure. Bitmaps with color depth greater than 8bpp are not supported. Be sure to use the DeleteObject function to delete hbmImage and crMask after the function returns.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_BeginDrag

Begins dragging an image.

BOOL ImageList_BeginDrag(
    HIMAGELIST himlTrack,
    int iTrack,
    int dxHotspot,
    int dyHotspot
   );

Parameters

himlTrack
Handle to the image list.
iTrack
Index of the image to drag.
dxHotspot and dyHotspot
Location of the drag position relative to the upper-left corner of the image.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

This function creates a temporary image list that is used for dragging. In response to subsequent WM_MOUSEMOVE messages, you can move the drag image by using the ImageList_DragMove function. To end the drag operation, you can use the ImageList_EndDrag function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Copy

Copies images within a given image list.

BOOL ImageList_Copy(
    HIMAGELIST himlDst,
    int        iDst,
    HIMAGELIST himlSrc,
    int        iSrc,
    UINT       uFlags);

Parameters

himlDst and himlSrc
Handle to an image list that is the target of the copy operation. In current versions of Windows®, both parameters must be identical.
iDst
Zero-based index of the image to be used as the destination of the copy operation.
iSrc
Zero-based index of the image to be used as the source of the copy operation.
uFlags
Bit flag value that specifies the type of copy operation to be made. This parameter can be one of the following values:
ILCF_MOVE | The source image is copied to the destination image's index. This operation results in multiple instances of a given image.
ILCF_SWAP | The source and destination images exchange positions within the image list.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Create

Creates a new image list.

HIMAGELIST ImageList_Create(
    int cx,
    int cy,
    UINT flags,
    int cInitial,
    int cGrow
   );

Parameters

cx
Width, in pixels, of each image.
cy
Height, in pixels, of each image.
flags
Set of bit flags that specify the type of image list to create. This parameter can be a combination of the following values, but it can include only one of the ILC_COLOR values.
ILC_COLOR | Use the default behavior if none of the other ILC_COLOR* flags is specified. Typically, the default is ILC_COLOR4, but for older display drivers, the default is ILC_COLORDDB.
ILC_COLOR4 | Use a 4-bit (16-color) device-independent bitmap (DIB) section as the bitmap for the image list.
ILC_COLOR8 | Use an 8-bit DIB section. The colors used for the color table are the same colors as the halftone palette.
ILC_COLOR16 | Use a 16-bit (32/64k-color) DIB section.
ILC_COLOR24 | Use a 24-bit DIB section.
ILC_COLOR32 | Use a 32-bit DIB section.
ILC_COLORDDB | Use a device-dependent bitmap.
ILC_MASK | Use a mask. The image list contains two bitmaps, one of which is a monochrome bitmap used as a mask. If this value is not included, the image list contains only one bitmap.
cInitial
Number of images that the image list initially contains.
cGrow
Number of images by which the image list can grow when the system needs to make room for new images. This parameter represents the number of new images that the resized image list can contain.

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Destroy

Destroys an image list.

BOOL ImageList_Destroy(
    HIMAGELIST himl
   );

Parameters

himl
Handle to the image list to destroy.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_DragEnter

Locks updates to the specified window during a drag operation and displays the drag image at the specified position within the window.

BOOL ImageList_DragEnter(
    HWND hwndLock,
    int x,
    int y
   );

Parameters

hwndLock
Handle to the window that owns the drag image.
x
X-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.
y
Y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_DragLeave

Unlocks the specified window and hides the drag image, allowing the window to be updated.

BOOL ImageList_DragLeave(
    HWND hwndLock
   );

Parameters

hwndLock
Handle to the window that owns the drag image.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_DragMove

Moves the image that is being dragged during a drag-and-drop operation. This function is typically called in response to a WM_MOUSEMOVE message.

BOOL ImageList_DragMove(
    int x,
    int y
   );

Parameters

x
X-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.
y
Y-coordinate at which to display the drag image. The coordinate is relative to the upper-left corner of the window, not the client area.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

To begin a drag operation, use the ImageList_BeginDrag function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_DragShowNolock

Shows or hides the image being dragged.

BOOL ImageList_DragShowNolock(
    BOOL fShow
   );

Parameters

fShow
Value specifying whether to show or hide the image being dragged. Specify TRUE to show the image or FALSE to hide the image.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Draw

Draws an image list item in the specified device context.

BOOL ImageList_Draw(
    HIMAGELIST himl,
    int i,
    HDC hdcDst,
    int x,
    int y,
    UINT fStyle
   );

Parameters

himl
Handle to the image list.
i
Index of the image to draw.
hdcDst
Handle to the destination device context.
x
X-coordinate at which to draw within the specified device context.
y
Y-coordinate at which to draw within the specified device context.
fStyle
Drawing style and, optionally, the overlay image. For information about specifying an overlay image index, see the comments section at the end of this topic. This parameter can be a combination of an overlay image index and one or more of the following values:
ILD_BLEND25,
ILD_FOCUS | Draws the image, blending 25 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_BLEND50,
ILD_SELECTED,
ILD_BLEND | Draws the image, blending 50 percent with the system highlight color. This value has no effect if the image list does not contain a mask.
ILD_MASK | Draws the mask.
ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

An overlay image is drawn transparently over the primary image specified in the i parameter. To specify an overlay image in the fStyle parameter, use the INDEXTOOVERLAYMASK macro to shift the one-based index of the overlay image. Use the OR operator to logically combine the return value of the macro with the drawing style flags specified in the fStyle parameter. You must first specify this image as an overlay image by using the ImageList_SetOverlayImage function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_DrawEx

Draws an image list item in the specified device context. The function uses the specified drawing style and blends the image with the specified color.

BOOL ImageList_DrawEx(
    HIMAGELIST himl,
    int i,
    HDC hdcDst,
    int x,
    int y,
    int dx,
    int dy,
    COLORREF rgbBk,
    COLORREF rgbFg,
    UINT fStyle
   );

Parameters

himl
Handle to the image list
i
Index of the image to draw.
hdcDst
Handle to the destination device context.
x
X-coordinate at which to draw within the specified device context.
y
Y-coordinate at which to draw within the specified device context.
dx
Width of the portion of the image to draw relative to the upper-left corner of the image. If dx and dy are zero, the function draws the entire image. The function does not ensure that the parameters are valid.
dy
Height of the portion of the image to draw, relative to the upper-left corner of the image. If dx and dy are zero, the function draws the entire image. The function does not ensure that the parameters are valid.
rgbBk
Background color of the image. This parameter can be an application-defined RGB value or one of the following values:
CLR_NONE | No background color. The image is drawn transparently.
CLR_DEFAULT | Default background color. The image is drawn using the background color of the image list.
This parameter is used only if the image list identified by himl was created with the ILC_MASK value.
rgbFg
Foreground color of the image. This parameter can be an application-defined RGB value or one of the following values:
CLR_NONE | No blend color. The image is blended with the color of the destination device context.
CLR_DEFAULT | Default foreground color. The image is drawn using the system highlight color as the foreground color.
This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 value.
fStyle
Drawing style and, optionally, the overlay image. For information about specifying an overlay image index, see the comments section at the end of this topic. This parameter can be a combination of an overlay image index and one or more of the following values:
ILD_BLEND25,
ILD_FOCUS | Draws the image, blending 25 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_BLEND50,
ILD_SELECTED,
ILD_BLEND | Draws the image, blending 50 percent with the blend color specified by rgbFG. This value has no effect if the image list does not contain a mask.
ILD_MASK | Draws the mask.
ILD_NORMAL | Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_TRANSPARENT | Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.
ILD_IMAGE | If the overlay does not require a mask to be drawn set the ILD_IMAGE flag. This causes ImageList_DrawEx to just draw the image, ignoring the mask.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

An overlay image is drawn transparently over the primary image specified in the i parameter. To specify an overlay image in the fStyle parameter, use the INDEXTOOVERLAYMASK macro to shift the one-based index of the overlay image. Use the OR operator to logically combine the return value of the macro with the drawing style flags specified in the fStyle parameter. You must first specify this image as an overlay image by using the ImageList_SetOverlayImage function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_DrawIndirect

Draws an image list image based on an IMAGELISTDRAWPARAMS structure.

BOOL ImageList_DrawIndirect(
    IMAGELISTDRAWPARAMS* pimldp);

Parameters

pimldp
Address of an IMAGELISTDRAWPARAMS structure that contains information about the draw operation.

Return Values

Returns nonzero if successful, and zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Duplicate

Creates a duplicate of an existing image list.

HIMAGELIST ImageList_Duplicate(
    HIMAGELIST himl);

Parameters

himl
Handle to the image list to be duplicated. All information contained in the original image list for normal images is copied to the new image list. Overlay images are not copied.

Return Values

Returns the handle to the new duplicate image list if successful, or NULL otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_EndDrag

Ends a drag operation.

VOID ImageList_EndDrag(VOID)

Return Values

None.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_GetBkColor

Retrieves the current background color for an image list.

COLORREF ImageList_GetBkColor(
    HIMAGELIST himl
   );

Parameters

himl
Handle to the image list.

Return Values

The return value is the background color.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_GetDragImage

Retrieves the temporary image list that is used for the drag image. The function also retrieves the current drag position and the offset of the drag image relative to the drag position.

HIMAGELIST ImageList_GetDragImage(
    POINT FAR *ppt,
    POINT FAR *pptHotspot
   );

Parameters

ppt
Address of a POINT structure that receives the current drag position. Can be NULL.
pptHotspot
Address of a POINT structure that receives the offset of the drag image relative to the drag position. Can be NULL.

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Remarks

The temporary image list is destroyed when the ImageList_EndDrag function is called. To begin a drag operation, use the ImageList_BeginDrag function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_GetIcon

Creates an icon from an image and mask in an image list.

HICON ImageList_GetIcon(
    HIMAGELIST himl,
    int i,
    UINT flags
   );

Parameters

himl
Handle to the image list.
i
Index of the image.
flags
Combination of flags that specify the drawing style. For a list of values, see the description of the ImageList_Draw function.

Return Values

Returns the handle to the icon if successful, or NULL otherwise.

Remarks

It is the responsibility of the calling application to destroy the icon returned from this function using the DestroyIcon function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_GetIconSize

Retrieves the dimensions of images in an image list. All images in an image list have the same dimensions.

BOOL ImageList_GetIconSize(
    HIMAGELIST himl,
    int FAR *cx,
    int FAR *cy
   );

Parameters

himl
Handle to the image list.
cx
Address of an integer variable that receives the width, in pixels, of each image.
cy
Address of an integer variable that receives the height, in pixels, of each image.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_GetImageCount

Retrieves the number of images in an image list.

int ImageList_GetImageCount(
    HIMAGELIST himl
   );

Parameters

himl
Handle to the image list.

Return Values

Returns the number of images.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_GetImageInfo

Retrieves information about an image.

BOOL ImageList_GetImageInfo(
    HIMAGELIST himl,
    int i,
    IMAGEINFO FAR *pImageInfo
   );

Parameters

himl
Handle to the image list.
i
Index of the image.
pImageInfo
Address of an IMAGEINFO structure that receives information about the image. The information in this structure can be used to directly manipulate the bitmaps for the image.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_LoadImage

Creates an image list from the specified bitmap, cursor, or icon resource.

HIMAGELIST ImageList_LoadImage(
    HINSTANCE hi,
    LPCTSTR lpbmp,
    int cx,
    int cGrow,
    COLORREF crMask,
    UINT uType,
    UINT uFlags
   );

Parameters

hi
Handle to the instance that contains the resource. This parameter can be NULL if you are loading an image from a file or loading an OEM resource.
lpbmp
Image to load. Unicode strings are supported on Microsoft® Windows NT® 4.0, Windows® 2000, and later, but they are not supported on Windows® 95 and Windows® 98.

If the uFlags parameter includes LR_LOADFROMFILE, lpbmp is the address of a null-terminated string that names the file containing the image to load.

If the hi parameter is non-NULL and LR_LOADFROMFILE is not specified, lpbmp is the address of a null-terminated string that contains the name of the image resource in the hi module.

If hi is NULL and LR_LOADFROMFILE is not specified, the low-order word of this parameter must be the identifier of an OEM image to load. To create this value, use the MAKEINTRESOURCE macro with one of the OEM image identifiers defined in Winuser.h. These identifiers have the following prefixes.
OBM_ for OEM bitmaps
OIC_ for OEM icons
OCR_ for OEM cursors

cx
Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified resource.
cGrow
Number of images by which the image list can grow when the system needs to make room for new images. This parameter represents the number of new images that the resized image list can contain.
crMask
Color used to generate a mask. Each pixel of this color in the specified bitmap, cursor, or icon is changed to black, and the corresponding bit in the mask is set to 1. If this parameter is the CLR_NONE value, no mask is generated. If this parameter is the CLR_DEFAULT value, the color of the pixel at the upper-left corner of the image is treated as the mask color.
uType
Flag that specifies the type of image to load. This parameter can be one of the following values.
IMAGE_BITMAP | Loads a bitmap.
IMAGE_CURSOR | Loads a cursor.
IMAGE_ICON | Loads an icon.
uFlags
Flags that specify how to load the image. This parameter can be a combination of the following values.
LR_CREATEDIBSECTION | Causes the function to return a DIB section bitmap rather than a compatible bitmap when the uType parameter specifies IMAGE_BITMAP. LR_CREATEDIBSECTION is useful for loading a bitmap without mapping it to the colors of the display device.
LR_DEFAULTCOLOR | Uses the color format of the display.
LR_LOADDEFAULTSIZE | Uses the width or height specified by the system metric values for cursors and icons if the cx parameter is set to zero. If this value is not specified and cx is set to zero, the function sets the size to the one specified in the resource. If the resource contains multiple images, the function sets the size to that of the first image.
LR_LOADFROMFILE | Loads the image from the file specified by the lpbmp parameter.
LR_LOADMAP3DCOLORS Searches the color table for the image and replaces the following shades of gray with the corresponding three-dimensional color:

Dk Gray: RGB(128, 128, 128)COLOR_3DSHADOW

Gray: RGB(192, 192, 192)COLOR_3DFACE

Lt Gray: RGB(223, 223, 223)COLOR_3DLIGHT

For more information, see the Remarks section.

LR_LOADTRANSPARENT | Retrieves the color value of the first pixel in the image and replaces the corresponding entry in the color table with the default window color (the COLOR_WINDOW display color). All pixels in the image that use that color become the default window value color. This value applies only to images that have a corresponding color table. For more information, see the Remarks section.
LR_MONOCHROME | Loads the image in black and white.
LR_SHARED | Shares the image handle if the image is loaded multiple times. Do not use this value for images that have nontraditional sizes that might change after loading or for images that are loaded from a file.

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Remarks

LR_LOADTRANSPARENT does not load the image transparently. It creates an opaque image list that only appears transparent because all the background pixels have been changed to COLOR_WINDOW. If the images are drawn over a background that is not the color COLOR_WINDOW, the image does not draw properly. Also, LR_LOADTRANSPARENT and LR_LOADMAP3DCOLORS use the system colors that were in effect at the time that ImageList_LoadImage was called. If the system colors subsequently change, the application must reload the image to remap the colors.

See Also

LoadImage

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h
Import Library: comctl32.lib


ImageList_Merge

Creates a new image by combining two existing images. The function also creates a new image list in which to store the image.

HIMAGELIST ImageList_Merge(
    HIMAGELIST himl1,
    int i1,
    HIMAGELIST himl2,
    int i2,
    int dx,
    int dy
   );

Parameters

himl1
Handle to the first image list.
i1
Index of the first existing image.
himl2
Handle to the second image list.
i2
Index of the second existing image.
dx and dy
Offset of the second image relative to the first image.

Return Values

Returns the handle to the new image list if successful, or NULL otherwise.

Remarks

The new image consists of the second existing image drawn transparently over the first. The mask for the new image is the result of performing a logical OR operation on the masks of the two existing images.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Read

Reads an image list from a stream.

HIMAGELIST ImageList_Read(
    LPSTREAM pstm
   );

Parameters

pstm
Address of the stream.

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Remove

Removes an image from an image list.

BOOL ImageList_Remove(
    HIMAGELIST himl,
    int i
   );

Parameters

himl
Handle to the image list.
i
Index of the image to remove. If this parameter is -1, the function removes all images.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

When an image is removed, the indexes of the remaining images are adjusted so that the image indexes always range from zero to one less than the number of images in the image list. For example, if you remove the image at index 0, then image 1 becomes image 0, image 2 becomes image 1, and so on.

See Also

ImageList_RemoveAll

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Replace

Replaces an image in an image list with a new image.

BOOL ImageList_Replace(
    HIMAGELIST himl,
    int i,
    HBITMAP hbmImage,
    HBITMAP hbmMask
   );

Parameters

himl
Handle to the image list.
i
Index of the image to replace.
hbmImage
Handle to the bitmap that contains the image.
hbmMask
Handle to the bitmap that contains the mask. If no mask is used with the image list, this parameter is ignored.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

The ImageList_Replace function copies the bitmap to an internal data structure. Be sure to use the DeleteObject function to delete hbmImage and hbmMask after the function returns.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_ReplaceIcon

Replaces an image with an icon or cursor.

int ImageList_ReplaceIcon(
    HIMAGELIST himl,
    int i,
    HICON hicon
   );

Parameters

himl
Handle to the image list.
i
Index of the image to replace. If i is -1, the function appends the image to the end of the list.
hicon
Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Values

Returns the index of the image if successful, or -1 otherwise.

Remarks

Because the system does not save hicon, you can destroy it after the function returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_SetBkColor

Sets the background color for an image list. This function only works if you add an icon or use ImageList_AddMasked with a black and white bitmap. Without a mask, the entire image is drawn; hence the background color is not visible.

COLORREF ImageList_SetBkColor(
    HIMAGELIST himl,
    COLORREF clrBk
   );

Parameters

himl
Handle to the image list.
clrBk
Background color to set. This parameter can be the CLR_NONE value; in that case, images are drawn transparently using the mask.

Return Values

Returns the previous background color if successful, or CLR_NONE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_SetDragCursorImage

Creates a new drag image by combining the specified image (typically a mouse cursor image) with the current drag image.

BOOL ImageList_SetDragCursorImage(
    HIMAGELIST himlDrag,
    int iDrag,
    int dxHotspot,
    int dyHotspot
   );

Parameters

himlDrag
Handle to the image list that contains the new image to combine with the drag image.
iDrag
Index of the new image to combine with the drag image.
dxHotspot and dyHotspot
Position of the hot spot within the new image.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_SetIconSize

Sets the dimensions of images in an image list and removes all images from the list.

BOOL ImageList_SetIconSize(
    HIMAGELIST himl,
    int cx,
    int cy
   );

Parameters

himl
Handle to the image list.
cx
Width, in pixels, of the images in the image list. All images in an image list have the same dimensions.
cy
Height, in pixels, of the images in the image list. All images in an image list have the same dimensions.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_SetImageCount

Resizes an existing image list.

BOOL ImageList_SetImageCount(
    HIMAGELIST himl,
    UINT       uNewCount);

Parameters

himl
Handle to the image list that will be resized.
uNewCount
Value specifying the new size of the image list.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

If an application expands an image list with this function, it must add new images by using the ImageList_Replace function. If your application does not add valid images at the new indexes, draw operations that use the new indexes will be unpredictable.

If you decrease the size of an image list by using this function, the truncated images are freed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_SetOverlayImage

Adds a specified image to the list of images to be used as overlay masks. An image list can have up to four overlay masks in version 4.70 and earlier and up to 15 in version 4.71. The function assigns an overlay mask index to the specified image.

BOOL ImageList_SetOverlayImage(
    HIMAGELIST himl,
    int iImage,
    int iOverlay
   );

Parameters

himl
Handle to the image list.
iImage
Zero-based index of an image in the himl image list. This index identifies the image to use as an overlay mask.
iOverlay
One-based index of the overlay mask.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

An overlay mask is an image drawn transparently over another image. To draw an overlay mask over an image, call the ImageList_Draw or ImageList_DrawEx function. The fStyle parameter of these functions can use the INDEXTOOVERLAYMASK macro to specify an overlay mask index.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_Write

Writes an image list to a stream.

BOOL ImageList_Write(
    HIMAGELIST himl,
    LPSTREAM pstm
   );

Parameters

himl
Handle to the image list.
pstm
Address of the stream.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


ImageList_AddIcon

Adds an icon or cursor to an image list. ImageList_AddIcon calls the ImageList_ReplaceIcon function.

int ImageList_AddIcon(
    HIMAGELIST himl,
    HICON hicon
   );

Parameters

himl
Handle to the image list. If this parameter identifies a masked image list, the macro copies both the image and mask bitmaps of the icon or cursor. If this parameter identifies a nonmasked image list, the macro copies only the image bitmap.
hicon
Handle to the icon or cursor that contains the bitmap and mask for the new image.

Return Values

Returns the index of the new image if successful, or -1 otherwise.

Remarks

Because the system does not save hicon, you can destroy it after the macro returns if the icon or cursor was created by the CreateIcon function. You do not need to destroy hicon if it was loaded by the LoadIcon function; the system automatically frees an icon resource when it is no longer needed.

The ImageList_AddIcon macro is defined as follows:

#define  ImageList_AddIcon(himl, hicon) ImageList_ReplaceIcon(himl, -1, hicon)

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ImageList_ExtractIcon

Calls the ImageList_GetIcon function to create an icon or cursor based on an image and mask in an image list.

HICON ImageList_ExtractIcon(
    HINSTANCE hi,
    HIMAGELIST himl,
    int i
   );

Parameters

hi
This parameter is not used and should always be zero.
himl
Handle to the image list.
i
Index of the image.

Return Values

Returns the handle of the icon or cursor if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ImageList_LoadBitmap

Calls the ImageList_LoadImage function to create an image list from the specified bitmap resource.

HIMAGELIST ImageList_LoadBitmap(
    HINSTANCE hi,
    LPCTSTR lpbmp,
    int cx,
    int cGrow,
    COLORREF crMask
   );

Parameters

hi
Handle to the instance that contains the bitmap resource. This parameter is NULL if you are loading an OEM bitmap.
lpbmp
Identifies the image to load.
If the hi parameter is non-NULL, lpszName is the address of a null-terminated string that contains the name of the image resource in the hi module.
If hi is NULL, the low-order word of this parameter must be the identifier of an OEM bitmap to load. To create this value, use the MAKEINTRESOURCE macro with one of the OEM bitmap identifiers defined in WINUSER.H. These identifiers have the OBM_ prefix.
cx
Width of each image. The height of each image and the initial number of images are inferred by the dimensions of the specified bitmap.
cGrow
Number of images by which the image list can grow when the system needs to make room for new images. This parameter represents the number of new images that the resized image list can contain.
crMask
Color used to generate a mask. Each pixel of this color in the specified bitmap is changed to black, and the corresponding bit in the mask is set to 1. If this parameter is the CLR_NONE value, no mask is generated.

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ImageList_RemoveAll

Calls the ImageList_Remove function to remove all of the images from an image list.

BOOL ImageList_Remove(
    HIMAGELIST himl
   );

Parameters

himl
Handle to the image list.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


INDEXTOOVERLAYMASK

Prepares the index of an overlay mask so that the ImageList_Draw function can use it.

UINT INDEXTOOVERLAYMASK(
    UINT iOverlay
   );

Parameters

iOverlay
Index of an overlay mask.

The INDEXTOOVERLAYMASK macro is defined as follows:

#define INDEXTOOVERLAYMASK(i) ((i) << 8)

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


IMAGEINFO

Contains information about an image in an image list. This structure is used with the ImageList_GetImageInfo function.

typedef struct _IMAGEINFO {
    HBITMAP hbmImage;
    HBITMAP hbmMask;
    int     Unused1;
    int     Unused2;
    RECT    rcImage;
} IMAGEINFO, FAR *LPIMAGEINFO;

Members

hbmImage
Handle to the bitmap that contains the images.
hbmMask
Handle to a monochrome bitmap that contains the masks for the images. If the image list does not contain a mask, this member is NULL.
Unused1
Not used. This member should always be zero.
Unused2
Not used. This member should always be zero.
rcImage
Bounding rectangle of the specified image within the bitmap specified by hbmImage.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


IMAGELISTDRAWPARAMS

Contains information about an image list draw operation and is used with the ImageList_DrawIndirect function.

typedef struct _IMAGELISTDRAWPARAMS {
    DWORD       cbSize;
    HIMAGELIST  himl;
    int         i;
    HDC         hdcDst;
    int         x;
    int         y;
    int         cx;
    int         cy;
    int         xBitmap;
    int         yBitmap;
    COLORREF    rgbBk;
    COLORREF    rgbFg;
    UINT        fStyle;
    DWORD       dwRop;
} IMAGELISTDRAWPARAMS, FAR * LPIMAGELISTDRAWPARAMS;

Members

cbSize
Size of this structure, in bytes.
himl
Handle to the image list that contains the image to be drawn.
i
Zero-based index of the image to be drawn.
hdcDst
Handle to the destination device context.
x and y
Coordinates where the image will be drawn.
cx and cy
Values that specify the number of pixels to be drawn, relative to the upper-left corner of the drawing operation as specified by xBitmap and yBitmap. If cx and cy are zero, ImageList_DrawIndirect draws the entire valid section. The function does not ensure that the parameters are valid.
xBitmap and yBitmap
Coordinates that specify the upper-left corner of the drawing operation with respect to the image itself. Pixels of the image that are to the left of xBitmap and above yBitmap are not drawn.
rgbBk
Image background color. This parameter can be an application-defined RGB value or one of the following values:
CLR_DEFAULT | Default background color. The image is drawn using the image list background color.
CLR_NONE | No background color. The image is drawn transparently.

This parameter is used only if the image list identified by himl was created with the ILC_MASK value.

rgbFg
Image foreground color. This parameter can be an application-defined RGB value or one of the following values:
CLR_DEFAULT | Default foreground color. The image is drawn using the system highlight color as the foreground color.
CLR_NONE | No blend color. The image is blended with the color of the destination device context.

This parameter is used only if fStyle includes the ILD_BLEND25 or ILD_BLEND50 flag.

fStyle
Flag specifying the drawing style and, optionally, the overlay image. See the comments section at the end of this topic for information on the overlay image. This parameter can be one or more of the following values:
ILD_BLEND25
Draws the image, blending 25 percent with the blend color specified by rgbFg. This value has no effect if the image list does not contain a mask.
ILD_FOCUS
Same as ILD_BLEND25.
ILD_BLEND50
Draws the image, blending 50 percent with the blend color specified by rgbFg. This value has no effect if the image list does not contain a mask.
ILD_SELECTED
Same as ILD_BLEND50.
ILD_BLEND
Same as ILD_BLEND50.
ILD_IMAGE
If the overlay does not require a mask to be drawn, set the ILD_IMAGE flag.
ILD_MASK
Draws the mask.
ILD_NORMAL
Draws the image using the background color for the image list. If the background color is the CLR_NONE value, the image is drawn transparently using the mask.
ILD_ROP
Draws the image using the raster operation code specified by the dwRop member.
ILD_TRANSPARENT
Draws the image transparently using the mask, regardless of the background color. This value has no effect if the image list does not contain a mask.
dwRop
Value specifying a raster operation code. These codes define how the color data for the source rectangle will be combined with the color data for the destination rectangle to achieve the final color. This member is ignored if the fStyle member does not include the ILD_ROP flag.

Some common raster operation codes include:
BLACKNESS | Fills the destination rectangle using the color associated with index zero in the physical palette. (This color is black for the default physical palette.)
DSTINVERT | Inverts the destination rectangle.
MERGECOPY | Merges the source rectangle colors with the specified pattern by using the Boolean AND operator.
MERGEPAINT | Merges the inverted source rectangle colors with the destination rectangle colors by using the Boolean OR operator.
NOTSRCCOPY | Copies the inverted source rectangle to the destination.
NOTSRCERASE | Combines the source and destination rectangle colors by using the Boolean OR operator. Inverts the resultant color.
PATCOPY | Copies the specified pattern into the destination bitmap.
PATINVERT | Combines the specified pattern colors with the destination rectangle colors by using the Boolean XOR operator.
PATPAINT | Combines the pattern colors with the inverted source rectangle colors by using the Boolean OR operator. Combines the result with the destination rectangle colors by using the Boolean OR operator.
SRCAND | Combines the source and destination rectangle colors by using the Boolean AND operator.
SRCCOPY | Copies the source rectangle directly to the destination rectangle.
SRCERASE | Combines the destination rectangle's inverted colors with the source rectangle colors by using the Boolean AND operator.
SRCINVERT | Combines the source and destination rectangle colors by using the Boolean XOR operator.
SRCPAINT | Combines the source and destination rectangle colors by using the Boolean OR operator.
WHITENESS | Fills the destination rectangle using the color associated with index one in the physical palette. (This color is white for the default physical palette.)

Remarks

An overlay image is an image that is drawn on top of the primary image specified in the i member of this structure. To specify an overlay image, logically OR the fStyle member with the INDEXTOOVERLAYMASK macro, passing the one-based index of the overlay image in the macro. This image must have been previously specified as an overlay image using the ImageList_SetOverlayImage API.

To extract the overlay image from the fStyle member, logically AND fStyle with the ILD_OVERLAYMASK value.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


IP Address Controls

An IP address control allows the user to enter an IP address in an easily understood format. This control also allows the application to obtain the address in numeric form rather than in text form.

  • About IP Address Controls
  • Using IP Address Controls
  • IP Address Control Reference

About IP Address Controls

Microsoft® Internet Explorer Version 4.0 introduces the IP address control, a new control similar to an edit control that allows the user to enter a numeric address in Internet protocol (IP) format. This format consists of four three-digit fields. Each field is treated individually; the field numbers are zero-based and proceed from left to right as shown in this figure.

The four three-digit fields of an IP address control

The control allows only numeric text to be entered in each of the fields. Once three digits have been entered in a given field, keyboard focus is automatically moved to the next field. If filling the entire field is not required by the application, the user can enter fewer than three digits. For example, if the field should only contain 21, typing 21 and pressing the RIGHT ARROW key will take the user to the next field.

The default range for each field is 0 to 255, but the application can set the range to any values between those limits with the IPM_SETRANGE message.

Note The IP address control is implemented in version 4.71 and later of Comctl32.dll.

Using IP Address Controls

This section describes how to implement an IP address control in your application.

Initializing an IP Address Control

To use an IP address control, call InitCommonControlsEx with the ICC_INTERNET_CLASSES flag set in the dwICC member of the INITCOMMONCONTROLSEX structure.

Creating an IP Address Control

Use the CreateWindow or the CreateWindowEx API to create an IP address control. The class name for the control is WC_IPADDRESS, which is defined in Commctrl.h. No IP address control-specific styles exist; however, because this is a child control, use the WS_CHILD style as a minimum.

Is an IP Address Control an Edit Control?

An IP address control is not an edit control and it will not respond to EM_ messages. It will, however, send the owner window the following edit control notifications through the WM_COMMAND message. Note that the IP address control will also send private IPN_ notifications through the WM_NOTIFY message.

Notification | Reason for notification
EN_SETFOCUS | Sent when the IP address control gains the keyboard focus.
EN_KILLFOCUS | Sent when the IP address control loses the keyboard focus.
EN_CHANGE | Sent when any field in the IP address control changes. Like the EN_CHANGE notification from a standard edit control, this notification is received after the screen has been updated.


IPM_CLEARADDRESS

Clears the contents of the IP address control.

IPM_CLEARADDRESS
    wParam = 0;
    lParam = 0;

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


IPM_GETADDRESS

Retrieves the address values for all four fields in the IP address control.

IPM_GETADDRESS
    wParam = 0;
    lParam = (LPARAM)(LPDWORD)pdwAddr;

Parameters

pdwAddr
Address of a DWORD value that receives the address. The field 3 value will be contained in bits 0 through 7. The field 2 value will be contained in bits 8 through 15. The field 1 value will be contained in bits 16 through 23. The field 0 value will be contained in bits 24 through 31. The FIRST_IPADDRESS, SECOND_IPADDRESS, THIRD_IPADDRESS, and FOURTH_IPADDRESS macros can also be used to extract the address information. Zero will be returned as the address for any blank fields.

Return Values

Returns the number of nonblank fields.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


IPM_ISBLANK

Determines if all fields in the IP address control are blank.

IPM_ISBLANK
    wParam = 0;
    lParam = 0;

Return Values

Returns nonzero if all fields are blank, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


IPM_SETADDRESS

Sets the address values for all four fields in the IP address control.

IPM_SETADDRESS
    wParam = 0;
    lParam = (LPARAM)(DWORD)dwAddr;

Parameters

dwAddr
DWORD value that contains the new address. The field 3 value is contained in bits 0 through 7. The field 2 value is contained in bits 8 through 15. The field 1 value is contained in bits 16 through 23. The field 0 value is contained in bits 24 through 31. The MAKEIPADDRESS macro can also be used to create the address information.

Return Values

The return value is not used.

Remarks

This message does not generate an IPN_FIELDCHANGED notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


IPM_SETFOCUS

Sets the keyboard focus to the specified field in the IP address control. All of the text in that field will be selected.

IPM_SETFOCUS
    wParam = (WPARAM)nField;
    lParam = 0;

Parameters

nField
Zero-based field index to which the focus should be set. If this value is greater than the number of fields, focus is set to the first blank field. If all fields are nonblank, focus is set to the first field.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


IPM_SETRANGE

Sets the valid range for the specified field in the IP address control.

IPM_SETRANGE
    wParam = (WPARAM)nField;
    lParam = (LPARAM)(WORD)wRange;

Parameters

nField
Zero-based field index to which the range will be applied.
wRange
WORD value that contains the lower limit of the range in the low-order byte and the upper limit in the high-order byte. Both of these values are inclusive. The MAKEIPRANGE macro can also be used to create the range.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

If the user enters a value in the field that is outside of this range, the control will send the IPN_FIELDCHANGED notification with the entered value. If the value is still outside of the range after sending the notification, the control will attempt to change the entered value to the closest range limit.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


IPN_FIELDCHANGED

Sent when the user changes a field in the control or moves from one field to another. This notification message is sent in the form of a WM_NOTIFY message.

IPN_FIELDCHANGED
    lpnmipa = (LPNMIPADDRESS) lParam;

Parameters

lpnmipa
Address of an NMIPADDRESS structure that contains information about the changed address. The iValue member of this structure will contain the entered value, even if it is out of the range of the field. You can modify this member to any value that is within the range for the field in response to this notification.

Return Values

The return value is ignored.

Remarks

This notification is not sent in response to a IPM_SETADDRESS message.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


FIRST_IPADDRESS

Extracts the field 0 value from a packed IP address retrieved with the IPM_GETADDRESS message.

BYTE FIRST_IPADDRESS(
    LPARAM lParam
);

Parameters

lParam
Packed IP address value.

Return Values

Returns a BYTE value that contains the field 0 value.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


FOURTH_IPADDRESS

Extracts the field 3 value from a packed IP address retrieved with the IPM_GETADDRESS message.

BYTE FOURTH_IPADDRESS(
    LPARAM lParam
);

Parameters

lParam
Packed IP address value.

Return Values

Returns a BYTE value that contains the field 3 value.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


MAKEIPADDRESS

Packs four byte values into a single LPARAM suitable for use with the IPM_SETADDRESS message.

LPARAM MAKEIPADDRESS(
    BYTE b0,
    BYTE b1,
    BYTE b2,
    BYTE b3
);

Parameters

b0
Field 0 address.
b1
Field 1 address.
b2
Field 2 address.
b3
Field 3 address.

Return Values

Returns an LPARAM value that contains the address.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


MAKEIPRANGE

Packs two byte values into a single LPARAM suitable for use with the IPM_SETRANGE message.

LPARAM MAKEIPRANGE(
    BYTE low,
    BYTE high
);

Parameters

low
Lower limit of the range.
high
Upper limit of the range.

Return Values

Returns an LPARAM value that contains the range.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SECOND_IPADDRESS

Extracts the field 1 value from a packed IP address retrieved with the IPM_GETADDRESS message.

BYTE SECOND_IPADDRESS(
    LPARAM lParam
);

Parameters

lParam
Packed IP address value.

Return Values

Returns a BYTE value that contains the field 1 value.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


THIRD_IPADDRESS

Extracts the field 2 value from a packed IP address retrieved with the IPM_GETADDRESS message.

BYTE THIRD_IPADDRESS(
    LPARAM lParam
);

Parameters

lParam
Packed IP address value.

Return Values

Returns a BYTE value that contains the field 2 value.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMIPADDRESS

Contains information for the IPN_FIELDCHANGED notification message.

typedef struct tagNMIPADDRESS{
    NMHDR hdr;
    int iField;
    int iValue;
} NMIPADDRESS, *LPNMIPADDRESS;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iField
Zero-based number of the field that was changed.
iValue
New value of the field specified in the iField member. While processing the IPN_FIELDCHANGED notification, this member can be set to any value that is within the range of the field and the control will place this new value in the field.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


List-View Controls

A list-view control is a window that displays a collection of items; each item consists of an icon and a label. List-view controls provide several ways to arrange and display items. For example, additional information about each item can be displayed in columns to the right of the icon and label. The following illustration shows a window with a list-view control in icon view.

Window with a list-view control.

This section discusses the following topics:

  • List-View Controls
  • Using List-View Controls
  • List-View Control Reference
  • Default List-View Message Processing


List-View Message Processing

Default List-View Message Processing

This section lists the window message processing performed by a list-view control.

Message | Processing performed
WM_CHAR Searches for a list-view item that begins with the specified character and, if the item is found, selects and sets the focus to the item.

Multiple characters received within a time-out interval, currently fixed at one second, are concatenated, and the list-view control searches for an item that begins with the resulting string.

WM_COMMAND | Processes the EN_UPDATE and EN_KILLFOCUS notification messages and forwards all other edit control notifications to the parent window.
WM_CREATE | Performs initialization additional to WM_NCCREATE. If the LVS_SHAREIMAGELISTS window style is not specified, the list-view control creates the icon and small icon image lists at this point.
WM_DESTROY | Frees resources allocated during WM_CREATE.
WM_ERASEBKGND | Erases the window background using the current background color for the list-view control. If the background color is the CLR_NONE value, the list-view control forwards the message to the parent window.
WM_GETDLGCODE | Returns a combination of the DLGC_WANTTAB and DLGC_WANTARROWS values.
WM_GETFONT | Returns the handle to the current label font.
WM_HSCROLL | Scrolls the list-view control horizontally.
WM_KEYDOWN | Processes the SPACEBAR, ENTER, and arrow keys and sends an LVN_KEYDOWN notification message to the parent window.
WM_KILLFOCUS | Repaints the focused list item, if any, and sends an NM_KILLFOCUS notification message to the parent window.
WM_LBUTTONDBLCLK | Sends the parent window an NM_DBLCLK notification message.
WM_LBUTTONDOWN Processed in different ways depending on whether a click or drag operation is being initiated. To determine which operation is involved, the list-view control enters a modal message loop until either the button is released or the mouse is moved.

In the case of a click, the list-view control might change which item has the focus and which items are selected, taking into account the cursor position, the state of the SHIFT and CTRL keys, and so on. Then the list-view control sends its parent window an NM_CLICK notification message.

If dragging begins over an item, the list-view control selects and sets the focus to the item. Then it sends an LVN_BEGINDRAG notification message to the parent window. The parent window is responsible for actually carrying out the drag operation.

If dragging begins over the window background, the list-view control enters another modal message loop, enabling the user to form a rectangle by dragging the mouse. Items within the rectangle are selected.

WM_NCCREATE | Allocates and initializes an internal data structure and then calls the DefWindowProc function.
WM_NCDESTROY | Frees resources allocated by the list-view control. Unless the LVS_SHAREIMAGELISTS style is used, this includes deleting the full-sized and small image lists.
WM_NOTIFY | Processes header control notification messages.
WM_PAINT | Displays any items in the update region. For callback items, the control first sends an LVN_GETDISPINFO notification message to the owner window to request display information. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_RBUTTONDOWN | Processed the same way as the WM_LBUTTONDOWN message, except that the control sends an NM_RCLICK notification message (instead of NM_CLICK) and an LVN_BEGINRDRAG notification message (instead of LVN_BEGINDRAG). Note that the control processes the corresponding WM_RBUTTONUP message, and does not dispatch it. Applications thus cannot see this message, even by subclassing the control.
WM_SETFOCUS | Repaints the focused list item, if any, and sends an NM_SETFOCUS notification message to the parent window.
WM_SETFONT | Saves the specified font handle, forwards the message to the header window, if any, and repaints using the new font.
WM_SETREDRAW | Turns redrawing on or off.
WM_TIMER | Begins editing of an item label. If the user clicks the label of the focused item, the list-view control sets a timer instead of entering edit mode immediately. The timer makes it possible for the list-view control to not enter edit mode if the user double-clicks the label.
WM_VSCROLL | Scrolls the list-view control vertically.
WM_WINDOWPOSCHANGED | Updates the window scroll bars. If the current view is icon or small icon view, and the LVS_AUTOARRANGE style is specified, the list-view control will also arrange the list items.
WM_WININICHANGE | Processes changes to system metrics.


What's New in List-View Controls

This is preliminary documentation and is subject to change.

The list-view control in the updated common controls delivered in Whistler provides new features that enable you to present useful visual information to your users.

  • The new grouping features of the list-view control can make it easier for users to scan large lists for relevant information.
  • The new tile view provides a compact yet informative display method for directory, file, and other information.
  • Insertion marks enable users to better visually follow the changing location of files during and after drag-and-drop operations.

Taken together, the new features of the list-view control enable you to provide a rich and intuitive interface for your applications.

In addition, the newest version of the list-view control is aware of the current system theme. For more information on theming, see Themes.

This article contains the following sections.

  • Tile View
  • Group View
  • Insertion Marks
  • Additions to List-View for Whistler

Tile View

The new tile-view features of the list-view control enable you to provide an even visual balance between graphical and textual information. The textual information provided for an item in tile view is taken from the columns defined for report view. Tile view can be used in combination with either the grouping or insertion mark features new to the list-view control. The tile view uses a 32 x 32 icon and several lines of text, as illustrated below.

The tile-view APIs enable you to specify which column fields to display for each item in tile view, and to collectively control the size and appearance of all items within a tile-view window. For clarity, the first line of text in a tile is always the item's name.

Group View

The grouping features of the list-view control, new for Whistler, enable you to visually group logically related sets of items. These groups are separated on the screen by a horizontal group header that contains the title and the number of items in the group. Some grouped items are illustrated below.

The grouping API enables group and group-element management by providing messages that add items to groups, add groups to views, sort group items, and query groups for item size and other information.

Insertion Marks

Insertion marks are used to show users where dragged items will be placed. Insertion marks are currently displayed when the user drags an item into the Start menu or Quick Launch bar. The insertion mark has been introduced for lists that are set to be autoarranged. When a user drags an item to a point between two other items, the insertion mark shows the user the item's expected new location.

The insertion mark API elements enable placement of insertion marks by providing messages and flags that perform hit detection, that specify the location and appearance of the insertion mark by item, and that query for information about the current size and appearance of the insertion mark.

Additions to List-View for Whistler

Tile View Messages

  • LVM_GETTILEINFO
  • LVM_GETTILEVIEWINFO
  • LVM_SETTILEINFO
  • LVM_SETTILEVIEWINFO

Group-View Messages

  • LVM_ENABLEGROUPVIEW
  • LVM_GETGROUPINFO
  • LVM_GETGROUPMETRICS
  • LVM_HASGROUP
  • LVM_INSERTGROUP
  • LVM_INSERTGROUPSORTED
  • LVM_REMOVEALLGROUPS
  • LVM_REMOVEGROUP
  • LVM_SETGROUPINFO
  • LVM_SORTGROUPS

Insertion-Mark Messages

  • LVM_GETINSERTMARK
  • LVM_GETINSERTMARKCOLOR
  • LVM_GETINSERTMARKRECT
  • LVM_INSERTMARKHITTEST
  • LVM_SETINSERTMARK
  • LVM_SETINSERTMARKCOLOR


List-View Controls

List-view controls are used to maintain and display collections of items with their associated icons. The following topics discuss list-view control programming considerations.

  • List-View Creation
  • List-View Styles and Views
  • Extended List-View Styles
  • Virtual List-View Style
  • List-View Working Areas
  • List-View Image Lists
  • List-View Items and Subitems
  • List-View Item States
  • Callback Items and the Callback Mask
  • List-View Columns
  • Arranging, Sorting, and Finding Items
  • List-View Item Position
  • List-View Scroll Position
  • List-View Label Editing
  • List-View Colors

List-View Creation

To create a list-view control, call the CreateWindow or CreateWindowEx function and specify the WC_LISTVIEW window class. This window class is registered when the common controls dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, use the InitCommonControls or InitCommonControlsEx function. Because list-view controls display both icons and text, as part of the creation process you must load the bitmaps and insert the text items.

List-View Styles and Views

List-view controls display items in four different views. The current view is specified by the control's window style. Additional window styles specify the alignment of items and control-specific functionality. The following table describes the four views.

View name | Description
Icon view | Specified by the LVS_ICON window style. Each item appears as a full-sized icon with a label below it. The user can drag the items to any location in the list-view window.
Small icon view | Specified by the LVS_SMALLICON window style. Each item appears as a small icon with the label to the right of it. The user can drag the items to any location.
List view | Specified by the LVS_LIST window style. Each item appears as a small icon with a label to the right of it. Items are arranged in columns and cannot be dragged to any arbitrary location by the user.
Report view | Specified by the LVS_REPORT window style. Each item appears on its own line, with information arranged in columns. The leftmost column is always left justified and contains the small icon and label. Subsequent columns contain subitems as specified by the application. Unless the LVS_NOCOLUMNHEADER window style is also specified, each column has a header.

You can change the view type after a list-view control is created. To retrieve and change the window style, use the GetWindowLong and SetWindowLong functions. To determine the window styles of the current view, use the LVS_TYPEMASK value.

You can control the way items are arranged in icon or small icon view by specifying either the LVS_ALIGNTOP (default) or LVS_ALIGNLEFT window style. You can change the alignment after a list-view control is created. To determine the current alignment, use the LVS_ALIGNMASK value.

Additional window styles provide other options, such as whether a user can edit labels or select more than one item at a time. For a complete list, see List-View Window Styles.

Extended List-View Styles

The extended list-view control styles provide options such as check boxes, flat scroll bars, gridlines, and hot-tracking. For a complete list, see Extended List-View Styles. Extended list-view styles are not accessed in the same manner as standard window styles. You do not use the GetWindowLong and SetWindowLong functions to make extended style changes.

There are two messages that set and retrieve extended style information: LVM_SETEXTENDEDLISTVIEWSTYLE and LVM_GETEXTENDEDLISTVIEWSTYLE. Instead of sending the messages explicitly, you can use the corresponding macros: ListView_SetExtendedListViewStyle, ListView_SetExtendedListViewStyleEx, and ListView_GetExtendedListViewStyle.

Virtual List-View Style

A virtual list view is a list-view control that has the LVS_OWNERDATA style. This style enables the control to handle millions of items. This is possible because the overhead of managing item data is placed on the owner. This allows the virtual list-view control to lend itself for use with large databases of information, where specific methods of accessing data are already in place.

A virtual list-view control maintains very little item information itself. Except for the item selection and focus information, all item information must be managed by the owner of the control. All other item information is requested from the owner by using LVN_GETDISPINFO notification messages.

Because this type of list control is intended for large data sets, it is recommended that you cache requested item data to improve retrieval performance. The list view provides a cache-hinting mechanism to assist in optimizing the cache. The hint is implemented in the form of an LVN_ODCACHEHINT notification message.

Creating a Virtual List-View Control

Virtual list-view controls are created using the CreateWindow or CreateWindowEx function, specifying the LVS_OWNERDATA window style as part of the dwStyle function parameter.

The LVS_OWNERDATA style can be used in combination with most other window styles, except the LVS_SORTASCENDING or LVS_SORTDESCENDING style. All virtual list-view controls default to the LVS_AUTOARRANGE style.

Note Dynamically switching to and from the LVS_OWNERDATA style is not supported.

Compatibility Issues

All four of the list-view styles—icon, small icon, list, and report view—support the LVS_OWNERDATA style. List-view controls that have the LVS_OWNERDATA style do not store any item-specific information. Therefore, the only valid item state flags that can apply to an item are LVIS_SELECTED and LVIS_FOCUSED. No other state information is stored. In particular, the list-view control does not maintain state or overlay images for each item. However, you can have the list-view control query your application for these images by sending it an LVM_SETCALLBACKMASK message.

Most list-view control messages are fully supported. However, some messages have limitations or are unsupported when the LVS_OWNERDATA style is used. The following table summarizes the affected messages. Messages and the associated macros not listed here are supported.

Message | Limitation
LVM_ARRANGE | Does not support the LVA_SNAPTOGRID style.
LVM_DELETEALLITEMS | Sets the item count to zero and clears all internal selection variables, but it does not actually delete any items. A notification callback will be made.
LVM_DELETEITEM | Is supported for selection integrity only and does not actually delete an item.
LVM_GETITEMSTATE | Returns only focus and selection states (those states stored by the list-view control).
LVM_GETNEXTITEM | Does not support the list-view search criteria LVNI_CUT, LVNI_HIDDEN, or LVNI_DROPHILITED. All other criteria are supported.
LVM_GETWORKAREAS | Is not supported.
LVM_INSERTITEM | Is supported for selection integrity only.
LVM_SETITEM | Is not supported. To set the item state, use the LVM_SETITEMSTATE message.
LVM_SETITEMCOUNT | Sets the number of items currently in the list. The owner must be prepared to supply data for any item up to the maximum set using this message, as requested by the list control by notification. The message parameters have been updated to support virtual list-view controls.
LVM_SETITEMPOSITION | Is not supported.
LVM_SETITEMSTATE | Allows only the selection and focus states to be changed for the item.
LVM_SETITEMTEXT | Is not supported. It is the application's responsibility to maintain the item texts.
LVM_SETWORKAREAS | Is not supported.
LVM_SORTITEMS | Is not supported. It is the application's responsibility to present the items in the desired order.

Handling Virtual List-View Control Notification Messages

List-view controls with the LVS_OWNERDATA style send the same notification messages as other list-view controls plus two additional ones: LVN_ODCACHEHINT and LVN_ODFINDITEM. The following are the most common notifications sent by a list-view control with the LVS_OWNERDATA style.

LVN_GETDISPINFO
A virtual list-view control maintains very little item information on its own. As a result, it often sends the LVN_GETDISPINFO notification message to request item information. This message is handled in much the same way as callback items in a standard list control. Because the number of items supported by the control can be very large, caching item data improves performance.

When handling LVN_GETDISPINFO, the owner of the control first attempts to supply requested item information from the cache (for more information, see Cache Management). If the requested item is not cached, the owner must be prepared to supply the information by other means.

LVN_ODCACHEHINT
A virtual list view sends the LVN_ODCACHEHINT notification message to assist in optimizing the cache. The notification message provides inclusive index values for a range of items that it recommends be cached. Upon receiving the notification message, the owner must be prepared to load the cache with item information for the requested range so that the information will be readily available when an LVN_GETDISPINFO message is sent.
LVN_ODFINDITEM
The LVN_ODFINDITEM notification message is sent by a virtual list-view control when the control needs the owner to find a particular callback item. The notification message is sent when the list-view control receives quick key access or when it receives an LVM_FINDITEM message. Search information is sent in the form of an LVFINDINFO structure, which is a member of the NMLVFINDITEM structure.

The owner must be prepared to search for an item that matches the information given by the list-view control. The owner returns the index of the item if successful, or -1 if no matching item is found.

Cache Management

A list-view control with the LVS_OWNERDATA style produces a large number of LVN_GETDISPINFO notification messages and, to assist in optimizing the cache, an LVN_ODCACHEHINT message. LVN_ODCACHEHINT messages provide information about the recommended items to include within the cache. These messages are sent as WM_NOTIFY messages, with the lParam value acting as the address of an NMLVCACHEHINT structure.

The NMLVCACHEHINT structure includes two integer members, iFrom and iTo, that represent the inclusive endpoints of a range of items that most likely will be needed. The owner must be prepared to load the cache with the item information for each of the items within the recommended range.

The list control often needs item information for the first item (offset 0). The LVN_ODCACHEHINT notification message might not always include item 0, but it must always be included in the cache.

The last items in the list are accessed often. Therefore, the owner might want to keep a second cache that includes the items at the end of the list. The requested range from LVN_ODCACHEHINT can be checked against the end cache to make it available automatically instead of reloading the same end range each time.

List-View Working Areas

List-view controls support working areas, which are rectangular virtual areas that the list-view control uses to arrange its items. A working area is not a window and cannot have a visible border. By default, the list-view control has no working areas. By creating a working area, you can create an empty border on the left, top, or right of the items or cause a horizontal scroll bar to be displayed when there normally would not be one.

The number of working areas can be retrieved with the LVM_GETNUMBEROFWORKAREAS message. The working areas are changed with the LVM_SETWORKAREAS message and can be retrieved with the LVM_GETWORKAREAS message. Both of these messages take the address of an array of RECT structures as the lParam and the number of RECT structures as the wParam. The left and top members of these structures specify the coordinates of the upper-left corner (the origin) of the working area, and the right and bottom members specify the lower-right corner of the working area. All the coordinates are in client coordinates of the list view. The maximum number of working areas allowed is defined by the LV_MAX_WORKAREAS value.

Changing the working area has no effect on list-view controls that have the LVS_LIST or LVS_REPORT view, but the working areas will be maintained when the view type is changed. With the LVS_ICON and LVS_SMALLICON views, the working area can be modified to change the way the items are displayed. Making the width of the working area (right - left) greater than the client width of the control causes the items to be wrapped at that width and the horizontal scroll bar to be displayed. Making the width of the working area narrower than the width of the control's client area causes the items to be wrapped within the working area and not the client area. Setting the left or top member to a positive value causes the items to be displayed starting at the working area, creating an empty space between the edge of the control and the items. An empty space can also be created between the right edge of the control and the items by making the width of the working area less than the client width of the control.

List-View Image Lists

By default, a list-view control does not display item images. To display item images, you must create image lists and associate them with the control. A list-view control can have three image lists:

  • An image list that contains full-sized icons displayed when the control is in icon view.
  • An image list that contains small icons displayed when the control is in small icon view, list view, or report view.
  • An image list that contains state images, which are displayed to the left of the full-sized or small icon. You can use state images, such as checked and cleared check boxes, to indicate application-defined item states. State images are displayed in icon view, small icon view, list view, and report view.

The full-sized and small icon image lists can also contain overlay images, which are designed to be drawn transparently over the item icons.

To use overlay images in a list-view control:

  1. Call the ImageList_SetOverlayImage function to assign an overlay image index to an image in the full-sized and small icon image lists. An overlay image is identified by a one-based index.
  2. You can associate an overlay image index with an item when you call the ListView_InsertItem or ListView_SetItem macro. Use the INDEXTOOVERLAYMASK macro to specify an overlay image index in the state member of the item's LVITEM structure. You must also set the LVIS_OVERLAYMASK bits in the stateMask member.

If a state image list is specified, a list-view control reserves space to the left of each item's icon for a state image.

To associate a state image with an item, use the INDEXTOSTATEIMAGEMASK macro to specify a state image index in the state member of the LVITEM structure. The index identifies an image in the control's state image list. Although image list indexes are zero-based, the control uses one-based indexes to identify state images. A state image index of zero indicates that an item has no state image.

By default, when a list-view control is destroyed, it destroys the image lists assigned to it. However, if a list-view control has the LVS_SHAREIMAGELISTS window style, the application is responsible for destroying the image lists when they are no longer in use. You should specify this style if you assign the same image lists to multiple list-view controls; otherwise, more than one control might try to destroy the same image list.

List-View Items and Subitems

Each item in a list-view control has an icon, a label, a current state, and an application-defined value. By using list-view messages, you can add, modify, and delete items as well as retrieve information about items.

Each item can have one or more subitems. A subitem is a string that, in report view, is displayed in a column separate from the item's icon and label. To specify the text of a subitem, use the LVM_SETITEMTEXT or LVM_SETITEM message. All items in a list-view control have the same number of subitems. The number of subitems is determined by the number of columns in the list-view control. When you add a column to a list-view control, you specify its associated subitem index.

The LVITEM structure defines a list-view item or subitem. The iItem member is the zero-based index of the item. The iSubItem member is the one-based index of a subitem or zero if the structure contains information about an item. Additional members specify the item's text, icon, state, and item data. Item data is an application-defined value associated with a list-view item.

To add an item to a list-view control, use the LVM_INSERTITEM message, specifying the address of an LVITEM structure. Before adding multiple items, you can send the control an LVM_SETITEMCOUNT message, specifying the number of items the control will ultimately contain. This message enables the list-view control to reallocate its internal data structures only once rather than every time you add an item. You can determine the number of items in a list-view control by using the LVM_GETITEMCOUNT message. If you are adding a large number of items to a list-view control, you can speed up the process by disabling redrawing before adding the items, then enable redrawing after the items are added. Use the WM_SETREDRAW message to enable and disable redrawing.

To change the attributes of a list-view item, use the LVM_SETITEM message, specifying the address of an LVITEM structure. The mask member of this structure specifies the item attributes you want to change. For example, to change only the text of an item or subitem, use the LVM_SETITEMTEXT message.

To retrieve information about a list-view item, use the LVM_GETITEM message, specifying the address of the LVITEM structure to fill in. The mask member of this structure specifies the item attributes to be retrieved. To retrieve only an item or subitem's text, use the LVM_GETITEMTEXT message.

To delete a list-view item, use the LVM_DELETEITEM message. You can delete all items in a list-view control by using the LVM_DELETEALLITEMS message.

List-View Item States

An item's state is a value that specifies the item's availability, indicates user actions, or otherwise reflects the item's status. A list-view control changes some state bits, such as when the user selects an item. An application might change other state bits to disable or hide the item or to specify an overlay image or state image. For more information about overlay images and state images, see List-View Image Lists.

An item's state is specified by the state member of the LVITEM structure. When you specify or change an item's state, the stateMask member specifies which state bits you need to change. You can change an item's state by using the LVM_SETITEMSTATE message. You can specify an item's state when you create it or when you change its attributes by using the LVM_SETITEM message. To determine an item's current state, use the LVM_GETITEMSTATE or LVM_GETITEM message.

To set an item's overlay image, the stateMask member of the LVITEM structure must include the LVIS_OVERLAYMASK value, and the state member must include the one-based index of the overlay image shifted left 8 bits by using the INDEXTOOVERLAYMASK macro. The index can be zero to specify no overlay image.

To set an item's state image, the stateMask member of the LVITEM structure must include the LVIS_STATEIMAGEMASK value, and the state member must include the one-based index of the state image shifted left 12 bits by using the INDEXTOSTATEIMAGEMASK macro. The index can be zero to specify no state image.

Callback Items and the Callback Mask

For each of its items, a list-view control typically stores the label text, the image list index of the item's icons, and a set of bit flags for the item's state. You can define callback items or change the control's callback mask to indicate that the application, rather than the control, stores some or all of this information. You might want to use callbacks if your application stores some of this information.

A callback item in a list-view control is an item for which the application stores the text or icon index, or both. You can define callback items when you send the LVM_INSERTITEM message to add an item to the list-view control. If the application stores the text for the item or subitem, set the pszText member of the item's LVITEM structure to LPSTR_TEXTCALLBACK. If the application stores the icon index for an item, set the iImage member of the item's LVITEM structure to I_IMAGECALLBACK.

The callback mask of a list-view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control's items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list-view control stores all item state information. After creating a list-view control and initializing its items, you can send the LVM_SETCALLBACKMASK message to change the callback mask. To retrieve the current callback mask, send the LVM_GETCALLBACKMASK message.

When a list-view control must display or sort a list-view item for which the application stores callback information, the control sends the LVN_GETDISPINFO notification message to the control's parent window. This message specifies an NMLVDISPINFO structure that contains the type of information required and identifies the item or subitem to retrieve. The parent window must process LVN_GETDISPINFO to provide the requested data.

If the list-view control detects a change in an item's callback information, such as a change in the text, icon, or state information, the control sends an LVN_SETDISPINFO notification message to notify you of the change.

If you change a callback item's attributes or state bits, you use the LVM_UPDATE message to force the control to repaint the item. This message also causes the control to arrange its items if it has the LVS_AUTOARRANGE style. You can use the LVM_REDRAWITEMS message to redraw a range of items by invalidating the corresponding portions of the list-view control's client area.

By effectively using callback items and the callback mask, you can ensure that each item attribute is maintained in only one place. Doing this can simplify your application, but the only space saved is the memory that would otherwise be required to store item labels and subitem text.

List-View Columns

Columns control the way items and their subitems are displayed in report view. Each column has a title and width and is associated with a specific subitem; subitem zero is the item's icon and label. The attributes of a column are defined by an LVCOLUMN structure.

To add a column to a list-view control, use the LVM_INSERTCOLUMN message. To delete a column, use the LVM_DELETECOLUMN message. Note that you cannot delete column zero of a list-view control. You can retrieve and change the properties of an existing column by using the LVM_GETCOLUMN and LVM_SETCOLUMN messages. To retrieve or change a column's width, use the LVM_GETCOLUMNWIDTH and LVM_SETCOLUMNWIDTH messages.

Unless the LVS_NOCOLUMNHEADER window style is specified, column headers appear in report view. The user can click a column header, causing an LVN_COLUMNCLICK notification message to be sent to the parent window. Typically, the parent window sorts the list-view control by the specified column when this clicking occurs. The user can also drag the column guides between the headers to size the columns.

List-view controls can display images next to column titles. To implement this feature, specify the LVCF_IMAGE value and assign the index of the image to the iImage member in the LVCOLUMN structure.

List-view controls can set the order in which columns are displayed. To implement this feature, specify the LVCF_ORDER value and assign the column order to the iOrder member in the LVCOLUMN structure. The column order is zero-based and is in left-to-right order. For example, zero indicates the leftmost column.

Arranging, Sorting, and Finding Items

You can use list-view messages to arrange and sort items and to find items based on their attributes or positions. Arranging repositions items to align on a grid, but the indexes of the items do not change. Sorting changes the sequence of items (and their corresponding indexes) and then repositions them accordingly. You can arrange items only in icon and small icon views, but you can sort items in any view. To find items, you send list-view messages that specify an item location or property.

To arrange items, use the LVM_ARRANGE message. You can ensure that items are arranged at all times by specifying the LVS_AUTOARRANGE window style.

To sort items, use the LVM_SORTITEMS message. When you sort using this message, you specify an application-defined callback function that the list-view control calls to compare the relative order of any two items. The control passes to the comparison function the item data associated with each of the two items. The item data is the value that was specified in the lParam member of the item's LVITEM structure when it was inserted into the list. By specifying the appropriate item data and supplying an appropriate comparison function, you can sort items by their label, by any subitem, or by any other property. Note that sorting items does not reorder the corresponding subitems. When items are reordered, their corresponding subitems are carried with them; that is, whole rows are kept together. To order the columns separately from one another, detaching the subitems from their items, you must regenerate the columns after sorting using LVM_SETITEM.

You can ensure that a list-view control is always sorted by specifying the LVS_SORTASCENDING or LVS_SORTDESCENDING window style. Controls with these styles use the label text of the items to sort them in ascending or descending order. You cannot supply a comparison function when using these window styles. If a list-view control has either of these styles, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEM structure.

You can find a list-view item with specific properties by using the LVM_FINDITEM message. You can find a list-view item that is in a specified state and has a specified relationship to a given item by using the LVM_GETNEXTITEM message. For example, you can retrieve the next selected item to the right of a specified item.

List-View Item Position

Every list-view item has a position and size, which you can retrieve and set using messages. You can also determine which item, if any, is at a specified position. The position of list-view items is specified in view coordinates, which are client coordinates offset by the scroll position.

To retrieve and set an item's position, use the LVM_GETITEMPOSITION and LVM_SETITEMPOSITION messages. LVM_GETITEMPOSITION works for all views, but LVM_SETITEMPOSITION works only for icon and small icon views.

You can determine which item, if any, is at a particular location by using the LVM_HITTEST message.

To retrieve the bounding rectangle for a list item or only for its icon or label, use the LVM_GETITEMRECT message.

List-View Scroll Position

Unless the LVS_NOSCROLL window style is specified, a list-view control can be scrolled to show more items than can fit in the client area of the control. You can retrieve a list-view control's scroll position and related information, scroll a list-view control by a specified amount, or scroll a list-view control so that a specified list item is visible.

In icon view or small icon view, the current scroll position is defined by the view origin. The view origin is the set of coordinates, relative to the visible area of the list-view control, that correspond to the view coordinates (0, 0). To retrieve the current view origin, use the LVM_GETORIGIN message. This message should be used only in icon or small icon view; it returns an error in list or report view.

In list or report view, the current scroll position is defined by the top index. The top index is the index of the first visible item in the list-view control. To retrieve the current top index, use the LVM_GETTOPINDEX message. This message returns a valid result only in list or report view; it returns zero in icon or small icon view.

You can use the LVM_GETVIEWRECT message to retrieve the bounding rectangle of all items in a list-view control, relative to the visible area of the control.

The LVM_GETCOUNTPERPAGE message returns the number of items that fit in one page of the list-view control. This message returns a valid result only in list and report views; in icon and small icon views, it returns the total number of items.

To scroll a list-view control by a specific amount, use the LVM_SCROLL message. Using the LVM_ENSUREVISIBLE message, you can scroll the list-view control, if necessary, to ensure that a specified item is visible.

List-View Label Editing

A list-view control that has the LVS_EDITLABELS window style enables a user to edit item labels in place. The user begins editing by clicking the label of an item that has the focus. Alternatively, an application can begin editing automatically by using the LVM_EDITLABEL message. The list-view control notifies the parent window when editing begins and when it is canceled or completed. When editing is completed, the parent window is responsible for updating the item's label, if appropriate.

When label editing begins, an edit control is created, positioned, and initialized. Before it is displayed, the list-view control sends its parent window an LVN_BEGINLABELEDIT notification message. If you need to modify the label editing process, you can implement a handler for this notification.

One use for an LVN_BEGINLABELEDIT notification handler is to control which labels the user can edit. To prevent label editing, return a nonzero value. To customize label editing, have the notification handler retrieve a handle to the edit control by sending an LVM_GETEDITCONTROL message to the list-view control. Once you have that handle, you can customize the edit control by sending the usual EM_XXX messages. For instance, to limit the amount of text a user can enter, send the edit control an EM_LIMITTEXT message. You can change the edit control's default text with SetWindowText. You can even subclass the edit control to intercept and discard invalid characters.

When label editing is canceled or completed, a list-view control sends its parent window an LVN_ENDLABELEDIT notification message. The lParam parameter is the address of an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item. If editing is canceled, the pszText member of the LVITEM structure is NULL; otherwise, pszText is the address of the edited text. The parent window is responsible for updating the item's label if it wants to keep the new label.

List-View Colors

An application can retrieve and set three colors for a list-view control.

Color | Messages used to retrieve and set colors
Text color | LVM_GETTEXTCOLOR, LVM_SETTEXTCOLOR
Text background color | LVM_GETTEXTBKCOLOR, LVM_SETTEXTBKCOLOR
Window background color | LVM_GETBKCOLOR, LVM_SETBKCOLOR

To customize the appearance of a list-view control more significantly, use NM_CUSTOMDRAW (list view).


Using List-View Controls

This section contains code examples that demonstrate how to create and use list-view controls in your applications.

  • Creating List-View Controls
  • Adding List-View Image Lists
  • Adding List-View Columns
  • Adding List-View Items and Subitems
  • Using List-View Working Areas
  • Using Virtual List-View Controls
  • Related Topics

Creating List-View Controls

To create a list-view control, you use the CreateWindow or CreateWindowEx function and specify the WC_LISTVIEW window class. The following code sample creates a list-view control in report view.

// CreateListView - creates a list-view control in report view.
// Returns the handle to the new control if successful, or NULL
// otherwise.
// hWndParent - handle to the control's parent window.
HWND CreateListView (HWND hwndParent)
{
HWND hWndListView;
RECT rcl;
INITCOMMONCONTROLSEX icex;

// Ensure that the common control DLL is loaded.
icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
icex.dwICC  = ICC_LISTVIEW_CLASSES;
InitCommonControlsEx(&icex);

// Create the list-view window in report view with label
// editing enabled.
GetClientRect (hWndParent, &rcl);
hWndListView = CreateWindow (WC_LISTVIEW, "",
        WS_CHILD | LVS_REPORT | LVS_EDITLABELS,
        0, 0, rcl.right - rcl.left, rcl.bottom - rcl.top,
        hwndParent, (HMENU) ID_LISTVIEW, hInst, NULL);
if (hWndListView == NULL)
        return NULL;

A list-view control can also be created as part of a dialog box template. Specify WC_LISTVIEW as the class name. Note that if you use a list-view control as part of a dialog box template, you must call InitCommonControls or InitCommonControlsEx before the dialog box template is created, in order to ensure that the list-view window class is properly registered. Otherwise, the dialog box template does not create the list-view control successfully.

The following illustration shows the four views that a list-view control can have.

Windows with list-view controls.

Typically, list-view applications enable the user to change from one view to another. The following code sample changes the list-view's window style, which in turn changes the view.

// SetView - sets a list-view's window style to change the view.
// hWndListView - handle to the list-view control.
// dwView - value specifying the new view style.

VOID SetView(HWND hWndListView, DWORD dwView)
{
// Retrieve the current window style.
DWORD dwStyle = GetWindowLong(hWndListView, GWL_STYLE);

// Only set the window style if the view bits have changed.
if ((dwStyle & LVS_TYPEMASK) != dwView)
    SetWindowLong(hWndListView, GWL_STYLE,
       (dwStyle & ~LVS_TYPEMASK) | dwView);
}

Adding List-View Image Lists

When a list-view control is created by default, it does not display item images. You must assign an image to the list-view control. To do this, use the LVM_SETIMAGELIST message or the corresponding macro ListView_SetImageList, specifying whether the image list contains full-sized icons, small icons, or state images. To retrieve the handle to an image list currently assigned to a list-view control, use the LVM_GETIMAGELIST message. You can use the GetSystemMetrics function to determine appropriate dimensions for the full-sized and small icons.

You need to create only the image lists that the control uses. For example, if your application does not allow the user to switch to icon view, you do not need to create and assign a large icon list. If you create both large and small image lists, they must contain the same images in the same order, because a single value is used to identify a list-view item's icon in both image lists.

// InitListViewImageLists - creates image lists for a list-view control.
// This function only creates image lists. It does not insert the
// items into the control, which is necessary for the control to be
// visible.
// Returns TRUE if successful, or FALSE otherwise.
// hWndListView - handle to the list-view control.
BOOL InitListViewImageLists(HWND hWndListView)
{
    HICON hiconItem;     // icon for list-view items
    HIMAGELIST hLarge;   // image list for icon view
    HIMAGELIST hSmall;   // image list for other views

    // Create the full-sized icon image lists.
    hLarge = ImageList_Create(GetSystemMetrics(SM_CXICON),
        GetSystemMetrics(SM_CYICON), ILC_MASK, 1, 1);
    hSmall = ImageList_Create(GetSystemMetrics(SM_CXSMICON),
        GetSystemMetrics(SM_CYSMICON), ILC_MASK, 1, 1);

    // Add an icon to each image list.
    hiconItem = LoadIcon(g_hinst, MAKEINTRESOURCE(IDI_ITEM));
    ImageList_AddIcon(hLarge, hiconItem);
    ImageList_AddIcon(hSmall, hiconItem);
    DestroyIcon(hiconItem);

    /*********************************************************
    Usually you have multiple icons; therefore, the previous
    four lines of code can be inside a loop. The following code
    shows such a loop. The icons are defined in the application's
    header file as resources, which are numbered consecutively
    starting with IDS_FIRSTICON. The number of icons is
    defined in the header file as C_ICONS.

    for(index = 0; index < C_ICONS; index++)
    {
    hIconItem = LoadIcon (hInst, MAKEINTRESOURCE (IDS_FIRSTICON +
                index));
    ImageList_AddIcon(hSmall, hIconItem);
    ImageList_AddIcon(hLarge, hIconItem);
    Destroy(hIconItem);
    }
    *********************************************************/

    // Assign the image lists to the list-view control.
    ListView_SetImageList(hwndLV, hLarge, LVSIL_NORMAL);
    ListView_SetImageList(hwndLV, hSmall, LVSIL_SMALL);
    return TRUE;
}

Adding List-View Columns

Columns are used when a list-view control is in report view to display the items and subitems. The following example adds columns to a list-view control. The column headings are defined in the application's header file as string resources, which are numbered consecutively starting with IDS_FIRSTCOLUMN. The number of columns is defined in the header file as C_COLUMNS.

// InitListViewColumns - adds columns to a list-view control.
// Returns TRUE if successful, or FALSE otherwise.
// hWndListView - handle to the list-view control.
BOOL InitListViewColumns(HWND hWndListView)
{
    char szText[256];     // temporary buffer
    LVCOLUMN lvc;
    int iCol;

    // Initialize the LVCOLUMN structure.
    // The mask specifies that the format, width, text, and subitem
    // members of the structure are valid.
    lvc.mask = LVCF_FMT | LVCF_WIDTH | LVCF_TEXT | LVCF_SUBITEM;

    // Add the columns.
    for (iCol = 0; iCol < C_COLUMNS; iCol++)
    {
        lvc.iSubItem = iCol;
        lvc.pszText = szText;
        lvc.cx = 100;           // width of column in pixels
        if ( iCol < 2 )
          {
          lvc.fmt = LVCFMT_LEFT;  // left-aligned column
          }
        else
          {
          lvc.fmt = LVCFMT_RIGHT;  // right-aligned column
          }
        LoadString(hInst, IDS_FIRSTCOLUMN + iCol,
                szText, sizeof(szText));
        if (ListView_InsertColumn(hWndListView, iCol, &lvc) == -1)
            return FALSE;
    }
    return TRUE;
}

Adding List-View Items and Subitems

To add an item to a list-view control, an application must first define an LVITEM structure and then send an LVM_INSERTITEM message, specifying the address of the LVITEM structure.

If an application uses report view, subitem text must be entered. The following code samples fill an LVITEM structure and add the list-view items by using the LVM_INSERTITEM message or the corresponding macro ListView_InsertItem. Because the application saves its own text, it specifies the LPSTR_TEXTCALLBACK value for the pszText member of the LVITEM structure. Specifying the LPSTR_TEXTCALLBACK value causes the control to send an LVN_GETDISPINFO notification message to its owner window whenever it needs to display an item.

// This code snippet adds three items, each with three subitems, to
// a list-view control.
// hWndListView - handle to the list-view control.
// The following application-specific structure, PETINFO, is used in
// the snippet.

typedef struct tagPETINFO
{
    char szKind[10];
    char szBreed[50];
    char szPrice[20];
}PETINFO;

// A PETINFO variable is declared and initialized as follows:
PETINFO rgPetInfo[ ] =
{
{"Dog", "Poodle", "$300.00"},
{"Cat", "Siamese", "$100.00"},
{"Fish", "Angel Fish", "$10.00"},
};

// Some code to create the list-view control.

// Initialize LVITEM members that are common to all items.
lvI.mask = LVIF_TEXT | LVIF_IMAGE | LVIF_PARAM | LVIF_STATE;
lvI.state = 0;
lvI.stateMask = 0;

// Initialize LVITEM members that are different for each item.
for (index = 0; index < 3; index++)
{
       lvI.iItem = index;
    lvI.iImage = index;
    lvI.iSubItem = 0;
    lvI.lParam = (LPARAM) &rgPetInfo[index];
    lvI.pszText = LPSTR_TEXTCALLBACK; // sends an LVN_GETDISPINFO
                                           // message.

if(ListView_InsertItem(hWndListView, &lvI) == -1)
return NULL;
}

// Because the application specifies LPSTR_TEXTCALLBACK, it sends
// LVN_GETDISPINFO notification messages. The application must
// process these notification messages and supply the text for the
// subitems.
// The text is stored in a previously listed application-defined
// structure called PETINFO.

case WM_NOTIFY:
  switch (((LPNMHDR) lParam)->code)
  {
  case LVN_GETDISPINFO:
    switch (((LPNMLVDISPINFO)lParam)->item.iSubItem)
    {
    case 0:
      plvdi->item.pszText = rgPetInfo[plvdi->item.iItem].szKind;
      break;
    case 1:
      plvdi->item.pszText = rgPetInfo[plvdi->item.iItem].szBreed;
      break;
    case 2:
      plvdi->item.pszText = rgPetInfo[plvdi->item.iItem].szPrice;
      break;
    default:
      break;
    }
    return 0;
  }
  // NOTE in addition to setting pszText to point to
  // the item text, you could copy the item text into pszText
  // using lstrcpyn. For example:
  lstrcpyn ( plvdi->item.pszText,
             rgPetInfo[plvdi->item.iItem].szKind, 10);

Using List-View Working Areas

When a working area is created, items that lie within the working area become members of it. Similarly, if an item is moved into a working area, the item becomes a member of the working area to which it was moved. If an item does not lie within any working area, it automatically becomes a member of the first (index 0) working area. If you want to create an item and have it placed within a specific working area, you will need to create the item and then move it into the desired working area using an LVM_SETITEMPOSITION or LVM_SETITEMPOSITION32 message.

The following illustration is an example of a list-view control that contains four working areas, each in a different quadrant of the client area and with a 25-pixel empty area around them.

List-view control that contains four working areas.

To determine which working area an item is a member of, retrieve the working areas, retrieve the position of the item, and compare its position to the working areas. The following function returns the index of the working area to which the item belongs. If the function fails, it returns -1. If the function succeeds, but the item is not inside any of the working areas, the function returns 0, because all items that are not inside a working area automatically become a member of working area zero.

int GetItemWorkingArea(HWND hWndListView, int iItem)
{
UINT     uWorkAreas = 0;
int      nReturn = -1;
LPRECT   pRects;
POINT    pt;

if(!ListView_GetItemPosition(hWndListView, iItem, &pt))
   return nReturn;

ListView_GetNumberOfWorkAreas(hWndListView, &uWorkAreas);

if(uWorkAreas)
   {
   pRects = (LPRECT)GlobalAlloc(GPTR, sizeof(RECT) * uWorkAreas);

   if(pRects)
      {
      UINT  i;

      nReturn = 0;

      ListView_GetWorkAreas(hWndListView, uWorkAreas, pRects);

      for(i = 0; i < uWorkAreas; i++)
         {
         if(PtInRect((pRects + i), pt))
            {
            nReturn = i;
            break;
            }
         }

      GlobalFree((HGLOBAL)pRects);
      }
   }
return nReturn;
}

Multiple working areas can be used for creating different areas within one view. You can create areas in a single view that have different meanings. For example, a view of a file system might have an area for read/write files and another area for read-only files. The user can categorize items by placing them in different working areas. If a file were moved into the read-only area, it would automatically become read-only.

Multiple working areas can intersect, but any items that lie within the intersection become members of the area with the lower index; therefore, it is best to avoid this situation. When sorting multiple work areas, the items are sorted compared to the other items in the same working area.

The following code examples show how to create working areas. The first example creates one working area with a 25-pixel empty space around the left, top, and right sides of the items.

{
#define  EMPTY_SPACE   25

RECT  rcClient;

GetClientRect(hwndListView, &rcClient);

rcClient.left += EMPTY_SPACE;
rcClient.top += EMPTY_SPACE;
rcClient.right -= (EMPTY_SPACE * 2);

SendMessage(hWndListView, LVM_SETWORKAREAS, 1, (LPARAM)&rcClient);
}

This example demonstrates how to create two working areas in a control that take up about half of the client area and have a 25-pixel border around each working area.

{
#define  EMPTY_SPACE   25

RECT  rcClient;
RECT  rcWork[2];

GetClientRect(hwndListView, &rcClient);

rcWork[0].left = rcClient.left + EMPTY_SPACE;
rcWork[0].top = rcClient.top + EMPTY_SPACE;
rcWork[0].right = (rcClient.right/2) - EMPTY_SPACE;
rcWork[0].bottom = rcClient.bottom;

rcWork[1].left = (rcClient.right/2) + EMPTY_SPACE;
rcWork[1].top = rcClient.top + EMPTY_SPACE;
rcWork[1].right = rcClient.right - EMPTY_SPACE;
rcWork[1].bottom = rcClient.bottom;

SendMessage(hWndListView, LVM_SETWORKAREAS, 2, (LPARAM)rcWork);
}

Using Virtual List-View Controls

This section includes sample code used to implement a virtual list-view control. The code contains application-defined functions and structures that implement aspects of a virtual list-view control and perform cache management.

Name | Description
OnNotify function | Handles virtual list-view notification messages.
PrepCache function | Performs basic cache management.
RetrieveItem function | Retrieves item information from the cache.
RndItem structure | Holds item information for use with a cache.

Note This sample code assumes that the cache used is a dynamically allocated array of the application-defined structure RndItem. The list-view control in the example is assumed to have three columns—one column for the item label and two columns for subitems.

Sample Function: OnNotify

This application-defined function handles notification messages commonly sent from a virtual list-view control.

LRESULT OnNotify( HWND hwnd, NMHDR* pnmhdr )
{
    LRESULT lrt = FALSE;

    switch (pnmhdr->code){
        case LVN_GETDISPINFO:
            RndItem rndItem;
            NMLVDISPINFO* pLvdi = (LPNMLVDISPINFO) pnmhdr;
            if (-1 == pLvdi->item.iItem){
                OutputDebugString("LVOWNER: Request for -1 item?\n");
                DebugBreak();
            }

            // Retrieve information for item at index iItem.
            RetrieveItem( &rndItem, pLvdi->item.iItem );

            if(pLvdi->item.mask & LVIF_STATE){
                // Fill in the state information.
                pLvdi->item.state |= rndItem.state;
            }

            if(pLvdi->item.mask & LVIF_IMAGE){
                // Fill in the image information.
                pLvdi->item.iImage = rndItem.iIcon;
            }

            if(pLvdi->item.mask & LVIF_TEXT){
                // Fill in the text information.
                switch (pLvdi->item.iSubItem){
                    case 0:
                        // Copy the main item text.
                        lstrcpy( pLvdi->item.pszText, rndItem.Title );
                        break;

                    case 1:
                        // Copy subitem 1 text.
                        lstrcpy( pLvdi->item.pszText, rndItem.SubText1 );
                        break;

                    case 2:
                        // Copy subitem 2 text.
                        lstrcpy( pLvdi->item.pszText, rndItem.SubText2 );
                        break;

                    default:
                        break;
                }
            }
            lrt = FALSE;
            break;

    case LVN_ODCACHEHINT:
        NMLVCACHEHINT* pcachehint = (NMLVCACHEHINT*) pnmhdr;

        // Load the cache with the recommended range.
        PrepCache( pcachehint->iFrom, pcachehint->iTo );
        break;

    case LVN_ODFINDITEM:
        LPNMLVFINDITEM pnmfi = (LPNMLVFINDITEM)pnmhdr;

        // Call a user-defined function to find the index according
        // to LVFINDINFO, which is embedded in the LPNMLVFINDITEM
        // structure. Set return value to -1 if no hits are found.
        break;

    default:
        break;

    return( lrt );
}

Sample Function: PrepCache

This function accepts the range values for the cache suggested by a virtual list-view control. It performs a verification to determine that the requested range is not already cached, and then it allocates the required global memory and fills the cache if necessary.

void PrepCache( int iFrom, int iTo )
{
/*  Global Variables
 *    g_priCache[ ] is the main cache.
 *    g_iCache is the index of the first item in the main cache.
 *    c_cCache is the count of items in the main cache.
 *
 *    g_priEndCache[ ] is the cache of items at the end of the list.
 *    g_iEndCache is the index of the first item in the end cache.
 *    g_cEndCache is the count of items in the end cache.
 */

    // Local Variables
    int i;
    BOOL fOLFrom = FALSE;
    BOOL fOLTo = FALSE;

    // Check to see if this is the end cache.
    if ((iTo == g_cItems - 1) && ((iTo - iFrom) < 30))  // 30 entries wide{
        // Check to see if this is a portion of the current end cache.
        if ((g_cCache) &&
            (iFrom >= g_iEndCache) &&
            (iFrom < g_iEndCache+g_cEndCache))
            return;  // if a part of current end cache, no loading
                     // is necessary

        // This is a new end cache; free the old memory.
        if ( g_priEndCache )
            GlobalFree( g_priEndCache );

        // Set the index and count values for the new end cache;
        // then retrieve the memory.
        g_iEndCache = iFrom;
        g_cEndCache = (iTo - iFrom + 1);
        g_priEndCache = (PRndItem)GlobalAlloc( GPTR, sizeof( RndItem )
            * g_cEndCache );

        if (! g_priEndCache);
            // Out of memory. Perform error handling operations.

        // Loop to fill the cache with the recommended items.
        for (i=0; i<g_cEndCache; i++);
            // Call function that accesses item information and
            // fills a cache element here.
    }

    else{    // Not a member of the current end cache. Try primary
             // cache instead.

        // Check to see if iFrom is within the primary cache.
        if ((g_cCache) &&
            (iFrom >= g_iCache) &&
            (iFrom < g_iCache+g_cCache))
            fOLFrom = TRUE;

        // Check to see if iTo is within the primary cache.
        if ((g_cCache) &&
            (iTo >= g_iCache) &&
            (iTo <= g_iCache+g_cCache))
            fOLTo = TRUE;

        // If both iFrom and iTo are within current cache, no work
        // is needed.
        if (fOLFrom && fOLTo)
            return;

        // Enlarge the cache size rather than make it specific to
        // this hint.
        if (fOLFrom)
            iFrom = g_iCache;
        else if (fOLTo)
            iTo = g_iCache + g_cCache;

        // A new primary cache is needed; free the old one.
        if ( g_priCache )
            GlobalFree( g_priCache );

        // Set the index and count values for the new primary cache,
        // and then retrieve the memory.
        g_iCache = iFrom;
        g_cCache = (iTo - iFrom + 1);
        g_priCache = (PRndItem)GlobalAlloc( GPTR, sizeof( RndItem )
            * g_cCache );

        if (!g_priEndCache);
            // Out of memory. Do error handling.

        // Loop to fill the cache with the recommended items.
        for (i=0; i<g_cEndCache; i++)
            // Call function that accesses item information and
            // fills a cache element here.
    }
}

Sample Function: RetrieveItem

This sample function accepts two parameters—the address of the application-defined structure RndItem and an integer value representing the index of the item in the list. It checks the index value to discover if the desired item is cached. If it is, the pointer that was passed to it is set to a location in the cache. If the item is not in the main or end cache, the item information must be located manually.

void RetrieveItem( PRndItem prndItem, int index )
{
/*  Global Variables
 *    g_priCache[ ] is the main cache.
 *    g_iCache is the index of the first item in the main cache.
 *    c_cCache is the count of items in the main cache.
 *
 *    g_priEndCache[ ] is the cache of items at the end of the list.
 *    g_iEndCache is the index of the first item in the end cache.
 *    g_cEndCache is the count of items in the end cache.
 */

    // Check to see if the item is in the main cache.
    if ((index >= g_iCache) && (index < g_iCache + g_cCache))
        *prndItem = g_priCache[index-g_iCache];

    // If it is not, check to see if the item is in the end area
    // cache.
    else if ((index >= g_iEndCache)
              && (index < g_iEndCache + g_cEndCache))
        *prndItem = g_priEndCache[index-g_iEndCache];
    else{
        // The item is not in either cache;
        // you should retrieve the item information manually.
    }
}

Sample Structure: RndItem

This sample user-defined structure holds information placed in the cache. The structure has the following form.

typedef struct _RndItem
{
    int   iIcon;            // bitmap assigned to this item
    TCHAR Title[SIZE];      // SIZE is a user-defined macro value
    UINT  state;            // item state value
    TCHAR SubText1[SIZE];   // text for the label of the first subitem
    TCHAR SubText2[SIZE];   // text for the label of the second item

} RndItem, *PRndItem;

Related Topics

For complete samples that demonstrate how to create and use list-view controls, see the following:

  • ListView1
  • Palletized

For a list of the window messages processed by a list-view control, see:

  • Default List-View Message Processing


List-View Window Styles

The following window styles are specific to list-view controls.

LVS_ALIGNLEFT
Items are left-aligned in icon and small icon view.
LVS_ALIGNTOP
Items are aligned with the top of the list-view control in icon and small icon view.
LVS_AUTOARRANGE
Icons are automatically kept arranged in icon and small icon view.
LVS_EDITLABELS
Item text can be edited in place. The parent window must process the LVN_ENDLABELEDIT notification message.
LVS_ICON
This style specifies icon view.
LVS_LIST
This style specifies list view.
LVS_NOCOLUMNHEADER
Column headers are not displayed in report view. By default, columns have headers in report view.
LVS_NOLABELWRAP
Item text is displayed on a single line in icon view. By default, item text may wrap in icon view.
LVS_NOSCROLL
Scrolling is disabled. All items must be within the client area. This style is not compatible with the LVS_LIST or LVS_REPORT styles. See Knowledge Base Article Q137520 for further discussion.
LVS_NOSORTHEADER
Column headers do not work like buttons. This style can be used if clicking a column header in report view does not carry out an action, such as sorting.
LVS_OWNERDATA
Version 4.70. This style specifies a virtual list-view control. For more information about this list control style, see List-View Controls.
LVS_OWNERDRAWFIXED
The owner window can paint items in report view. The list-view control sends a WM_DRAWITEM message to paint each item; it does not send separate messages for each subitem. The itemData member of the DRAWITEMSTRUCT structure contains the item data for the specified list-view item.
LVS_REPORT
This style specifies report view. When using the LVS_REPORT style with a list-view control, the first column is always left-aligned. You cannot use LVCFMT_RIGHT to change this alignment. See LVCOLUMN for further information on column alignment.
LVS_SHAREIMAGELISTS
The image list will not be deleted when the control is destroyed. This style enables the use of the same image lists with multiple list-view controls.
LVS_SHOWSELALWAYS
The selection, if any, is always shown, even if the control does not have the focus.
LVS_SINGLESEL
Only one item at a time can be selected. By default, multiple items may be selected.
LVS_SMALLICON
This style specifies small icon view.
LVS_SORTASCENDING
Item indexes are sorted based on item text in ascending order.
LVS_SORTDESCENDING
Item indexes are sorted based on item text in descending order.

Remarks

For the LVS_SORTASCENDING and LVS_SORTDESCENDING styles, item indexes are sorted based on item text in ascending or descending order, respectively. Because the LVS_LIST and LVS_REPORT views display items in the same order as their indexes, the results of sorting are immediately visible to the user. The LVS_ICON and LVS_SMALLICON views do not use item indexes to determine the position of icons. With those views, the results of sorting are not visible to the user.

You can use the LVS_TYPEMASK mask to isolate the window styles that correspond to the current view: LVS_ICON, LVS_LIST, LVS_REPORT, and LVS_SMALLICON.

You can use the LVS_ALIGNMASK mask to isolate the window styles that specify the alignment of items: LVS_ALIGNLEFT and LVS_ALIGNTOP.

You can use the LVS_TYPESTYLEMASK mask to isolate the window styles that control item alignment (LVS_ALIGNLEFT and LVS_ALIGNTOP) and those that control header appearance and behavior (LVS_NOCOLUMNHEADER and LVS_NOSORTHEADER).


Extended List-View Styles

List-view control styles have been extended. To employ these new styles, use the LVM_SETEXTENDEDLISTVIEWSTYLE message or one of the ListView_SetExtendedListViewStyle or ListView_SetExtendedListViewStyleEx macros.

LVS_EX_CHECKBOXES
Version 4.70. Enables check boxes for items in a list-view control. When set to this style, the control will create and set a state image list with two images using DrawFrameControl. State image 1 is the unchecked box, and state image 2 is the checked box. Setting the state image to zero removes the checkbox altogether. Check boxes are visible and functional with all list-view modes. You can obtain the state of the check box for a given item with ListView_GetCheckState. To set the check state, use ListView_SetCheckState.
LVS_EX_FLATSB
Version 4.71. Enables flat scroll bars in the list view. If you need more control over the appearance of the list-view's scroll bars, you should manipulate the list-view's scroll bars directly using the Flat Scroll Bar APIs. If the system metrics change, you are responsible for adjusting the scrollbar metrics with FlatSB_SetScrollProp. See Flat Scroll Bars for further details.
LVS_EX_FULLROWSELECT
Version 4.70. When an item is selected, the item and all its subitems are highlighted. This style is available only in conjunction with the LVS_REPORT style.
LVS_EX_GRIDLINES
Version 4.70. Displays gridlines around items and subitems. This style is available only in conjunction with the LVS_REPORT style.
LVS_EX_HEADERDRAGDROP
Version 4.70. Enables drag-and-drop reordering of columns in a list-view control. This style is only available to list-view controls that use the LVS_REPORT style.
LVS_EX_INFOTIP
Version 4.71. When a list-view control uses the LVS_EX_INFOTIP style, the LVN_GETINFOTIP notification message is sent to the parent window before displaying an item's ToolTip.
LVS_EX_LABELTIP
Version 5.80. If a partially hidden label in any list-view mode lacks ToolTip text, the list-view control will unfold the label. If this style is not set, the list-view control will unfold partly hidden labels only for the large icon mode.
LVS_EX_MULTIWORKAREAS
Version 4.71. If the list-view control has the LVS_AUTOARRANGE style, the control will not autoarrange its icons until one or more work areas are defined (see LVM_SETWORKAREAS). To be effective, this style must be set before any work areas are defined and any items have been added to the control.
LVS_EX_ONECLICKACTIVATE
Version 4.70. The list-view control sends an LVN_ITEMACTIVATE notification message to the parent window when the user clicks an item. This style also enables hot tracking in the list-view control. Hot tracking means that when the cursor moves over an item, it is highlighted but not selected. See the Remarks for a discussion of item activation.
LVS_EX_REGIONAL
Version 4.71. Sets the list-view window region to include only the item icons and text using SetWindowRgn. Any area that is not part of an item is excluded from the window region. This style is only available to list-view controls that use the LVS_ICON style.
LVS_EX_SUBITEMIMAGES
Version 4.70. Allows images to be displayed for subitems. This style is available only in conjunction with the LVS_REPORT style.
LVS_EX_TRACKSELECT
Version 4.70. Enables hot-track selection in a list-view control. Hot track selection means that an item is automatically selected when the cursor remains over the item for a certain period of time. The delay can be changed from the default system setting with a LVM_SETHOVERTIME message. This style applies to all styles of list-view control. You can check whether or not hot-track selection is enabled by calling SystemParametersInfo.
LVS_EX_TWOCLICKACTIVATE
Version 4.70. The list-view control sends an LVN_ITEMACTIVATE notification message to the parent window when the user double-clicks an item. This style also enables hot tracking in the list-view control. Hot tracking means that when the cursor moves over an item, it is highlighted but not selected. See the Remarks for a discussion of item activation.
LVS_EX_UNDERLINECOLD
Version 4.71. Causes those non-hot items that may be activated to be displayed with underlined text. This style requires that LVS_EX_TWOCLICKACTIVATE be set also. See the Remarks for a discussion of item activation.
LVS_EX_UNDERLINEHOT
Version 4.71. Causes those hot items that may be activated to be displayed with underlined text. This style requires that LVS_EX_ONECLICKACTIVATE or LVS_EX_TWOCLICKACTIVATE also be set. See the Remarks for a discussion of item activation.

Remarks

An item becomes hot when the mouse hovers over it. If hot-tracking is enabled, hot items will be highlighted, but the user must still click the item at least once to select it. Activating an item causes the list-view control to send an LVN_ITEMACTIVATE notification. An item may be selected when it is in a state in which a single click will select it.

If the LVS_EX_ONECLICKACTIVATE style is set, only one click is required to select any item, so all items may be selected. If the LVS_EX_TWOCLICKACTIVATE style is set, two clicks are required to select an item. With this style, the item may be selected only after it has been clicked once.

Setting the LVS_EX_UNDERLINEHOT style will cause the text of any hot item that may be selected to be underlined. Setting the LVS_EX_UNDERLINECOLD style will cause the text of items that are not hot, but may be selected, to be underlined.


List-View Item States

An item's state value consists of the item's state, an optional overlay mask index, and an optional state image mask index.

An item's state determines its appearance and functionality. The state can be zero or one or more of the following values:
Item State | Description
LVIS_ACTIVATING | Not currently supported.
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.

You can use the LVIS_OVERLAYMASK mask to isolate the one-based index of the overlay image. You can use the LVIS_STATEIMAGEMASK mask to isolate the one-based index of the state image.


LVM_APPROXIMATEVIEWRECT

Calculates the approximate width and height required to display a given number of items. You can send this message explicitly or use the ListView_ApproximateViewRect macro.

LVM_APPROXIMATEVIEWRECT
    wParam = (WPARAM)(INT) iCount;
    lParam = (LPARAM) MAKELPARAM(cx, cy);

Parameters

iCount
Number of items to be displayed in the control. If this parameter is set to -1, the message uses the total number of items in the control.
cx and cy
Proposed dimensions of the control, in pixels. Either parameter can be set to -1 to allow the message to use the current width or height value.

Return Values

Returns a DWORD value that holds the approximate width and height needed to display the items, in pixels.

Remarks

Setting the size of the list-view control based on the dimensions provided by this message can optimize redraw and reduce flicker.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_ARRANGE

Arranges items in icon view. You can send this message explicitly or by using the ListView_Arrange macro.

LVM_ARRANGE
    wParam = (WPARAM) (int) code;
    lParam = 0;

Parameters

code
Alignment. This can be one of the following values:
LVA_ALIGNLEFT | Aligns items along the left edge of the window.
LVA_ALIGNTOP | Aligns items along the top edge of the window.
LVA_DEFAULT | Aligns items according to the list-view control's current alignment styles (the default value).
LVA_SNAPTOGRID | Snaps all icons to the nearest grid position.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_CREATEDRAGIMAGE

Creates a drag image list for the specified item. You can send this message explicitly or by using the ListView_CreateDragImage macro.

LVM_CREATEDRAGIMAGE
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (LPPOINT) lpptUpLeft;

Parameters

iItem
Index of the item.
lpptUpLeft
Address of a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Values

Returns the handle to the drag image list if successful, or NULL otherwise.

Remarks

Your application is responsible for destroying the image list when it is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_DELETEALLITEMS

Removes all items from a list-view control. You can send this message explicitly or by using the ListView_DeleteAllItems macro.

LVM_DELETEALLITEMS
    wParam = 0;
    lParam = 0;

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a list-view control receives the LVM_DELETEALLITEMS message, it sends the LVN_DELETEALLITEMS notification message to its parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_DELETECOLUMN

Removes a column from a list-view control. You can send this message explicitly or by using the ListView_DeleteColumn macro.

LVM_DELETECOLUMN
    wParam = (WPARAM) (int) iCol;
    lParam = 0;

Parameters

iCol
Index of the column to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Column zero of the list-view control cannot be deleted. If you must delete column zero, insert a zero length dummy column zero and delete column one and above.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_DELETEITEM

Removes an item from a list-view control. You can send this message explicitly or by using the ListView_DeleteItem macro.

LVM_DELETEITEM
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Parameters

iItem
Index of the list-view item to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_EDITLABEL

Begins in-place editing of the specified list-view item's text. The message implicitly selects and focuses the specified item. You can send this message explicitly or by using the ListView_EditLabel macro.

LVM_EDITLABEL
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Parameters

iItem
Index of the list-view item. To cancel editing, set iItem to -1.

Return Values

Returns the handle to the edit control that is used to edit the item text if successful, or NULL otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

WM_CANCELMODE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_ENABLEGROUPVIEW Message

This is preliminary documentation and is subject to change.

Enables or disables a group.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_ENABLEGROUPVIEW,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (BOOL) fEnable;
   (LPARAM) lParam
  |     // = (LPARAM) (LPARAM) lParam;

);

Parameters

fEnable
[in] BOOL that indicates whether to enable or disable the group. Use TRUE to enable group view, FALSE to disable it.
lParam
[in] Must be NULL.

Return Value

Returns one of the following values.

0 | The group is already in an enabled or disabled state.
1 | The state of the group was successfully changed.
-1 | The operation failed.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_ENSUREVISIBLE

Ensures that a list-view item is either entirely or partially visible, scrolling the list-view control if necessary. You can send this message explicitly or by using the ListView_EnsureVisible macro.

LVM_ENSUREVISIBLE
    wParam = (WPARAM) (int) i;
    lParam = (LPARAM) (BOOL) fPartialOK;

Parameters

i
Index of the list-view item.
fPartialOK
Value specifying whether the item must be entirely visible. If this parameter is TRUE, no scrolling occurs if the item is at least partially visible.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_FINDITEM

Searches for a list-view item with the specified characteristics. You can send this message explicitly or by using the ListView_FindItem macro.

LVM_FINDITEM
    wParam = (WPARAM) (int) iStart;
    lParam = (LPARAM) (const LPLVFINDINFO) plvfi;

Parameters

iStart
Index of the item to begin the search with or -1 to start from the beginning. The specified item is itself excluded from the search.
plvfi
Address of an LVFINDINFO structure that contains information about what to search for.

Return Values

Returns the index of the item if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETBKCOLOR

Retrieves the background color of a list-view control. You can send this message explicitly or by using the ListView_GetBkColor macro.

LVM_GETBKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns the background color of the list-view control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETBKIMAGE

Retrieves the background image in a list-view control. You can send this message explicitly or by using the ListView_GetBkImage macro.

LVM_GETBKIMAGE
    wParam = 0;
    lParam = (LPARAM) (LPLVBKIMAGE) plvbki;

Parameters

plvbki
Address of an LVBKIMAGE structure that will receive the background image information.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

LVM_SETBKIMAGE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_GETCALLBACKMASK

Retrieves the callback mask for a list-view control. You can send this message explicitly or by using the ListView_GetCallbackMask macro.

LVM_GETCALLBACKMASK
    wParam = 0;
    lParam = 0;

Return Values

Returns the callback mask.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETCOLUMN

Retrieves the attributes of a list-view control's column. You can send this message explicitly or by using the ListView_GetColumn macro.

LVM_GETCOLUMN
    wParam = (WPARAM) (int) iCol;
    lParam = (LPARAM) (LPLVCOLUMN) pcol;

Parameters

iCol
Index of the column.
pcol
Address of an LVCOLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.
If the mask member specifies the LVCF_TEXT value, the pszText member must contain the address of the buffer that receives the item text and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETCOLUMNORDERARRAY

Retrieves the current left-to-right order of columns in a list-view control. You can send this message explicitly or use the ListView_GetColumnOrderArray macro.

LVM_GETCOLUMNORDERARRAY
    wParam = (WPARAM) (int) iCount;
    lParam = (LPARAM) lpiArray;

Parameters

iCount
Number of columns in the list-view control.
lpiArray
Address of an array of integers that receives the index values of the columns in the list-view control. The array must be large enough to hold iCount elements.

Return Values

If successful, returns nonzero, and the buffer at lpiArray receives the column index of each column in the control in the order they appear from left to right. Otherwise, the return value is zero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_GETCOLUMNWIDTH

Retrieves the width of a column in report or list view. You can send this message explicitly or by using the ListView_GetColumnWidth macro.

LVM_GETCOLUMNWIDTH
    wParam = (WPARAM) (int) iCol;
    lParam = 0;

Parameters

iCol
Index of the column. This parameter is ignored in list view.

Return Values

Returns the column width if successful, or zero otherwise. If this message is sent to a list-view control with the LVS_REPORT style and the specified column doesn't exist, the return value is undefined.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETCOUNTPERPAGE

Calculates the number of items that can fit vertically in the visible area of a list-view control when in list or report view. Only fully visible items are counted. You can send this message explicitly or by using the ListView_GetCountPerPage macro.

LVM_GETCOUNTPERPAGE
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of fully visible items if successful. If the current view is icon or small icon view, the return value is the total number of items in the list-view control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETEDITCONTROL

Retrieves the handle to the edit control being used to edit a list-view item's text. You can send this message explicitly or by using the ListView_GetEditControl macro.

LVM_GETEDITCONTROL
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the edit control if successful, or NULL otherwise.

Remarks

When label editing begins, an edit control is created, positioned, and initialized. Before it is displayed, the list-view control sends its parent window an LVN_BEGINLABELEDIT notification message.

To customize label editing, implement a handler for LVN_BEGINLABELEDIT and have it send an LVM_GETEDITCONTROL message to the list-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, send the list-view control a WM_CANCELMODE message.

The list-view item being edited is the currently focused item—that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

See Also

ListView_GetEditControl

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


LVM_GETEXTENDEDLISTVIEWSTYLE

Retrieves the extended styles that are currently in use for a given list-view control. You can send this message explicitly or use the ListView_GetExtendedListViewStyle macro.

LVM_GETEXTENDEDLISTVIEWSTYLE
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD that represents the styles currently in use for a given list-view control. This value can be a combination of extended styles.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_GETGROUPINFO Message

This is preliminary documentation and is subject to change.

Retrieves group information.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETGROUPINFO,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (int) iGroupId;
   (LPARAM) lParam
  |     // = (LPARAM) (PLV_GROUP) pgrp;

);

Parameters

iGroupId
[in] Identifier (ID) that specifies the group whose information is retrieved.
pgrp
[in] Pointer an LV_GROUP structure that receives the retrieved information.

Return Value

Returns the ID of the group if successful, or -1 otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETGROUPMETRICS Message

This is preliminary documentation and is subject to change.

Retrieves the metrics of a group.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns nothing in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETGROUPMETRICS,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (WPARAM) wParam;
   (LPARAM) lParam
  |     // = (LPARAM) (PLVGROUPMETRICS) pGroupMetrics;

);

Parameters

wParam
[in] Must be NULL.
pGroupMetrics
[in] Pointer to an LVGROUPMETRICS structure that receives the retrieved metrics.

Return Value

The return value is not used.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETHEADER

Retrieves the handle to the header control used by the list-view control. You can send this message explicitly or use the ListView_GetHeader macro.

LVM_GETHEADER
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the header control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_GETHOTCURSOR

Retrieves the HCURSOR value used when the pointer is over an item while hot tracking is enabled. You can send this message explicitly or use the ListView_GetHotCursor macro.

LVM_GETHOTCURSOR
    wParam = 0;
    lParam = 0;

Return Values

Returns an HCURSOR value that is the handle to the cursor that the list-view control uses when hot tracking is enabled.

Remarks

A list-view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_GETHOTITEM

Retrieves the index of the hot item. You can send this message explicitly or use the ListView_GetHotItem macro.

LVM_GETHOTITEM
    wParam = 0;
    lParam = 0;

Return Values

Returns the index of the item that is hot.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_GETHOVERTIME

Retrieves the amount of time that the mouse cursor must hover over an item before it is selected. You can send this message explicitly or use the ListView_GetHoverTime macro.

LVM_GETHOVERTIME
    wParam = 0;
    lParam = 0;

Return Values

Returns the amount of time, in milliseconds, that the mouse cursor must hover over an item before it is selected. If the return value is (DWORD)-1, then the hover time is the default hover time.

Remarks

The hover time only affects list-view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list-view style.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_GETIMAGELIST

Retrieves the handle to an image list used for drawing list-view items. You can send this message explicitly or by using the ListView_GetImageList macro.

LVM_GETIMAGELIST
    wParam = (WPARAM) (int) iImageList;
    lParam = 0;

Parameters

iImageList
Image list to retrieve. This parameter can be one of the following values:
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.

Return Values

Returns the handle to the specified image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETINSERTMARK Message

This is preliminary documentation and is subject to change.

Retrieves the position of the insertion point.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETINSERTMARK,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (PLVINSERTMARK) plvim;

);

Parameters

wParam
[in] Must be zero.
plvim
[in] Pointer to a LVINSERTMARK structure that receives the position of the insertion point.

Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the cbSize member of the LVINSERTMARK structure does not equal the actual size of the structure.

Remarks

An insertion point can appear only if the list-view control is in icon view, small icon view, or tile view, and is not in group-view mode.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETINSERTMARKCOLOR Message

This is preliminary documentation and is subject to change.

Retrieves the color of the insertion point.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETINSERTMARKCOLOR,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = 0; not used, must be zero

);

Parameters

wParam
[in] Must be zero.
lParam
[in] Must be zero.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETINSERTMARKRECT Message

This is preliminary documentation and is subject to change.

Retrieves the rectangle that bounds the insertion point.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETINSERTMARKRECT,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (LPRECT) rc;

);

Parameters

wParam
[in] Not used; must be zero.
rc
[in] Pointer to a RECT structure that contains the coordinates of a rectangle that bounds the insertion point.

Return Value

Returns TRUE if there is an insertion point, or FALSE otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETISEARCHSTRING

Retrieves the incremental search string of a list-view control. You can send this message explicitly or by using the ListView_GetISearchString macro.

LVM_GETISEARCHSTRING
    wParam = 0;
    lParam = (LPARAM) (LPSTR) lpsz;

Parameters

lpsz
Address of a buffer that receives the incremental search string. To just retrieve the length of the string, set lpsz to NULL.

Return Values

Returns the number of characters in the incremental search string, or zero if the list-view control is not in incremental search mode.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A time-out period is associated with each character that the user types. If the time-out period elapses before the user types another character, the incremental search string is reset.

Make sure that the buffer is large enough to hold the string. If it is too small, an immediate invalid page fault will result.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETITEM

Retrieves some or all of a list-view item's attributes. You can send this message explicitly or by using the ListView_GetItem macro.

LVM_GETITEM
    wParam = 0;
    lParam = (LPARAM) (LPLVITEM) pitem;

Parameters

pitem
Address of an LVITEM structure that specifies the information to retrieve and receives information about the list-view item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the LVM_GETITEM message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LVITEM structure.

If the LVIF_TEXT flag is set in the mask member of the LVITEM structure, the pszText member must point to a valid buffer and the cchTextMax member must be set to the number of characters in that buffer. Applications should not assume that the text will necessarily be placed in the specified buffer. The control may instead change the pszText member of the structure to point to the new text, rather than place it in the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


LVM_GETITEMCOUNT

Retrieves the number of items in a list-view control. You can send this message explicitly or by using the ListView_GetItemCount macro.

LVM_GETITEMCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETITEMPOSITION

Retrieves the position of a list-view item. You can send this message explicitly or by using the ListView_GetItemPosition macro.

LVM_GETITEMPOSITION
    wParam = (WPARAM) (int) i;
    lParam = (LPARAM) (POINT FAR *) ppt;

Parameters

i
Index of the list-view item.
ppt
Address of a POINT structure that receives the position of the item's upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETITEMRECT

Retrieves the bounding rectangle for all or part of an item in the current view. You can send this message explicitly or by using the ListView_GetItemRect macro.

LVM_GETITEMRECT
    wParam = (WPARAM) (int) i;
    lParam = (LPARAM) (LPRECT) prc;

Parameters

i
[in] Index of the list-view item.
prc
[in/out] Address of a RECT structure that receives the bounding rectangle. When the message is sent, the left member of this structure is used to specify the portion of the list-view item from which to retrieve the bounding rectangle. It must be set to one of the following values:
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL | Returns the bounding rectangle of the item text.
LVIR_SELECTBOUNDS | Returns the union of the LVIR_ICON and LVIR_LABEL rectangles, but excludes columns in report view.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETITEMSPACING

Determines the spacing between items in a list-view control. You can send this message explicitly or by using the ListView_GetItemSpacing macro.

LVM_GETITEMSPACING
    wParam = (WPARAM) (BOOL) fSmall;
    lParam = 0;

Parameters

fSmall
View for which to retrieve the item spacing. This parameter is TRUE for small icon view, or FALSE for icon view.

Return Values

Returns the amount of spacing between items. The horizontal spacing is contained in the low-order WORD and the vertical spacing is contained in the high-order WORD.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETITEMSTATE

Retrieves the state of a list-view item. You can send this message explicitly or by using the ListView_GetItemState macro.

LVM_GETITEMSTATE
    wParam = (WPARAM) (int) i;
    lParam = (LPARAM) (UINT) mask;

Parameters

i
Index of the list-view item.
mask
State information to retrieve. This parameter can be a combination of the following values:
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.
LVIS_OVERLAYMASK | Use this mask to retrieve the item's overlay image index.
LVIS_STATEIMAGEMASK | Use this mask to retrieve the item's state image index.

Return Values

Returns the current state for the specified item. The only valid bits in the return value are those that correspond to the bits set in the mask parameter.

Remarks

An item's state information includes a set of bit flags as well as image list indexes that indicate the item's state image and overlay image.

See Also

LVM_SETITEMSTATE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETITEMTEXT

Retrieves the text of a list-view item or subitem. You can send this message explicitly or by using the ListView_GetItemText macro.

LVM_GETITEMTEXT
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (LPLVITEM) pitem;

Parameters

iItem
Index of the list-view item.
pitem
Address of an LVITEM structure. To retrieve the item text, set iSubItem to zero. To retrieve the text of a subitem, set iSubItem to the subitem's index. The pszText member points to a buffer that receives the text. The cchTextMax member specifies the number of characters in the buffer.

Return Values

If you send this message explicitly, it returns the number of characters in the pszText member of the LVITEM structure.

Remarks

You can also send this message by calling the ListView_GetItemText macro. However, this macro does not return the string length.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETNEXTITEM

Searches for a list-view item that has the specified properties and bears the specified relationship to a specified item. You can send this message explicitly or by using the ListView_GetNextItem macro.

LVM_GETNEXTITEM
    wParam = (WPARAM) (int) iStart;
    lParam = MAKELPARAM((UINT) flags, 0);

Parameters

iStart
Index of the item to begin the search with, or -1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.
flags
Specifies the relationship to the item specified in iStart. This can be one or a combination of the following values:

LVNI_ALL Searches for a subsequent item by index (the default value).

The physical relationship to iStart can be specified with one of the following values:
LVNI_ABOVE | Searches for an item that is above the specified item.
LVNI_BELOW | Searches for an item that is below the specified item.
LVNI_TOLEFT | Searches for an item to the left of the specified item.
LVNI_TORIGHT | Searches for an item to the right of the specified item.

The state of the item to find can be specified with one or a combination of the following values:
LVNI_CUT | The item has the LVIS_CUT state flag set.
LVNI_DROPHILITED | The item has the LVIS_DROPHILITED state flag set.
LVNI_FOCUSED | The item has the LVIS_FOCUSED state flag set.
LVNI_SELECTED | The item has the LVIS_SELECTED state flag set.

If an item does not have all of the specified state flags set, the search continues with the next item.

Return Values

Returns the index of the next item if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETNUMBEROFWORKAREAS

Retrieves the number of working areas in a list-view control. You can send this message explicitly or use the ListView_GetNumberOfWorkAreas macro.

LVM_GETNUMBEROFWORKAREAS
    wParam = 0;
    lParam = (LPARAM)(LPUINT) lpuWorkAreas;

Parameters

lpuWorkAreas
Address of a UINT value that receives the number of working areas in the list-view control. If zero is placed in this variable, then no working areas are currently set. This value cannot be NULL.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_GETORIGIN

Retrieves the current view origin for a list-view control. You can send this message explicitly or by using the ListView_GetOrigin macro.

LVM_GETORIGIN
    wParam = 0;
    lParam = (LPARAM) (LPPOINT) lpptOrg;

Parameters

lpptOrg
Address of a POINT structure that receives the view origin.

Return Values

Returns TRUE if successful, or FALSE if the current view is list or report view.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETSELECTEDCOUNT

Determines the number of selected items in a list-view control. You can send this message explicitly or by using the ListView_GetSelectedCount macro.

LVM_GETSELECTEDCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of selected items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETSELECTIONMARK

Retrieves the selection mark from a list-view control. You can send this message explicitly or use the ListView_GetSelectionMark macro.

LVM_GETSELECTIONMARK
    wParam = 0;
    lParam = 0;

Return Values

Returns the zero-based selection mark, or -1 if there is no selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts.

See Also

LVM_SETSELECTIONMARK

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_GETSTRINGWIDTH

Determines the width of a specified string using the specified list-view control's current font. You can send this message explicitly or by using the ListView_GetStringWidth macro.

LVM_GETSTRINGWIDTH
    wParam = 0;
    lParam = (LPARAM) (LPCSTR) psz;

Parameters

psz
Address of a null-terminated string.

Return Values

Returns the string width if successful, or zero otherwise.

Remarks

The LVM_GETSTRINGWIDTH message returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in the LVM_SETCOLUMNWIDTH message, the string will be truncated. To retrieve the column width that can contain the string without truncating it, you must add padding to the returned string width.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETSUBITEMRECT

Retrieves information about the bounding rectangle for a subitem in a list-view control. You can send this message explicitly or by using the ListView_GetSubItemRect macro (recommended). This message is intended to be used only with list-view controls that use the LVS_REPORT style.

LVM_GETSUBITEMRECT
    wParam = (WPARAM)(int) iItem;
    lParam = (LPARAM)(LPRECT) lpRect;

Parameters

iItem
Index of the subitem's parent item.
lpRect
Address of a RECT structure that will receive the subitem bounding rectangle information. Its members must be initialized according to the following member/value relationships:
Member | Value
top | The one-based index of the subitem.
left | Flag value (see following). Indicates the portion of the list-view subitem for which to retrieve the bounding rectangle.
Flag Value | Meaning
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL | Returns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_GETTEXTBKCOLOR

Retrieves the text background color of a list-view control. You can send this message explicitly or by using the ListView_GetTextBkColor macro.

LVM_GETTEXTBKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns the background color of the text.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETTEXTCOLOR

Retrieves the text color of a list-view control. You can send this message explicitly or by using the ListView_GetTextColor macro.

LVM_GETTEXTCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns the text color.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETTILEINFO Message

This is preliminary documentation and is subject to change.

Retrieves information about a tile in a list-view control.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETTILEINFO,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (LVTILEINFO) lvtinfo;

);

Parameters

wParam
[in] Must be zero.
lvtinfo
[in] LVTILEINFO structure that receives the retrieved information.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Tile view is a new way of arranging and displaying items in a list-view control. The other views are icon, small icon, details, and list.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETTILEVIEWINFO Message

This is preliminary documentation and is subject to change.

Retrieves information about a list-view control in tile view.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_GETTILEVIEWINFO,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (LVTILEVIEWINFO) lvtvinfo;

);

Parameters

wParam
[in] Must be zero.
lvtvinfo
[in] LVTILEVIEWINFO structure that receives the retrieved information.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Tile view is a new way of arranging and displaying items in a list-view control. The other views are icon, small icon, details, and list.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_GETTOOLTIPS

Retrieves the ToolTip control that the list-view control uses to display ToolTips. You can send this message explicitly or use the ListView_GetToolTips macro.

LVM_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle of the ToolTip control.

See Also

LVM_SETTOOLTIPS

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETTOPINDEX

Retrieves the index of the topmost visible item when in list or report view. You can send this message explicitly or by using the ListView_GetTopIndex macro.

LVM_GETTOPINDEX
    wParam = 0;
    lParam = 0;

Return Values

Returns the index of the item if successful, or zero if the list-view control is in icon or small icon view.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the ListView_GetUnicodeFormat macro.

LVM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

LVM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETVIEWRECT

Retrieves the bounding rectangle of all items in the list-view control. The list view must be in icon or small icon view. You can send this message explicitly or by using the ListView_GetViewRect macro.

LVM_GETVIEWRECT
    wParam = 0;
    lParam = (LPARAM) (RECT FAR *) prc;

Parameters

prc
Address of a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list-view control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_GETWORKAREAS

Retrieves the working areas from a list-view control. You can send this message explicitly or use the ListView_GetWorkAreas macro.

LVM_GETWORKAREAS
    wParam = (WPARAM)(INT) nWorkAreas;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

nWorkAreas
The number of RECT structures in the array at lprc.
lprc
Address of an array of RECT structures that receive the current working areas of the list-view control. Values in these structures are in client coordinates. nWorkAreas specifies the number of structures in this array.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_HASGROUP Message

This is preliminary documentation and is subject to change.

Determines whether the list-view control has a specified group.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_HASGROUP,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (int) dwGroupId;
   (LPARAM) lParam
  |     // = (LPARAM) (LPARAM) lParam;

);

Parameters

dwGroupId
[in] Identifier (ID) of the group.
lParam
[in] Must be NULL.

Return Value

Returns TRUE if the list-view control has the specified group, or FALSE otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_HITTEST

Determines which list-view item, if any, is at a specified position. You can send this message explicitly or by using the ListView_HitTest macro.

LVM_HITTEST
    wParam = 0;
    lParam = (LPARAM) (LPLVHITTESTINFO) pinfo;

Parameters

pinfo
Address of an LVHITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

Return Values

Returns the index of the item at the specified position, if any, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_INSERTCOLUMN

Inserts a new column in a list-view control. You can send this message explicitly or by using the ListView_InsertColumn macro.

LVM_INSERTCOLUMN
    wParam = (WPARAM) (int) iCol;
    lParam = (LPARAM) (const LPLVCOLUMN) pcol;

Parameters

iCol
Index of the new column.
pcol
Address of an LVCOLUMN structure that contains the attributes of the new column.

Return Values

Returns the index of the new column if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_INSERTGROUP Message

This is preliminary documentation and is subject to change.

Inserts a group into a list-view control.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_INSERTGROUP,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (int) index;
   (LPARAM) lParam
  |     // = (LPARAM) (PLV_GROUP) pgrp;

);

Parameters

index
[in] Index of the item where the group is to be added.
pgrp
[in] Pointer to a LV_GROUP structure that contains the group to add.

Return Value

Returns the index of the item that the group was added to, or -1 if the operation failed.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_INSERTGROUPSORTED Message

This is preliminary documentation and is subject to change.

Inserts a sorted group.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns nothing in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_INSERTGROUPSORTED,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (LVINSERTGROUPSORTED) structInsert;
   (LPARAM) lParam
  |     // = (LPARAM) (LPARAM) lParam;

);

Parameters

structInsert
[in] Pointer to an LVINSERTGROUPSORTED structure that contains the sorted group to insert.
lParam
[in] Must be NULL.

Return Value

The return value is not used.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_INSERTITEM

Inserts a new item in a list-view control. You can send this message explicitly or by using the ListView_InsertItem macro.

LVM_INSERTITEM
    wParam = 0;
    lParam = (LPARAM) (const LPLVITEM) pitem;

Parameters

pitem
Address of an LVITEM structure that specifies the attributes of the list-view item. Use the iItem member to specify the zero-based index at which the new item should be inserted. If this value is greater than the number of items currently contained by the listview, the new item will be appended to the end of the list and assigned the correct index. Examine the message's return value to determine the actual index assigned to the item.

Return Values

Returns the index of the new item if successful, or -1 otherwise.

Remarks

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems. The iSubItem member of the LVITEM structure must be zero.

If a list-view control has the LVS_EX_CHECKBOX style set, any value placed in bits 12 through 15 of the state member of the LVITEM structure will be ignored. When an item is added with this style set, it will always be set to the unchecked state.

If a list-view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its .

The LVM_INSERTITEM message will insert the new item in the proper position in the sort order if the following conditions hold:

  • You are using one of the LVS_SORTXXX styles.
  • You are not using the LVS_OWNERDRAW style.
  • The pszText member of the structure pointed to by pitem is not set to LPSTR_TEXTCALLBACK.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


LVM_INSERTMARKHITTEST Message

This is preliminary documentation and is subject to change.

Retrieves the insertion point closest to a specified point.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_INSERTMARKHITTEST,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (LPPOINT) point;
   (LPARAM) lParam
  |     // = (LPARAM) (PLVINSERTMARK) plvim;

);

Parameters

point
[in] Pointer to a POINT structure that contains the hit test coordinates.
plvim
[in] Pointer to an LVINSERTMARK structure that specifies the insertion point closest to the coordinates defined by the point parameter.

Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the cbSize member of the LVINSERTMARK structure does not equal the actual size of the structure, or when an insertion point does not apply in the current view.

Remarks

An insertion point can only appear if the list-view control is in icon view, small icon view, or tile view and is not in group-view mode.

If insertion points do not apply for the view, the LVINSERTMARK structure contains a -1 in the iItem member.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_REDRAWITEMS

Forces a list-view control to redraw a range of items. You can send this message explicitly or by using the ListView_RedrawItems macro.

LVM_REDRAWITEMS
    wParam = (int) iFirst;
    lParam = (int) iLast;

Parameters

iFirst
Index of the first item to redraw.
iLast
Index of the last item to redraw.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The specified items are not actually redrawn until the list-view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_REMOVEALLGROUPS Message

This is preliminary documentation and is subject to change.

Removes all groups from a list-view control.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns nothing in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_REMOVEALLGROUPS,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (WPARAM) wParam;
   (LPARAM) lParam
  |     // = (LPARAM) (LPARAM) lParam;

);

Parameters

wParam
[in] Must be NULL.
lParam
[in] Must be NULL.

Return Value

The return value is not used.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_REMOVEGROUP Message

This is preliminary documentation and is subject to change.

Removes a group from a list-view control.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_REMOVEGROUP,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (int) iGroundId;
   (LPARAM) lParam
  |     // = (LPARAM) (LPARAM) lParam;

);

Parameters

iGroundId
[in] Identifier (ID) that specifies the group to remove.
lParam
[in] Must be NULL.

Return Value

Returns the index of the group if successful, or -1 otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SCROLL

Scrolls the content of a list-view control. You can send this message explicitly or by using the ListView_Scroll macro.

LVM_SCROLL
    wParam = (int) dx;
    lParam = (int) dy;

Parameters

dx
Integer value that specifies the amount of horizontal scrolling in pixels. If the list-view control is in list-view, this value specifies the number of columns to scroll.
dy
Integer value that specifies the amount of vertical scrolling in pixels.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the list-view control is in report view, the control can only be scrolled vertically in whole line increments. Therefore, the dy parameter will be rounded to the nearest number of pixels that form a whole line increment. For example, if the height of a line is 16 pixels and 8 is passed for dy, the list will be scrolled by 16 pixels (1 line). If 7 is passed for dy, the list will be scrolled 0 pixels (0 lines).

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETBKCOLOR

Sets the background color of a list-view control. You can send this message explicitly or by using the ListView_SetBkColor macro.

LVM_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM) (COLORREF) clrBk;

Parameters

clrBk
Background color to set or the CLR_NONE value for no background color. List-view controls with background colors redraw themselves significantly faster than those without background colors.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETBKIMAGE

Sets the background image in a list-view control. You can send this message explicitly or by using the ListView_SetBkImage macro.

LVM_SETBKIMAGE
    wParam = 0;
    lParam = (LPARAM)(LPLVBKIMAGE) plvbki;

Parameters

plvbki
Address of a LVBKIMAGE structure that contains the new background image information.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

Because the list-view control uses OLE COM to manipulate the background images, the calling application must call CoInitialize or OleInitialize before sending this message. It is best to call one of these functions when the application is initialized and call either CoUninitialize or OleUninitialize when the application is terminating.

See Also

LVM_GETBKIMAGE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_SETCALLBACKMASK

Changes the callback mask for a list-view control. You can send this message explicitly or by using the ListView_SetCallbackMask macro.

LVM_SETCALLBACKMASK
    wParam = (WPARAM) (UINT) mask;
    lParam = 0;

Parameters

mask
Value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. This value can be any combination of the following constants:
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus.
LVIS_SELECTED | The item is selected.
LVIS_OVERLAYMASK | The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK | The application stores the image list index of the current state image for each item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The callback mask of a list-view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control's items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list-view control stores all item state information. After creating a list-view control and initializing its items, you can send the LVM_SETCALLBACKMASK message to change the callback mask. To retrieve the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information about overlay images and state images, see Adding List-View Image Lists.

For more information on list-view callbacks, see Callback Items and the Callback Mask.

See Also

LVN_GETDISPINFO

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETCOLUMN

Sets the attributes of a list-view column. You can send this message explicitly or by using the ListView_SetColumn macro.

LVM_SETCOLUMN
    wParam = (WPARAM) (int) iCol;
    lParam = (LPARAM) (const LPLVCOLUMN) pcol;

Parameters

iCol
Index of the column.
pcol
Address of an LVCOLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.
If the mask member specifies the LVCF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETCOLUMNORDERARRAY

Sets the left-to-right order of columns in a list-view control. You can send this message explicitly or use the ListView_SetColumnOrderArray macro.

LVM_SETCOLUMNORDERARRAY
    wParam = (WPARAM) (int) iCount;
    lParam = (LPARAM) (LPINT) lpiArray;

Parameters

iCount
Size, in elements, of the buffer at lpiArray.
lpiArray
Address of an array that specifies the order in which columns should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays column 2, column 0, and column 1 in that order.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_SETCOLUMNWIDTH

Changes the width of a column in report-view mode or the width of all columns in list-view mode. You can send this message explicitly or use the ListView_SetColumnWidth macro.

LVM_SETCOLUMNWIDTH
    wParam = (WPARAM) (int) iCol;
    lParam = MAKELPARAM((int) cx, 0);

Parameters

iCol
Zero-based index of a valid column. For list-view mode, this parameter must be set to zero.
cx
New width of the column, in pixels. For report-view mode, the following special values are supported:
LVSCW_AUTOSIZE | Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER | Automatically sizes the column to fit the header text. If you use this value with the last column, its width is set to fill the remaining width of the list-view control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Assume that you have a 2-column list-view control with a width of 500 pixels. If the width of column zero is set to 200 pixels, and you send this message with wParam = 1 and lParam = LVSCW_AUTOSIZE_USEHEADER, the second (and last) column will be 300 pixels wide.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETEXTENDEDLISTVIEWSTYLE

Sets extended styles in list-view controls. You can send this message explicitly or use the ListView_SetExtendedListViewStyle or ListView_SetExtendedListViewStyleEx macro.

LVM_SETEXTENDEDLISTVIEWSTYLE
    wParam = (WPARAM)dwExMask;
    lParam = (LPARAM)dwExStyle;

Parameters

dwExMask
DWORD value that specifies which styles in dwExStyle are to be affected. This parameter can be a combination of extended styles. Only the extended styles in dwExMask will be changed. All other styles will be maintained as they are. If this parameter is zero, all of the styles in dwExStyle will be affected.
dwExStyle
DWORD value that specifies the extended list-view control style. This parameter can be a combination of extended styles.

Return Values

Returns a DWORD value that contains the previous extended list-view control styles.

Remarks

The dwExMask parameter allows you to modify one or more extended styles without having to retrieve the existing styles first. For example, if you pass LVS_EX_FULLROWSELECT for dwExMask and 0 for dwExStyle, the LVS_EX_FULLROWSELECT style will be cleared but all other styles will remain the same.

For backward compatibility reasons, the ListView_SetExtendedListViewStyle macro has not been updated to use dwExMask. To use the dwExMask value, use the ListView_SetExtendedListViewStyleEx macro.

When you use this message to set the LVS_EX_CHECKBOXES style, any previously set state image index will be discarded. All check boxes will be initialized to the unchecked state. The state image index is contained in bits 12 through 15 of the state member of the LVITEM structure.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_SETGROUPINFO Message

This is preliminary documentation and is subject to change.

Sets group information.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SETGROUPINFO,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (int) iGroupId;
   (LPARAM) lParam
  |     // = (LPARAM) (PLV_GROUP) pgrp;

);

Parameters

iGroupId
[in] Identifier (ID) that specifies the group whose information is to be set.
pgrp
[in] Pointer to an LV_GROUP structure that contains the information to set.

Return Value

Returns the ID of the group if successful, or -1 otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SETGROUPMETRICS Message

This is preliminary documentation and is subject to change.

Sets the metrics of a group.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns nothing in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SETGROUPMETRICS,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (WPARAM) wParam;
   (LPARAM) lParam
  |     // = (LPARAM) (PLVGROUPMETRICS) pGroupMetrics;

);

Parameters

wParam
[in] Must be NULL.
pGroupMetrics
[in] Pointer to an LVGROUPMETRICS structure that contains the metrics to set.

Return Value

The return value is not used.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SETHOTCURSOR

Sets the HCURSOR value that the list-view control uses when the pointer is over an item while hot tracking is enabled. You can send this message explicitly or use the ListView_SetHotCursor macro. To check whether or not hot tracking is enabled, call SystemParametersInfo.

LVM_SETHOTCURSOR
    wParam = 0;
    lParam = (LPARAM)(HCURSOR) hCursor;

Parameters

hCursor
Handle to the cursor to be set.

Return Values

Returns an HCURSOR value that is the previous hot cursor.

Remarks

A list-view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_SETHOTITEM

Sets the hot item for a list-view control. You can send this message explicitly or use the ListView_SetHotItem macro.

LVM_SETHOTITEM
    wParam = (WPARAM)(INT) iIndex;
    lParam = 0;

Parameters

iIndex
Zero-based index of the item to be set as the hot item.

Return Values

Returns the index of the item that was previously hot.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_SETHOVERTIME

Sets the amount of time which the mouse cursor must hover over an item before it is selected. You can send this message explicitly or use the ListView_SetHoverTime macro.

LVM_SETHOVERTIME
    wParam = 0;
    lParam = (LPARAM)(DWORD)dwHoverTime;

Parameters

dwHoverTime
The new amount of time, in milliseconds, that the mouse cursor must hover over an item before it is selected. If this value is (DWORD)-1, then the hover time is set to the default hover time.

Return Values

Returns the previous hover time.

Remarks

The hover time only affects list-view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list-view style.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_SETICONSPACING

Sets the spacing between icons in list-view controls that have the LVS_ICON style. You can send this message explicitly or by using the ListView_SetIconSpacing macro.

LVM_SETICONSPACING
    wParam = 0;
    lParam = (LPARAM) MAKELONG(cx, cy);

Parameters

cx
Distance, in pixels, to set between icons on the x-axis. See Remarks.
cy
Distance, in pixels, to set between icons on the y-axis. See Remarks.

Return Values

Returns a DWORD value that contains the previous cx in the low word and the previous cy in the high word.

Remarks

Values for cx and cy are relative to the upper-left corner of an icon bitmap. Therefore, to set spacing between icons that do not overlap, the cx or cy values must include the size of the icon, plus the amount of empty space desired between icons. Values that do not include the width of the icon will result in overlaps.

When defining the icon spacing, cx and cy must set to 4 or larger. Smaller values will not yield the desired layout. To reset cx and cy to the default spacing, set the lParam value to -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_SETIMAGELIST

Assigns an image list to a list-view control. You can send this message explicitly or by using the ListView_SetImageList macro.

LVM_SETIMAGELIST
    wParam = (WPARAM) (int) iImageList;
    lParam = (LPARAM) (HIMAGELIST) himl;

Parameters

iImageList
Type of image list. This parameter can be one of the following values:
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.
himl
Handle to the image list to assign.

Return Values

Returns the handle to the image list previously associated with the control if successful, or NULL otherwise.

Remarks

The current image list will be destroyed when the list-view control is destroyed unless the LVS_SHAREIMAGELISTS style is set. If you use this message to replace one image list with another, your application must explicitly destroy all image lists other than the current one.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETINSERTMARK Message

This is preliminary documentation and is subject to change.

Sets the insertion point to the defined position.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SETINSERTMARK,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (PLVINSERTMARK) plvim;

);

Parameters

wParam
[in] Must be zero.
plvim
[in] Pointer to a LVINSERTMARK structure that specifies where to set the insertion point.

Return Value

Returns TRUE if successful, or FALSE otherwise. FALSE is returned if the size in the cbSize member of the LVINSERTMARK structure does not equal the actual size of the structure, or when an insertion point does not apply in the current view.

Remarks

An insertion point can only appear if the list-view control is in icon view, small icon view, or tile view, and is not in group-view mode.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SETINSERTMARKCOLOR Message

This is preliminary documentation and is subject to change.

Sets the color of the insertion point.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns COLORREF in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SETINSERTMARKCOLOR,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (COLORREF) color;

);

Parameters

wParam
[in] Must be zero.
color
[in] COLORREF structure that specifies the color to set the insertion point.

Return Value

Returns COLORREF structure set to the previous color.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SETITEM

Sets some or all of a list-view item's attributes. You can also send LVM_SETITEM to set the text of a subitem. You can send this message explicitly or by using the ListView_SetItem macro.

LVM_SETITEM
    wParam = 0;
    lParam = (LPARAM) (const LPLVITEM) pitem;

Parameters

pitem
Address of an LVITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.
If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change and the state member contains the values for those states.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

To set the attributes of a list-view item, set the iItem member of the LVITEM structure to the index of the item, and set the iSubItem member to zero. For an item, you can set the state, pszText, iImage, and lParam members of the LVITEM structure.

To set the text of a subitem, set the iItem and iSubItem members to indicate the specific subitem, and use the pszText member to specify the text. Alternatively, you can use the ListView_SetItemText macro to set the text of a subitem. You cannot set the state or lParam members for subitems because subitems do not have these attributes. In version 4.70 and later, you can set the iImage member for subitems. The subitem image will be displayed if the list-view control has the LVS_EX_SUBITEMIMAGES extended style. Previous versions will ignore the subitem image.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETITEMCOUNT

Causes the list-view control to allocate memory for the specified number of items or sets the virtual number of items in a virtual list-view control. This depends on how the list-view control was created. You can send this message explicitly or use the ListView_SetItemCount or ListView_SetItemCountEx macros.

LVM_SETITEMCOUNT
    wParam = (WPARAM) (int) cItems;
    lParam = (LPARAM) dwFlags;

Parameters

cItems
Number of items that the list-view control will ultimately contain.
dwFlags
Version 4.70. Values that specify the behavior of the list-view control after resetting the item count. This value can be a combination of the following:
LVSICF_NOINVALIDATEALL | The list-view control will not repaint unless affected items are currently in view.
LVSICF_NOSCROLL | The list-view control will not change the scroll position when the item count changes.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

If the list-view control was created without the LVS_OWNERDATA style, sending this message causes the control to allocate its internal data structures for the specified number of items. This prevents the control from having to allocate the data structures every time an item is added.

If the list-view control was created with the LVS_OWNERDATA style (a virtual list view), sending this message sets the virtual number of items that the control contains.

The dwFlags parameter is intended only for list-view controls that use the LVS_OWNERDATA and LVS_REPORT or LVS_LIST styles.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETITEMPOSITION

Moves an item to a specified position in a list-view control (must be in icon or small icon view). You can send this message explicitly or by using the ListView_SetItemPosition macro.

LVM_SETITEMPOSITION
    wParam = (LPARAM) (int) i;
    lParam = MAKELPARAM((int) x, (int) y);

Parameters

i
Index of the list-view item.
x and y
New position of the item's upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the list-view control has the LVS_AUTOARRANGE style, the items in the list-view control are arranged after the position of the item is set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETITEMPOSITION32

Moves an item to a specified position in a list-view control (must be in icon or small icon view). This message differs from the LVM_SETITEMPOSITION message in that it uses 32-bit coordinates. You can send this message explicitly or by using the ListView_SetItemPosition32 macro.

LVM_SETITEMPOSITION32
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (LPPOINT) lpptNewPos;

Parameters

iItem
Index of the list-view item for which to set the position.
lpptNewPos
Address of a POINT structure that contains the new position of the item, in list-view coordinates.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETITEMSTATE

Changes the state of an item in a list-view control. You can send this message explicitly or by using the ListView_SetItemState macro.

LVM_SETITEMSTATE
    wParam = (WPARAM) (int) i;
    lParam = (LPARAM) (LPLVITEM) pitem;

Parameters

i
Index of the list-view item.
If this parameter is -1, then the state change is applied to all items.
pitem
Address of an LVITEM structure. The stateMask member specifies which state bits to change, and the state member contains the new values for those bits. The other members are ignored.

Return Values

If you send this message explicitly, it returns TRUE if successful or FALSE otherwise.

Remarks

An item's state value includes a set of bit flags that indicate the item's state. The state value can also include image list indexes that indicate the item's state image and overlay image.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETITEMTEXT

Changes the text of a list-view item or subitem. You can send this message explicitly or by using the ListView_SetItemText macro.

LVM_SETITEMTEXT
    wParam = (WPARAM) (int) i;
    lParam = (LPARAM) (LPLVITEM) pitem;

Parameters

i
Index of the list-view item.
pitem
Address of an LVITEM structure. The iSubItem member is the index of the subitem, or it can be zero to set the item label. The pszText member is the address of a null-terminated string containing the new text; it can also be NULL.

The pszText member can also be LPSTR_TEXTCALLBACK to indicate a callback item for which the parent window stores the text. In this case, the list-view control sends the parent an LVN_GETDISPINFO notification message when it needs the text.

Return Values

If you send this message explicitly, it returns TRUE if successful or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETSELECTIONMARK

Sets the selection mark in a list-view control. You can send this message explicitly or use the ListView_SetSelectionMark macro.

LVM_SETSELECTIONMARK
    wParam = 0;
    lParam = (LPARAM)(INT) iIndex;

Parameters

iIndex
Zero-based index of the new selection mark.

Return Values

Returns the previous selection mark, or -1 if there is no previous selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts. This message does not affect the selection state of the item.

See Also

LVM_GETSELECTIONMARK

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_SETTEXTBKCOLOR

Sets the background color of text in a list-view control. You can send this message explicitly or by using the ListView_SetTextBkColor macro.

LVM_SETTEXTBKCOLOR
    wParam = 0;
    lParam = (LPARAM) (COLORREF) clrText;

Parameters

clrText
New text color.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETTEXTCOLOR

Sets the text color of a list-view control. You can send this message explicitly or by using the ListView_SetTextColor macro.

LVM_SETTEXTCOLOR
    wParam = 0;
    lParam = (LPARAM) (COLORREF) clrText;

Parameters

clrText
New text color.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETTILEINFO Message

This is preliminary documentation and is subject to change.

Sets information for a tile of a list-view control.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SETTILEINFO,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (LVTILEINFO) lvtinfo;

);

Parameters

wParam
[in] Must be zero.
lvtinfo
[in] LVTILEINFO structure that contains the information to set.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Tile view is a new way of arranging and displaying items in a list-view control. The other views are icon, small icon, details, and list.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SETTILEVIEWINFO Message

This is preliminary documentation and is subject to change.

Sets information that a list-view control uses in tile view.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SETTILEVIEWINFO,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = (LPARAM) (LVTILEVIEWINFO) lvtvinfo;

);

Parameters

wParam
[in] Must be zero.
lvtvinfo
[in] LVTILEVIEWINFO structure that contains the information to set.

Return Value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Tile view is a new way of arranging and displaying items in a list-view control. The other views are icon, small icon, details, and list.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SETTOOLTIPS

Sets the ToolTip control that the list-view control will use to display ToolTips. You can send this message explicitly or use the ListView_SetToolTips macro.

LVM_SETTOOLTIPS
    wParam = 0;
    lParam = (LPARAM)(HWND)hwndToolTip;

Parameters

hwndToolTip
Handle to the ToolTip control to be set.

Return Values

Returns the handle to the previous ToolTip control.

See Also

LVM_GETTOOLTIPS

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the ListView_SetUnicodeFormat macro.

LVM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

LVM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SETWORKAREAS

Sets the working areas within a list-view control. You can send this message explicitly or use the ListView_SetWorkAreas macro.

LVM_SETWORKAREAS
    wParam = (WPARAM)(INT) nWorkAreas;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

nWorkAreas
The number of structures in the array at lprc. The maximum number of working areas allowed is defined by the LV_MAX_WORKAREAS value.
lprc
Address of an array of RECT structures that contain the new working areas of the list-view control. Values in these structures are in client coordinates. If this parameter is NULL, the working area will be set to the client area of the control. nWorkAreas specifies the number of structures in this array.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVM_SORTGROUPS Message

This is preliminary documentation and is subject to change.

Sorts a group.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LVM_SORTGROUPS,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) (PFNLVGROUPCOMPARE) pfnGroupCompare;
   (LPARAM) lParam
  |     // = (LPARAM) (LPVOID) plv;

);

Parameters

pfnGroupCompare
[in] Pointer to a comparison function.
plv
[in] Void pointer.

Return Value

Returns 1 if successful, or 0 otherwise.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LVM_SORTITEMS

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence. You can send this message explicitly or by using the ListView_SortItems macro.

LVM_SORTITEMS
    wParam = (WPARAM) (LPARAM) lParamSort;
    lParam = (LPARAM) (PFNLVCOMPARE) pfnCompare;

Parameters

lParamSort
Application-defined value that is passed to the comparison function.
pfnCompare
Address of the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
LPARAM lParamSort);

The lParam1 parameter is the 32-bit value associated with the first item being compared, and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items' LVITEM structure when they were inserted into the list. The ListView_SortItem's lParamSort parameter is passed to the callback function as its third parameter.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

Note: During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control, the results are unpredictable.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVM_SORTITEMSEX

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence. You can send this message explicitly or by using the ListView_SortItemsEx macro.

LVM_SORTITEMSEX
    wParam = (WPARAM) (LPARAM) lParamSort;
    lParam = (LPARAM) (PFNLVCOMPARE) pfnCompare;

Parameters

lParamSort
Application-defined value that is passed to the comparison function.
pfnCompare
Address of an application-defined comparison function. It is called during the sort operation each time the relative order of two list items needs to be compared.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
LPARAM lParamSort);

This message is similar to LVM_SORTITEMS, except for the type of information passed to the comparison function. With LVM_SORTITEMSEX, lParam1 is the current index of the first item, and lParam2 is the current index of the second item. You can send an LVM_GETITEMTEXT message to retrieve more information on an item, if needed.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

Note: During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control aside from LVM_GETITEM (ListView_GetItem), the results are unpredictable.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


LVM_SUBITEMHITTEST

Determines which list-view item or subitem is at a given position. You can send this message explicitly or by using the ListView_SubItemHitTest macro.

LVM_SUBITEMHITTEST
    wParam = 0;
    lParam = (LPARAM)(LVHITTESTINFO FAR *)pInfo;

Parameters

pInfo
Address of an LVHITTESTINFO structure. The POINT structure within LVHITTESTINFO should be set to the client coordinates to be hit-tested.

Return Values

Returns the index of the item or subitem tested, if any, or -1 otherwise. If an item or subitem is at the given coordinates, the fields of the LVHITTESTINFO structure will be filled with the applicable hit information.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVM_UPDATE

Updates a list-view item. If the list-view control has the LVS_AUTOARRANGE style, this macro causes the list-view control to be arranged. You can send this message explicitly or by using the ListView_Update macro.

LVM_UPDATE
    wParam = (WPARAM) iItem;
    lParam = 0;

Parameters

iItem
Index of the item to update.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_ApproximateViewRect

Calculates the approximate width and height required to display a given number of items. You can use this macro or send the LVM_APPROXIMATEVIEWRECT message explicitly.

DWORD ListView_ApproximateViewRect(
    hwndLV,
    cx,
    cy,
    iCount
);

Parameters

hwndLV
Handle to the list-view control.
cx and cy
The proposed dimensions of the control, in pixels. Either parameter can be -1 to allow the message to use the current width or height value.
iCount
Number of items to be displayed in the control. If this parameter is -1, the message uses the total number of items in the control.

Return Values

Returns a DWORD value that holds the approximate width and height needed to display the items, in pixels.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_Arrange

Arranges items in icon view. You can use this macro or send the LVM_ARRANGE message explicitly.

BOOL ListView_Arrange(
    HWND hwnd,
    UINT code
);

Parameters

hwnd
Handle to the list-view control.
code
Alignment. This can be one of the following values:
LVA_ALIGNLEFT | Aligns items along the left edge of the window.
LVA_ALIGNTOP | Aligns items along the top edge of the window.
LVA_DEFAULT | Aligns items according to the list-view control's current alignment styles (the default value).
LVA_SNAPTOGRID | Snaps all icons to the nearest grid position.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_CreateDragImage

Creates a drag image list for the specified item. You can use this macro or send the LVM_CREATEDRAGIMAGE message explicitly.

HIMAGELIST ListView_CreateDragImage(
    HWND hwnd,
    int iItem,
    LPPOINT lpptUpLeft
);

Parameters

hwnd
Handle to the list-view control.
iItem
Index of the item.
lpptUpLeft
Address of a POINT structure that receives the initial location of the upper-left corner of the image, in view coordinates.

Return Values

Returns the handle to the drag image list if successful, or NULL otherwise.

Remarks

Your application is responsible for destroying the image list when it is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_DeleteAllItems

Removes all items from a list-view control. You can use this macro or send the LVM_DELETEALLITEMS message explicitly.

BOOL ListView_DeleteAllItems(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a list-view control receives the LVM_DELETEALLITEMS message, it sends the LVN_DELETEALLITEMS notification message to its parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_DeleteColumn

Removes a column from a list-view control. You can use this macro or send the LVM_DELETECOLUMN message explicitly.

BOOL ListView_DeleteColumn(
    HWND hwnd,
    int iCol
);

Parameters

hwnd
Handle to the list-view control.
iCol
Index of the column to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Column zero of the list-view control cannot be deleted. If you must delete column zero, insert a zero length dummy column zero and delete column one and above.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_DeleteItem

Removes an item from a list-view control. You can use this macro or send the LVM_DELETEITEM message explicitly.

BOOL ListView_DeleteItem(
    HWND hwnd,
    int iItem
);

Parameters

hwnd
Handle to the list-view control.
iItem
Index of the list-view item to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_EditLabel

Begins in-place editing of the specified list-view item's text. The message implicitly selects and focuses the specified item. You can use this macro or send the LVM_EDITLABEL message explicitly.

HWND ListView_EditLabel(
    HWND hwnd,
    int iItem
);

Parameters

hwnd
Handle to the list-view control.
iItem
Index of the list-view item. To cancel editing, set iItem to -1.

Return Values

Returns the handle to the edit control that is used to edit the item text if successful, or NULL otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

See Also

WM_CANCELMODE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_EnsureVisible

Ensures that a list-view item is either entirely or partially visible, scrolling the list-view control if necessary. You can use this macro or send the LVM_ENSUREVISIBLE message explicitly.

BOOL ListView_EnsureVisible(
    HWND hwnd,
    int i,
    BOOL fPartialOK
);

Parameters

hwnd
Handle to the list-view control.
i
Index of the list-view item.
fPartialOK
Value specifying whether the item must be entirely visible. If this parameter is TRUE, no scrolling occurs if the item is at least partially visible.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_FindItem

Searches for a list-view item with the specified characteristics. You can use this macro or send the LVM_FINDITEM message explicitly.

int ListView_FindItem(
    HWND hwnd,
    int iStart,
    const LPLVFINDINFO plvfi
);

Parameters

hwnd
Handle to the list-view control.
iStart
Index of the item after which to begin the search, or -1 to start from the beginning.
plvfi
Address of an LVFINDINFO structure that contains information about what to search for.

Return Values

Returns the index of the item if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetBkColor

Retrieves the background color of a list-view control. You can use this macro or send the LVM_GETBKCOLOR message explicitly.

COLORREF ListView_GetBkColor(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the background color of the list-view control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetBkImage

Retrieves the background image in a list-view control. You can use this macro or send the LVM_GETBKIMAGE message explicitly.

BOOL ListView_GetBkImage(
    HWND hwndLV,
    LPLVBKIMAGE plvbki
);

Parameters

hwndLV
Handle to the list-view control.
plvbki
Address of a LVBKIMAGE structure that will receive the background image information.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

ListView_SetBkImage

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_GetCallbackMask

Retrieves the callback mask for a list-view control. You can use this macro or send the LVM_GETCALLBACKMASK message explicitly.

UINT ListView_GetCallbackMask(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the callback mask.

See Also

LVM_SETCALLBACKMASK

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetCheckState

Determines if an item in a list-view control is selected. This should be used only for list-view controls that have the LVS_EX_CHECKBOXES style.

BOOL ListView_GetCheckState(
    HWND hwndLV,
    UINT iIndex
);

Parameters

hwndLV
Handle to a list-view control.
iIndex
Index of the item for which to retrieve the check state.

Return Values

Returns nonzero if the given item is selected, or zero otherwise. If this macro is applied to a list-view control that does not have check boxes enabled, the return value is not reliable.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetColumn

Retrieves the attributes of a list-view control's column. You can use this macro or send the LVM_GETCOLUMN message explicitly.

BOOL ListView_GetColumn(
    HWND hwnd,
    int iCol,
    LPLVCOLUMN pcol
);

Parameters

hwnd
Handle to the list-view control.
iCol
Index of the column.
pcol
Address of an LVCOLUMN structure that specifies the information to retrieve and receives information about the column. The mask member specifies which column attributes to retrieve.
If the mask member specifies the LVCF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetColumnOrderArray

Retrieves the current left-to-right order of columns in a list-view control. You can use this macro or send the LVM_GETCOLUMNORDERARRAY message explicitly.

BOOL ListView_GetColumnOrderArray(
    HWND hwndLV,
    int iCount,
    int *lpiArray
);

Parameters

hwndLV
Handle to a list-view control.
iCount
Number of columns in the list-view control.
lpiArray
Address of an array of integers that will receive the index values of the columns in the list-view control. The array must be large enough to hold iCount elements.

Return Values

If successful, returns nonzero and the buffer at lpiArray receives the column index of each column in the control in the order they appear from left to right. Otherwise, the return value is zero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetColumnWidth

Retrieves the width of a column in report or list view. You can use this macro or send the LVM_GETCOLUMNWIDTH message explicitly.

int ListView_GetColumnWidth(
    HWND hwnd,
    int iCol
);

Parameters

hwnd
Handle to the list-view control.
iCol
Index of the column. This parameter is ignored in list view.

Return Values

Returns the column width if successful, or zero otherwise. If this macro is used on a list-view control with the LVS_REPORT style and the specified column doesn't exist, the return value is undefined.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetCountPerPage

Calculates the number of items that can fit vertically in the visible area of a list-view control when in list or report view. Only fully visible items are counted. You can use this macro or send the LVM_GETCOUNTPERPAGE message explicitly.

int ListView_GetCountPerPage(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the number of fully visible items if successful. If the current view is icon or small icon view, the return value is the total number of items in the list-view control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetEditControl

Retrieves the handle to the edit control being used to edit a list-view item's text. You can use this macro or send the LVM_GETEDITCONTROL message explicitly.

HWND ListView_GetEditControl(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the handle to the edit control if successful, or NULL otherwise.

Remarks

When label editing begins, an edit control is created, positioned, and initialized. Before it is displayed, the list-view control sends its parent window an LVN_BEGINLABELEDIT notification message.

To customize label editing, implement a handler for LVN_BEGINLABELEDIT and have it use ListView_GetEditControl to send an LVM_GETEDITCONTROL message to the list-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but you should not destroy it. To cancel editing, you can send the list-view control a WM_CANCELMODE message.

The list-view item being edited is the currently focused item—that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

See Also

LVM_GETEDITCONTROL

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


ListView_GetExtendedListViewStyle

Retrieves the extended styles that are currently in use for a given list-view control. You can use this macro or send the LVM_GETEXTENDEDLISTVIEWSTYLE message explicitly.

DWORD ListView_GetExtendedListViewStyle(
    HWND hwndLV
);

Parameters

hwndLV
Handle to a list-view control.

Return Values

Returns a DWORD value that represents the styles currently in use for a given list-view control. This can be a combination of extended styles.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetHeader

Retrieves the handle to the header control used by a list-view control. You can use this macro or send the LVM_GETHEADER message explicitly.

HWND ListView_GetHeader(
    HWND hwndLV
);

Parameters

hwndLV
Handle to a list-view control.

Return Values

Returns the handle to the header control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetHotCursor

Retrieves the HCURSOR used when the pointer is over an item while hot tracking is enabled. You can use this macro or send the LVM_GETHOTCURSOR message explicitly.

HCURSOR ListView_GetHotCursor(
    HWND hwndLV
);

Parameters

hwndLV
Handle to a list-view control.

Return Values

Returns an HCURSOR value that is the handle to the cursor that the list-view control uses when hot tracking is enabled.

Remarks

A list-view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetHotItem

Retrieves the index of the hot item. You can use this macro or send the LVM_GETHOTITEM message explicitly.

INT ListView_GetHotItem(
    HWND hwndLV
);

Parameters

hwndLV
Handle to a list-view control.

Return Values

Returns the index of the item that is currently hot.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetHoverTime

Retrieves the amount of time that the mouse cursor must hover over an item before it is selected. You can use this macro or send the LVM_GETHOVERTIME message explicitly.

DWORD ListView_GetHoverTime(
   HWND hwndLV
);

Parameters

hwndLV
Handle to a list-view control.

Return Values

Returns the amount of time, in milliseconds, that the mouse cursor must hover over an item before it is selected. If the return value is (DWORD)-1, then the hover time is the default hover time.

Remarks

The hover time only affects list-view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list-view style.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_GetImageList

Retrieves the handle to an image list used for drawing list-view items. You can use this macro or send the LVM_GETIMAGELIST message explicitly.

HIMAGELIST ListView_GetImageList(
    HWND hwnd,
    int iImageList
);

Parameters

hwnd
Handle to the list-view control.
iImageList
Image list to retrieve. This parameter can be one of the following values:
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.

Return Values

Returns the handle to the specified image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetISearchString

Retrieves the incremental search string of a list-view control. You can use this macro or send the LVM_GETISEARCHSTRING message explicitly.

BOOL ListView_GetISearchString(
    HWND hwnd,
    LPSTR lpsz
);

Parameters

hwnd
Handle to the list-view control.
lpsz
Address of a buffer that receives the incremental search string. To just retrieve the length of the string, set lpsz to NULL.

Return Values

Returns the number of characters in the incremental search string, or zero if the list-view control is not in incremental search mode.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A time-out period is associated with each character that the user types. If the time-out period elapses before the user types another character, the incremental search string is reset.

Make sure that the buffer is large enough to hold the string. If it is too small, an immediate invalid page fault will result.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetItem

Retrieves some or all of a list-view item's attributes. You can use this macro or send the LVM_GETITEM message explicitly.

BOOL ListView_GetItem(
    HWND hwnd,
    LPLVITEM pitem
);

Parameters

hwnd
Handle to the list-view control.
pitem
Address of an LVITEM structure that specifies the information to retrieve and receives information about the list-view item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the LVM_GETITEM message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LVITEM structure.

If the LVIF_TEXT flag is set in the mask member of the LVITEM structure, the pszText member must point to a valid buffer and the cchTextMax member must be set to the number of characters in that buffer. Applications should not assume that the text will necessarily be placed in the specified buffer. The control may instead change the pszText member of the structure to point to the new text rather than place it in the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


ListView_GetItemCount

Retrieves the number of items in a list-view control. You can use this macro or send the LVM_GETITEMCOUNT message explicitly.

int ListView_GetItemCount(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the number of items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetItemPosition

Retrieves the position of a list-view item. You can use this macro or explicitly send the LVM_GETITEMPOSITION message.

BOOL ListView_GetItemPosition(
    HWND hwnd,
    int i,
    POINT FAR *ppt
);

Parameters

hwnd
Handle to the list-view control.
i
Index of the list-view item.
ppt
Address of a POINT structure that receives the position of the item's upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetItemRect

Retrieves the bounding rectangle for all or part of an item in the current view. You can use this macro or send the LVM_GETITEMRECT message explicitly.

BOOL ListView_GetItemRect(
    HWND hwnd,
    int i,
    RECT FAR *prc,
    int code
);

Parameters

hwnd
[in] Handle to the list-view control.
i
[in] Index of the list-view item.
prc
[out] Address of a RECT structure that receives the bounding rectangle.
code
[in] Portion of the list-view item from which to retrieve the bounding rectangle. This parameter must be one of the following values:
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL | Returns the bounding rectangle of the item text.
LVIR_SELECTBOUNDS | Returns the union of the LVIR_ICON and LVIR_LABEL rectangles, but excludes columns in report view.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetItemSpacing

Determines the spacing between items in a list-view control. You can use this macro or send the LVM_GETITEMSPACING message explicitly.

DWORD ListView_GetItemSpacing(
    HWND hwnd,
    BOOL fSmall
);

Parameters

hwnd
Handle to the list-view control.
fSmall
View for which to retrieve the item spacing. This parameter is TRUE for small icon view, or FALSE for icon view.

Return Values

Returns the amount of spacing between items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetItemState

Retrieves the state of a list-view item. You can use this macro or send the LVM_GETITEMSTATE message explicitly.

UINT WINAPI ListView_GetItemState(
    HWND hwnd,
    int i,
    UINT mask
);

Parameters

hwnd
Handle to the list-view control.
i
Index of the list-view item.
mask
State information to retrieve. This parameter can be a combination of the following values:
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection.
LVIS_OVERLAYMASK | Use this mask to retrieve the item's overlay image index.
LVIS_STATEIMAGEMASK | Use this mask to retrieve the item's state image index.

Return Values

Returns the current state for the specified item. The only valid bits in the return value are those that correspond to the bits set in the mask parameter.

Remarks

An item's state information includes a set of bit flags as well as image list indexes that indicate the item's state image and overlay image.

See Also

ListView_SetItemState

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetItemText

Retrieves the text of a list-view item or subitem. You can use this macro or send the LVM_GETITEMTEXT message explicitly.

void ListView_GetItemText(
    HWND hwnd,
    int iItem,
    int iSubItem,
    LPTSTR pszText,
    int cchTextMax
);

Parameters

hwnd
Handle to the list-view control.
iItem
Index of the list-view item.
iSubItem
Index of the subitem. To retrieve the item text, set iSubItem to zero.
pszText
Pointer to a buffer that receives the item or subitem text.
cchTextMax
Number of characters in the pszText buffer.

Return Values

No return value. To get the length of the retrieved string, send the LVM_GETITEMTEXT message explicitly.

See Also

LVITEM

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetNextItem

Searches for a list-view item that has the specified properties and bears the specified relationship to a specified item. You can use this macro or send the LVM_GETNEXTITEM message explicitly.

int ListView_GetNextItem(
    HWND hwnd,
    int iStart,
    UINT flags
);

Parameters

hwnd
Handle to the list-view control.
iStart
Index of the item with which to begin the search, or -1 to find the first item that matches the specified flags. The specified item itself is excluded from the search.
flags
Geometric relation of the requested item to the specified item and, if specified, the state of the requested item. For a list of possible values, see the description of the flags parameter in the LVM_GETNEXTITEM message. If an item does not have all of the specified state flags set, the search continues with the next item.

Return Values

Returns the index of the next item if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetNumberOfWorkAreas

Retrieves the number of working areas in a list-view control. You can use this macro or send the LVM_GETNUMBEROFWORKAREAS message explicitly.

BOOL ListView_GetNumberOfWorkAreas(
    HWND hwndLV,
    LPUINT lpuWorkAreas
);

Parameters

hwndLV
Handle to the list-view control.
lpuWorkAreas
Address of a UINT value that receives the number of working areas in the list-view control. If zero is placed in this variable, then no working areas are currently set. This value cannot be NULL.

Return Values

The return value for this macro is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_GetOrigin

Retrieves the current view origin for a list-view control. You can use this macro or send the LVM_GETORIGIN message explicitly.

BOOL ListView_GetOrigin(
    HWND hwnd,
    LPPOINT lpptOrg
);

Parameters

hwnd
Handle to the list-view control.
lpptOrg
Address of a POINT structure that receives the view origin.

Return Values

Returns TRUE if successful, or FALSE if the current view is list or report view.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetSelectedCount

Determines the number of selected items in a list-view control. You can use this macro or send the LVM_GETSELECTEDCOUNT message explicitly.

UINT ListView_GetSelectedCount(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the number of selected items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetSelectionMark

Retrieves the selection mark from a list-view control. You can use this macro or explicitly send the LVM_GETSELECTIONMARK message.

INT ListView_GetSelectionMark(
    HWND hwndLV
);

Parameters

hwndLV
Handle to a list-view control.

Return Values

Returns the zero-based selection mark, or -1 if there is no selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts.

See Also

ListView_SetSelectionMark

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_GetStringWidth

Determines the width of a specified string using the specified list-view control's current font. You can use this macro or send the LVM_GETSTRINGWIDTH message explicitly.

int ListView_GetStringWidth(
    HWND hwnd,
    LPCSTR psz
);

Parameters

hwnd
Handle to the list-view control.
psz
Address of a null-terminated string.

Return Values

Returns the string width if successful, or zero otherwise.

Remarks

The ListView_GetStringWidth macro returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in a call to the ListView_SetColumnWidth macro, the string will be truncated. To retrieve the column width that can contain the string without truncating it, you must add padding to the returned string width.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetSubItemRect

Retrieves information about the rectangle that surrounds a subitem in a list-view control. You can use this macro (recommended) or send the LVM_GETSUBITEMRECT message explicitly. This macro is intended to be used only on list-view controls that use the LVS_REPORT style.

BOOL ListView_GetSubItemRect(
    HWND hwndLV,
    int iItem,
    int iSubItem,
    int code,
    LPRECT lpRect
);

Parameters

hwndLV
Handle to a list-view control.
iItem
Index of the subitem's parent item.
iSubItem
The one-based index of the subitem.
code
Portion of the list-view subitem for which to retrieve the bounding rectangle information. This value can be one of the following:
LVIR_BOUNDS | Returns the bounding rectangle of the entire item, including the icon and label.
LVIR_ICON | Returns the bounding rectangle of the icon or small icon.
LVIR_LABEL | Returns the bounding rectangle of the entire item, including the icon and label. This is identical to LVIR_BOUNDS.
lpRect
Address of a RECT structure that receives the subitem bounding rectangle information.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_GetTextBkColor

Retrieves the text background color of a list-view control. You can use this macro or send the LVM_GETTEXTBKCOLOR message explicitly.

COLORREF ListView_GetTextBkColor(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the background color of the text.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetTextColor

Retrieves the text color of a list-view control. You can use this macro or send the LVM_GETTEXTCOLOR message explicitly.

COLORREF ListView_GetTextColor(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the text color.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetToolTips

Retrieves the ToolTip control that the list-view control uses to display ToolTips. You can use this macro or send the LVM_GETTOOLTIPS message explicitly.

HWND ListView_GetToolTips(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the handle to the ToolTip control.

See Also

ListView_SetToolTips

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetTopIndex

Retrieves the index of the topmost visible item when in list or report view. You can use this macro or send the LVM_GETTOPINDEX message explicitly.

int ListView_GetTopIndex(
    HWND hwnd
);

Parameters

hwnd
Handle to the list-view control.

Return Values

Returns the index of the item if successful, or zero if the list-view control is in icon or small icon view.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetUnicodeFormat

Retrieves the UNICODE character format flag for the control. You can use this macro or send the LVM_GETUNICODEFORMAT message explicitly.

BOOL ListView_GetUnicodeFormat(
    HWND hwnd
);

Parameters

hwnd
Handle to the control.

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

See Also

ListView_SetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetViewRect

Retrieves the bounding rectangle of all items in the list-view control. The list view must be in icon or small icon view. You can use this macro or send the LVM_GETVIEWRECT message explicitly.

BOOL ListView_GetViewRect(
    HWND hwnd,
    RECT FAR *prc
);

Parameters

hwnd
Handle to the list-view control.
prc
Address of a RECT structure that receives the bounding rectangle. All coordinates are relative to the visible area of the list-view control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_GetWorkAreas

Retrieves the working areas from a list-view control. You can use this macro, or send the LVM_GETWORKAREAS message explicitly.

void ListView_GetWorkAreas(
    HWND hwndLV,
    INT nWorkAreas,
    LPRECT lprc
);

Parameters

hwndLV
Handle to the list-view control.
nWorkAreas
The number of RECT structures in the array at lprc.
lprc
Address of an array of RECT structures that receive the working areas of the list-view control. Values in these structures are in client coordinates. nWorkAreas specifies the number of structures in this array.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_HitTest

Determines which list-view item, if any, is at a specified position. You can use this macro or send the LVM_HITTEST message explicitly.

int ListView_HitTest(
    HWND hwnd,
    LPLVHITTESTINFO pinfo
);

Parameters

hwnd
Handle to the list-view control.
pinfo
Address of an LVHITTESTINFO structure that contains the position to hit test and receives information about the results of the hit test.

Return Values

Returns the index of the item at the specified position, if any, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_InsertColumn

Inserts a new column in a list-view control. You can use this macro or send the LVM_INSERTCOLUMN message explicitly.

int ListView_InsertColumn(
    HWND hwnd,
    int iCol,
    const LPLVCOLUMN pcol
);

Parameters

hwnd
Handle to the list-view control.
iCol
Index of the new column.
pcol
Address of an LVCOLUMN structure that contains the attributes of the new column.

Return Values

Returns the index of the new column if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_InsertItem

Inserts a new item in a list-view control. You can use this macro or send the LVM_INSERTITEM message explicitly.

int ListView_InsertItem(
    HWND hwnd,
    const LPLVITEM pitem
);

Parameters

hwnd
Handle to the list-view control.
pitem
Address of an LVITEM structure that specifies the attributes of the list-view item. Use the iItem member to specify the zero-based index at which the new item should be inserted. If this value is greater than the number of items currently contained by the listview control, the new item will be appended to the end of the list and assigned the correct index. Examine the macro's return value to determine the actual index assigned to the item.

Return Values

Returns the index of the new item if successful, or -1 otherwise.

Remarks

You cannot use ListView_InsertItem or LVM_INSERTITEM to insert subitems. The iSubItem member of the LVITEM structure must be zero.

If a list-view control has the LVS_EX_CHECKBOX style set, any value placed in bits 12 through 15 of the state member of the LVITEM structure will be ignored. When an item is added with this style set, it will always be set to the unchecked state.

If a list-view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEM structure.

The ListView_InsertItem macro will insert the new item in the proper position in the sort order if the following conditions hold:

  • You are using one of the LVS_SORTXXX styles.
  • You are not using the LVS_OWNERDRAW style.
  • The pszText member of the structure pointed to by pitem is not set to LPSTR_TEXTCALLBACK.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


ListView_RedrawItems

Forces a list-view control to redraw a range of items. You can use this macro or send the LVM_REDRAWITEMS message explicitly.

BOOL ListView_RedrawItems(
    HWND hwnd,
    int iFirst,
    int iLast
);

Parameters

hwnd
Handle to the list-view control.
iFirst
Index of the first item to redraw.
iLast
Index of the last item to redraw.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The specified items are not actually redrawn until the list-view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this macro.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_Scroll

Scrolls the content of a list-view control. You can use this macro or send the LVM_SCROLL message explicitly.

BOOL ListView_Scroll(
    HWND hwnd,
    int dx,
    int dy
);

Parameters

hwnd
Handle to the list-view control.
dx
Integer value that specifies the amount of horizontal scrolling in pixels. If the list-view control is in list view, this value specifies the number of columns to scroll.
dy
Integer value that specifies the amount of vertical scrolling in pixels.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the list-view control is in report view, the control can only be scrolled vertically in whole line increments. Therefore, the dy parameter will be rounded to the nearest number of pixels that form a whole line increment. For example, if the height of a line is 16 pixels and 8 is passed for dy, the list will be scrolled by 16 pixels (1 line). If 7 is passed for dy, the list will be scrolled 0 pixels (0 lines).

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetBkColor

Sets the background color of a list-view control. You can use this macro or send the LVM_SETBKCOLOR message explicitly.

BOOL ListView_SetBkColor(
    HWND hwnd,
    COLORREF clrBk
);

Parameters

hwnd
Handle to the list-view control.
clrBk
Background color to set or the CLR_NONE value for no background color. List-view controls with background colors redraw themselves significantly faster than those without background colors.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetBkImage

Sets the background image in a list-view control. You can use this macro or send the LVM_SETBKIMAGE message explicitly.

BOOL ListView_SetBkImage(
    HWND hwndLV,
    LPLVBKIMAGE plvbki;
);

Parameters

hwndLV
Handle to the list-view control.
plvbki
Address of an LVBKIMAGE structure that contains the new background image information.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

Because the list-view control uses OLE COM to manipulate the background images, the calling application must call CoInitialize or OleInitialize before using this macro. It is best to call one of these functions when the application is initialized, and call either CoUninitialize or OleUninitialize when the application is terminating.

See also

ListView_GetBkImage

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_SetCallbackMask

Changes the callback mask for a list-view control. You can use this macro or send the LVM_SETCALLBACKMASK message explicitly.

BOOL ListView_SetCallbackMask(
    WND hwnd,
    UINT mask
);

Parameters

hwnd
Handle to the list-view control.
mask
Value of the callback mask. The bits of the mask indicate the item states or images for which the application stores the current state data. This value can be any combination of the following constants:
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus.
LVIS_SELECTED | The item is selected.
LVIS_OVERLAYMASK | The application stores the image list index of the current overlay image for each item.
LVIS_STATEIMAGEMASK | The application stores the image list index of the current state image for each item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The callback mask of a list-view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control's items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list-view control stores all item state information. After creating a list-view control and initializing its items, you can use the ListView_SetCallbackMask macro or LVM_SETCALLBACKMASK message to change the callback mask. To retrieve the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information about overlay images and state images, see List-View Image Lists.

For more information on list-view callbacks, see Callback Items and the Callback Mask

See Also

LVN_GETDISPINFO

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetCheckState

Used to select or deselect an item in a list-view control. You can use this macro or send the LVM_SETITEMSTATE message explicitly.

ListView_SetCheckState(
    HWND hwndLV,
    UINT iIndex,
    BOOL fCheck
);

Parameters

hwndLV
Handle to a list-view control.
iIndex
Index of the item for which to set the check state.
fCheck
Value that is set to TRUE to select the item, or FALSE to deselect it.

Return Values

No return value.

Remarks

This macro should only be used for list-view controls with the LVS_EX_CHECKBOXES style. Although the LVM_SETITEMSTATE message used by ListView_SetCheckState is found on Microsoft® Windows® 95 and later systems, the LVS_EX_CHECKBOXES style was not introduced until version 4.70 of the common controls.

See Also

ListView_SetItemState

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetColumn

Sets the attributes of a list-view column. You can use this macro or send the LVM_SETCOLUMN message explicitly.

BOOL ListView_SetColumn(
    HWND hwnd,
    int iCol,
    LPLVCOLUMN pcol
);

Parameters

hwnd
Handle to the list-view control.
iCol
Index of the column.
pcol
Address of an LVCOLUMN structure that contains the new column attributes. The mask member specifies which column attributes to set.
If the mask member specifies the LVCF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetColumnOrderArray

Sets the left-to-right order of columns in a list-view control. You can use this macro or send the LVM_SETCOLUMNORDERARRAY message explicitly.

BOOL ListView_SetColumnOrderArray(
    HWND hwndLV,
    int iCount,
    int *lpiArray
);

Parameters

hwndLV
Handle to a list-view control.
iCount
Number of columns in the list-view control.
lpiArray
Address of an array specifying the order in which columns should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays column 2, column 0, and column 1, from left to right.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetColumnWidth

Used to change the width of a column in report view or the width of all columns in list-view mode. You can use this macro or send the LVM_SETCOLUMNWIDTH message explicitly.

BOOL ListView_SetColumnWidth(
    HWND hwnd,
    int iCol,
    int cx
);

Parameters

hwnd
Handle to the list-view control.
iCol
Zero-based index of a valid column. For list-view mode, this parameter must be set to zero.
cx
New width of the column, in pixels. For report-view mode, the following special values are supported:
LVSCW_AUTOSIZE | Automatically sizes the column.
LVSCW_AUTOSIZE_USEHEADER | Automatically sizes the column to fit the header text. If you use this value with the last column, its width is set to fill the remaining width of the list-view control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Assume that you have a 2-column list-view control with a width of 500 pixels. If the width of column zero is set to 200 pixels, and you send ListView_SetColumnWidth(hwnd, 1, LVSCW_AUTOSIZE_USEHEADER), the second (and last) column will be 300 pixels wide.

Note that ListView_SetColumnWidth converts the cx parameter to a 16-bit value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetExtendedListViewStyle

Sets extended styles for list-view controls. You can use this macro or send the LVM_SETEXTENDEDLISTVIEWSTYLE message explicitly.

void ListView_SetExtendedListViewStyle(
    HWND hwndLV,
    DWORD dwExStyle
);

Parameters

hwndLV
Handle to the list-view control that will receive the style change.
dwExStyle
DWORD value that specifies the extended list-view control style. This parameter can be a combination of extended styles.

Remarks

For backward compatibility reasons, the ListView_SetExtendedListViewStyle macro has not been updated to use dwExMask. To use the dwExMask value, use the ListView_SetExtendedListViewStyleEx macro.

When you use this macro to set the LVS_EX_CHECKBOXES style, any previously set state image index will be discarded. All check boxes will be initialized to the unchecked state. The state image index is contained in bits 12 through 15 of the state member of the LVITEM structure.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetExtendedListViewStyleEx

Sets extended styles for list-view controls using the style mask. You can use this macro or send the LVM_SETEXTENDEDLISTVIEWSTYLE message explicitly.

void ListView_SetExtendedListViewStyleEx(
    HWND hwndLV,
    DWORD dwExMask,
    DWORD dwExStyle
);

Parameters

hwndLV
Handle to the list-view control that will receive the style change.
dwExMask
DWORD value that specifies which styles in dwExStyle are to be affected. This parameter can be a combination of extended styles. Only the extended styles in dwExMask will be changed. All other styles will be maintained as they are. If this parameter is zero, all of the styles in dwExStyle will be affected.
dwExStyle
DWORD value that specifies the extended list-view control style. This parameter can be a combination of extended styles.

Remarks

When you use this macro to set the LVS_EX_CHECKBOXES style, any previously set state image index will be discarded. All check boxes will be initialized to the unchecked state. The state image index is contained in bits 12 through 15 of the state member of the LVITEM structure.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_SetHotCursor

Sets the HCURSOR that the list-view control uses when the pointer is over an item while hot tracking is enabled. You can use this macro or send the LVM_SETHOTCURSOR message explicitly. To check whether or not hot tracking is enabled, call SystemParametersInfo.

HCURSOR ListView_SetHotCursor(
    HWND    hwndLV,
    HCURSOR hCursor
);

Parameters

hwndLV
Handle to a list-view control.
hCursor
Handle to the cursor to be set.

Return Values

Returns an HCURSOR value that is the cursor that was previously used when the pointer was over an item.

Remarks

A list-view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetHotItem

Sets the hot item in a list-view control. You can use this macro or send the LVM_SETHOTITEM message explicitly.

INT ListView_SetHotItem(
    HWND hwndLV,
    INT  iIndex
);

Parameters

hwndLV
Handle to a list-view control.
iIndex
Zero-based index of the item to be set as the hot item.

Return Values

Returns the index of the item that was previously hot.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetHoverTime

Sets the amount of time that the mouse cursor must hover over an item before it is selected. You can use this macro or send the LVM_SETHOVERTIME message explicitly.

ListView_SetHoverTime(
    HWND hwndLV,
    DWORD dwHoverTime
);

Parameters

hwndLV
Handle to a list-view control.
dwHoverTime
The new amount of time, in milliseconds, that the mouse cursor must hover over an item before it is selected. If this value is (DWORD)-1, then the hover time is set to the default hover time.

Return Values

Returns the previous hover time.

Remarks

The hover time only affects list-view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list-view style.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_SetIconSpacing

Sets the spacing between icons in list-view controls set to the LVS_ICON style. You can use this macro or send the LVM_SETICONSPACING message explicitly.

DWORD ListView_SetIconSpacing(
    HWND hwndLV,
    int cx,
    int cy
);

Parameters

hwndLV
Handle to a list-view control.
cx
Distance, in pixels, to set between icons on the x-axis.
cy
Distance, in pixels, to set between icons on the y-axis.

Return Values

Returns a DWORD value that contains the previous cx in the low word and the previous cy in the high word.

Remarks

The cx and cy parameters are relative to the upper-left corner of an icon bitmap. Therefore, to set spacing between icons that do not overlap, the cx or cy values must include the size of the icon, plus the amount of empty space desired between icons. Values that do not include the width of the icon will result in overlaps.

When defining the icon spacing, cx and cy must set to 4 or larger. Smaller values will not yield the desired layout. You can reset cx and cy to the default spacing by setting both values to -1. This approach only allows you to reset both default settings. You cannot reset only cx or cy to the default setting by setting one of them to -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetImageList

Assigns an image list to a list-view control. You can use this macro or send the LVM_SETIMAGELIST message explicitly.

HIMAGELIST ListView_SetImageList(
    HWND hwnd,
    HIMAGELIST himl,
    int iImageList
);

Parameters

hwnd
Handle to the list-view control.
himl
Handle to the image list to assign.
iImageList
Type of image list. This parameter can be one of the following values:
LVSIL_NORMAL | Image list with large icons.
LVSIL_SMALL | Image list with small icons.
LVSIL_STATE | Image list with state images.

Return Values

Returns the handle to the image list previously associated with the control if successful, or NULL otherwise.

Remarks

The current image list will be destroyed when the list-view control is destroyed unless the LVS_SHAREIMAGELISTS style is set. If you use this message to replace one image list with another, your application must explicitly destroy all image lists other than the current one.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetItem

Sets some or all of a list-view item's attributes. You can also use ListView_SetItem to set the text of a subitem. You can use this macro or send the LVM_SETITEM message explicitly.

BOOL ListView_SetItem(
    HWND hwnd,
    const LPLVITEM pitem
);

Parameters

hwnd
Handle to the list-view control.
pitem
Address of an LVITEM structure that contains the new item attributes. The iItem and iSubItem members identify the item or subitem, and the mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.
If the mask member specifies the LVIF_STATE value, the stateMask member specifies which item states to change, and the state member contains the values for those states.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

To set the attributes of a list-view item, set the iItem member of the LVITEM structure to the index of the item, and set the iSubItem member to zero. For an item, you can use the state, pszText, iImage, and lParam members of the LVITEM structure to modify these item parameters.

To set the text of a subitem, set the iItem and iSubItem members to indicate the specific subitem, and use the pszText member to specify the text. Alternatively, you can use the ListView_SetItemText macro to set the text of a subitem. You cannot set the state or lParam members for subitems because subitems do not have these attributes. In version 4.70 and later, you can set the iImage member for subitems. The subitem image will be displayed if the list-view control has the LVS_EX_SUBITEMIMAGES extended style. Previous versions will ignore the subitem image.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetItemCount

Causes the list-view control to allocate memory for the specified number of items. You can use this macro or send the LVM_SETITEMCOUNT message explicitly.

void ListView_SetItemCount(
    HWND hwndLV,
    int cItems
);

Parameters

hwndLV
Handle to a list-view control.
cItems
Number of items for which the list-view control should allocate memory.

Remarks

If the list-view control was created without the LVS_OWNERDATA style, this macro causes the control to allocate its internal data structures for the specified number of items. This prevents the control from having to allocate the data structures every time an item is added.

If the list-view control was created with the LVS_OWNERDATA style (a virtual list view), the ListView_SetItemCountEx macro should be used.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetItemCountEx

Sets the virtual number of items in a virtual list view. You can use this macro or send the LVM_SETITEMCOUNT message explicitly.

void ListView_SetItemCountEx(
    HWND hwndLV,
    int cItems,
    DWORD dwFlags
);

Parameters

hwndLV
Handle to a virtual list-view control.
cItems
Number of items that the list-view control will contain.
dwFlags
Values that specify the behavior of the list-view control after resetting the item count. This value can be a combination of the following:
LVSICF_NOINVALIDATEALL | The list-view control will not repaint unless affected items are currently in view.
LVSICF_NOSCROLL | The list-view control will not change the scroll position when the item count changes.

Remarks

This macro is intended only for list-view controls that use the LVS_OWNERDATA and LVS_REPORT or LVS_LIST styles.

If the list-view control was created with the LVS_OWNERDATA style, this macro sets the virtual number of items that the control contains.

If the list-view control was created without the LVS_OWNERDATA style, the ListView_SetItemCount macro should be used.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_SetItemPosition

Moves an item to a specified position in a list-view control (in icon or small icon view). You can use this macro or send the LVM_SETITEMPOSITION message explicitly.

BOOL ListView_SetItemPosition(
    HWND hwnd,
    int i,
    int x,
    int y
);

Parameters

hwnd
Handle to the list-view control.
i
Index of the list-view item.
x and y
New position of the item's upper-left corner, in view coordinates.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the list-view control has the LVS_AUTOARRANGE style, the list-view control is arranged after the position of the item is set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetItemPosition32

Moves an item to a specified position in a list-view control (in icon or small icon view). This macro differs from the ListView_SetItemPosition macro in that it uses 32-bit coordinates. You can use the ListView_SetItemPosition32 macro or send the LVM_SETITEMPOSITION32 message explicitly.

void ListView_SetItemPosition32(
    HWND hwnd,
    int iItem,
    int x,
    int y
);

Parameters

hwnd
Handle to the list-view control.
iItem
Index of the list-view item for which to set the position.
x and y
New horizontal and vertical coordinates of the item.

Return Values

No return value.

See Also

POINT

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetItemState

Changes the state of an item in a list-view control. You can use this macro or send the LVM_SETITEMSTATE message explicitly.

ListView_SetItemState(
    HWND hwnd,
    int i,
    UINT state,
    UINT mask
);

Parameters

hwnd
Handle to the list-view control.
i
Index of the list-view item. If this parameter is -1, then the state change is applied to all items.
state
New state bits for the item. The mask parameter indicates the valid bits of the state parameter. The macro ignores bits in the state parameter if the corresponding bit is not set in the mask parameter.

The low-order byte contains a set of bit flags that indicate the item's state. This byte can be a combination of the following values:
LVIS_CUT | The item is marked for a cut-and-paste operation.
LVIS_DROPHILITED | The item is highlighted as a drag-and-drop target.
LVIS_FOCUSED | The item has the focus, so it is surrounded by a standard focus rectangle. Although more than one item may be selected, only one item can have the focus.
LVIS_SELECTED | The item is selected. The appearance of a selected item depends on whether it has the focus and also on the system colors used for selection. Items will only show as selected if the list-view control has focus or the LVS_SHOWSELALWAYS style is used.

Bits 8 through 11 of the state parameter specify the one-based index of an overlay image in the control's image lists. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To specify an overlay index, use the INDEXTOOVERLAYMASK macro.

Bits 12 through 15 of the state parameter specify the one-based index of an image in the control's state image list. The state image is displayed next to an item's icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To specify a state image index, use the INDEXTOSTATEIMAGEMASK macro.

mask
Bits of the state parameter that you want to set or clear. You can use ListView_SetItemState both to set and to clear bits. To set an item's overlay image index, set the LVIS_OVERLAYMASK bits. To set an item's state image index, set the LVIS_STATEIMAGEMASK bits.

Return Values

No return value.

Remarks

An item's state value includes a set of bit flags that indicate the item's state. The state value can also include image list indexes that indicate the item's state image and overlay image.

The mask parameter specifies the state bits you want to modify, and the state parameter specifies the new value for those bits. To set a bit in the item's internal state, set it in both the mask and state parameters. To clear a bit in the item's internal state, set it in the mask parameter and clear it in the state parameter. To leave a bit unchanged in the item's internal state, clear it in the mask parameter.

See Also

ListView_GetItemState

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetItemText

Changes the text of a list-view item or subitem. You can use this macro or send the LVM_SETITEMTEXT message explicitly.

VOID WINAPI ListView_SetItemText(
    HWND hwnd,
    int i,
    int iSubItem,
    LPCSTR pszText
);

Parameters

hwnd
Handle to the list-view control.
i
Index of the list-view item.
iSubItem
Index of the subitem. To set the item label, set iSubItem to zero.
pszText
Address of a null-terminated string that contains the new text.
This parameter can be LPSTR_TEXTCALLBACK to indicate a callback item for which the parent window stores the text. In this case, the list-view control sends the parent an LVN_GETDISPINFO notification message when it needs the text.
This parameter can be NULL.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetSelectionMark

Sets the selection mark in a list-view control. You can use this macro or send the LVM_SETSELECTIONMARK message explicitly.

INT ListView_SetSelectionMark(
    HWND hwndLV,
    INT  iIndex
);

Parameters

hwndLV
Handle to a list-view control.
iIndex
Zero-based index of the list-view item to be selected.

Return Values

Returns the previous selection mark, or -1 if there is no previous selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts. This macro does not affect the selection state of the item.

See Also

ListView_GetSelectionMark

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_SetTextBkColor

Sets the background color of text in a list-view control. You can use this macro or send the LVM_SETTEXTBKCOLOR message explicitly.

BOOL ListView_SetTextBkColor(
    HWND hwnd,
    COLORREF clrText
);

Parameters

hwnd
Handle to the list-view control.
clrText
New text color.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetTextColor

Sets the text color of a list-view control. You can use this macro or send the LVM_SETTEXTCOLOR message explicitly.

BOOL ListView_SetTextColor(
    HWND hwnd,
    COLORREF clrText
);

Parameters

hwnd
Handle to the list-view control.
clrText
New text color.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetToolTips

Sets the ToolTip control that the list-view control will use to display ToolTips. You can use this macro or send the LVM_SETTOOLTIPS message explicitly.

HWND ListView_SetToolTips(
    HWND hwnd,
    HWND hwndToolTip
);

Parameters

hwnd
Handle to the list-view control.
hwndToolTip
Handle to the ToolTip control to be set.

Return Values

Returns the handle to the previous ToolTip control.

See Also

ListView_GetToolTips

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetUnicodeFormat

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the LVM_SETUNICODEFORMAT message explicitly.

BOOL ListView_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Parameters

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

See Also

ListView_GetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SetWorkAreas

Sets the working area within a list-view control. You can use this macro or send the LVM_SETWORKAREAS message explicitly.

void ListView_SetWorkAreas(
    HWND hwndLV,
    INT nWorkAreas,
    LPRECT lprc
);

Parameters

hwndLV
Handle to a list-view control.
nWorkAreas
Number of RECT structures in the array at lprc. The maximum number of working areas allowed is defined by the LV_MAX_WORKAREAS value.
lprc
Address of an array of RECT structures that contain the new working areas of the list-view control. Values in these structures are in client coordinates. If this parameter is NULL, the working area will be set to the client area of the control. nWorkAreas specifies the number of structures in this array.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


ListView_SortItems

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence. You can use this macro or send the LVM_SORTITEMS message explicitly.

BOOL ListView_SortItems(
    HWND hwnd,
    PFNLVCOMPARE pfnCompare,
    LPARAM lParamSort
);

Parameters

hwnd
Handle to the list-view control.
pfnCompare
Address of the application-defined comparison function. The comparison function is called during the sort operation each time the relative order of two list items needs to be compared.
lParamSort
Application-defined value that is passed to the comparison function.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
LPARAM lParamSort);

The lParam1 parameter is the 32-bit value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items' LVITEM structure when they were inserted into the list. The lParamSort parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

Note: During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control, the results are unpredictable.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


ListView_SortItemsEx

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence. You can use this macro or send the LVM_SORTITEMSEX message explicitly.

BOOL ListView_SortItemsEx(
    HWND hwnd,
    PFNLVCOMPARE pfnCompare,
    LPARAM lParamSort
);

Parameters

hwnd
Handle to the list-view control.
pfnCompare
Address of an application-defined comparison function. It is called during the sort operation each time the relative order of two list items needs to be compared.
lParamSort
Application-defined value that is passed to the comparison function.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The comparison function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
LPARAM lParamSort);

where lParam1 is the index of the first item and lParam2 the index of the second. The ListView_SortItemEx's lParamSort parameter is passed to the callback function as its third parameter.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

You can send an LVM_GETITEMTEXT message to retrieve further information on an item, if needed.

This macro is similar to ListView_SortItems, except for the type of information passed to the comparison function. With ListView_SortItemsEx, the item's index is passed instead of its lparam value.

Note: During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control aside from LVM_GETITEM (ListView_GetItem), the results are unpredictable.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


ListView_SubItemHitTest

Determines which list-view item or subitem is located at a given position. You can use this macro or send the LVM_SUBITEMHITTEST message explicitly.

INT ListView_SubItemHitTest(
    HWND hwndLV,
    LPLVHITTESTINFO pInfo
);

Parameters

hwndLV
Handle to the list-view control that will be hit-tested.
pInfo
Address of an LVHITTESTINFO structure. The POINT structure within LVHITTESTINFO must be set to the client coordinates to be hit-tested.

Return Values

Returns the index of the item or subitem tested, if any, or -1 otherwise. If an item or subitem is at the given coordinates, the fields of the LVHITTESTINFO structure will be filled with the applicable hit information.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


ListView_Update

Updates a list-view item. If the list-view control has the LVS_AUTOARRANGE style, this macro causes the list-view control to be arranged. You can use this macro or send the LVM_UPDATE message explicitly.

BOOL ListView_Update(
    HWND hwnd,
    int iItem
);

Parameters

hwnd
Handle to the list-view control.
iItem
Index of the item to update.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_BEGINDRAG

Notifies a list-view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

LVN_BEGINDRAG
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_BEGINLABELEDIT

Notifies a list-view control's parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_BEGINLABELEDIT
    pdi = (LPNMLVDISPINFO) lParam;

Parameters

pdi
Address of an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item being edited.

Return Values

To allow the user to edit the label, return FALSE.

To prevent the user from editing the label, return TRUE.

Remarks

When label editing begins, an edit control is created, positioned, and initialized. Before it is displayed, the list-view control sends its parent window an LVN_BEGINLABELEDIT notification message.

To customize label editing, implement a handler for LVN_BEGINLABELEDIT and have it send an LVM_GETEDITCONTROL message to the list-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

When the user cancels or completes the editing, the parent window receives an LVN_ENDLABELEDIT notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


LVN_BEGINRDRAG

Notifies a list-view control's parent window that a drag-and-drop operation involving the right mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

LVN_BEGINRDRAG
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the item being dragged, and the other members are zero.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_COLUMNCLICK

Notifies a list-view control's parent window that a column was clicked. This notification message is sent in the form of a WM_NOTIFY message.

LVN_COLUMNCLICK
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure. The iItem member is -1, and the iSubItem member identifies the column. All other members are zero.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_DELETEALLITEMS

Notifies a list-view control's parent window that all items in the control are about to be deleted. This notification message is sent in the form of a WM_NOTIFY message.

LVN_DELETEALLITEMS
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure. The iItem member is -1, and the other members are zero.

Return Values

To suppress subsequent LVN_DELETEITEM notification messages, return TRUE.

To receive subsequent LVN_DELETEITEM notification messages, return FALSE.

Remarks

A list-view control sends the LVN_DELETEALLITEMS notification message when it is destroyed or when it receives the LVM_DELETEALLITEMS message. If LVN_DELETEALLITEMS does not return TRUE, the control will also send an LVN_DELETEITEM notification message as each item is deleted.

If the LVN_DELETEALLITEMS message handler is in a dialog box procedure, return TRUE from the dialog box procedure, and use the SetWindowLong function with DWL_MSGRESULT to set the message return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_DELETEITEM

Notifies a list-view control's parent window that an item is about to be deleted. This notification message is sent in the form of a WM_NOTIFY message.

LVN_DELETEITEM
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the item being deleted. All other members of this structure are zero.

Return Values

No return value.

Remarks

Do not add, delete, or rearrange items in the list view while processing this notification.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


LVN_ENDLABELEDIT

Notifies a list-view control's parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_ENDLABELEDIT
    pdi = (LPNMLVDISPINFO) lParam;

Parameters

pdi
Address of an NMLVDISPINFO structure. The item member of this structure is an LVITEM structure whose iItem member identifies the item being edited. The pszText member of item contains a valid value when the LVN_ENDLABELEDIT message is sent, regardless of whether the LVIF_TEXT flag is set in the mask member of the LVITEM structure.

If the user cancels editing, the pszText member of the LVITEM structure is NULL; otherwise, pszText is the address of the edited text.

Return Values

If the pszText member of the LVITEM structure is non-NULL, return TRUE to set the item's label to the edited text. Return FALSE to reject the edited text and revert to the original label.

If the pszText member of the LVITEM structure is NULL, the return value is ignored.

Remarks

When the user begins editing an item label, the parent window of the list-view control receives an LVN_BEGINLABELEDIT notification message. When the user cancels or completes the editing, the parent window receives an LVN_ENDLABELEDIT notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_GETDISPINFO

Sent by a list-view control to its parent window. It is a request for the parent window to provide information needed to display or sort a list-view item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_GETDISPINFO
    pnmv = (LPNMLVDISPINFO) lParam;

Parameters

pnmv
Address of an NMLVDISPINFO structure. On input, the LVITEM structure contained in this structure specifies the type of information required and identifies the item or subitem of interest.
Use the LVITEM structure to return the requested information to the control. If your message handler sets the LVIF_DI_SETITEM flag in the mask member of the LVITEM structure, the list-view control stores the requested information and will not ask for it again.

Return Values

No return value.

Remarks

A list-view control sends the LVN_GETDISPINFO notification to retrieve item information that is stored by the application rather than the control. The information can be text or icon information for an item. It can also be item state information. See the LVM_SETCALLBACKMASK message for more information on implementing item state on a callback basis.

For more information on list-view callbacks, see Callback Items and the Callback Mask.

See Also

LVN_SETDISPINFO

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_GETINFOTIP

Sent by a large icon view list-view control that has the LVS_EX_INFOTIP extended style. This notification is sent when the list-view control is requesting additional text information to be displayed in a ToolTip. It is sent in the form of a WM_NOTIFY message.

LVN_GETINFOTIP
    pGetInfoTip = (LPNMLVGETINFOTIP)lParam;

Parameters

pGetInfoTip
Address of an NMLVGETINFOTIP structure that contains information about this notification.

Return Values

The return value for this notification is not used.

Remarks

This notification is only sent by list-view controls that have the LVS_EX_INFOTIP extended style. The LVN_GETINFOTIP notification is sent for sub-items while in report mode only when the LVS_EX_FULLROWSELECT extended style is in use.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVN_HOTTRACK

Sent by a list-view control when the user moves the mouse over an item. This notification is only sent by list-view controls that have the LVS_EX_TRACKSELECT extended list-view style. It is sent in the form of a WM_NOTIFY message.

LVN_HOTTRACK
    lpnmlv = (LPNMLISTVIEW)lParam;

Parameters

lpnmlv
Address of an NMLISTVIEW structure that contains information about this notification. The iItem, iSubItem, and ptAction members of this structure contain information about the item. The receiving application can modify the iItem member to specify the item that will be selected. If iItem is set to -1, no item will be selected.

Return Values

Return zero to allow the list view to perform its normal track select processing. If the application returns nonzero, the item will not be selected.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVN_INSERTITEM

Notifies a list-view control's parent window that a new item was inserted. This notification message is sent in the form of a WM_NOTIFY message.

LVN_INSERTITEM
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure. The iItem member identifies the new item, and the other members are zero.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_ITEMACTIVATE

Sent by a list-view control when the user activates an item. This notification is sent in the form of a WM_NOTIFY message.

LVN_ITEMACTIVATE
#if (_WIN32_IE >= 0x0400)
    lpnmia = (LPNMITEMACTIVATE)lParam;
#else
    lpnm = (LPNMHDR)lParam;
#endif

Parameters

lpnmia
Version 4.71. Address of an NMITEMACTIVATE structure that contains information about this notification.
lpnm
Version 4.70 and earlier. Address of an NMHDR structure that contains information about this notification.

Return Values

The application receiving this notification must return zero.

Remarks

To obtain the items being activated, the receiving application should use the LVM_GETSELECTEDCOUNT message to retrieve the number of items that are selected and then send the LVM_GETNEXTITEM message with LVNI_SELECTED until all of the items have been retrieved.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVN_ITEMCHANGED

Notifies a list-view control's parent window that an item has changed. This notification message is sent in the form of a WM_NOTIFY message.

LVN_ITEMCHANGED
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure that identifies the item and specifies which of its attributes have changed. If the iItem member of the structure pointed to by pnmv is -1, the change has been applied to all items in the list view.

Return Values

No return value.

Remarks

If a list-view control has the LVS_OWNERDATA style, and the user selects a range of items by holding down the SHIFT key and clicking the mouse, LVN_ITEMCHANGED notifications are not sent for each selected or deselected item. Instead, you will receive a single LVN_ODSTATECHANGED notification, indicating that a range of items has changed state.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_ITEMCHANGING

Notifies a list-view control's parent window that an item is changing. This notification message is sent in the form of a WM_NOTIFY message.

LVN_ITEMCHANGING
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMLISTVIEW structure that identifies the item and specifies which of its attributes are changing.

Return Values

Returns TRUE to prevent the change, or FALSE to allow the change.

Remarks

If the list-view control has the LVS_OWNERDATA style, LVN_ITEMCHANGING notifications are not sent.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_KEYDOWN

Notifies a list-view control's parent window that a key has been pressed. This notification message is sent in the form of a WM_NOTIFY message.

LVN_KEYDOWN
    pnkd = (LPNMLVKEYDOWN) lParam;

Parameters

pnkd
Address of an NMLVKEYDOWN structure.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVN_MARQUEEBEGIN

Notifies a list-view control's parent window that a bounding box (marquee) selection has begun. This notification message is sent in the form of a WM_NOTIFY message.

LVN_MARQUEEBEGIN
    pnmv = (LPNMLISTVIEW) lParam;

Parameters

pnmv
Address of an NMHDR structure.

Return Values

Note A bounding box selection is the process of clicking the list-view window's client area and dragging to select multiple items simultaneously.To accept the notification message, return zero. To quit the bounding box selection, return nonzero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVN_ODCACHEHINT

Sent by a virtual list-view control when the contents of its display area have changed. For example, a list-view control sends this notification when the user scrolls the control's display. The LVN_ODCACHEHINT notification message is sent in the form of a WM_NOTIFY message.

LVN_ODCACHEHINT
    pCachehint = (NMLVCACHEHINT *)lParam;

Parameters

pCachehint
Address of an NMLVCACHEHINT structure containing information about the range of items to be cached.

Return Values

The application receiving this notification must return zero.

Remarks

Handling this message allows the application to update the item information held in cache so that it is readily available when an LVN_GETDISPINFO notification message is sent.

Note that this message is not always an exact representation of the items that will be requested by LVN_GETDISPINFO. Therefore, if the requested item is not cached while handling LVN_GETDISPINFO, the application must be prepared to supply the requested information from a source outside the cache.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVN_ODFINDITEM

Sent by a virtual list-view control when it needs the owner to find a particular callback item. For example, the control will send this notification when it receives shortcut keyboard input or when it receives an LVM_FINDITEM message.

LVN_ODFINDITEM
    pFindInfo = (PNMLVFINDITEM) lParam;

Parameters

pFindInfo
Address of an NMLVFINDITEM structure that includes information to be used for the search.

Return Values

Return the index of the item found, or -1 if no item is found.

Remarks

Search information is sent in the form of an LVFINDINFO structure, which is a member of the NMLVFINDITEM structure.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVN_ODSTATECHANGED

Sent by a list-view control when the state of an item or range of items has changed. This notification is sent in the form of a WM_NOTIFY message.

LVN_ODSTATECHANGED
    lpStateChange = (LPNMLVODSTATECHANGE) lParam;

Parameters

lpStateChange
Address of an NMLVODSTATECHANGE structure that contains information about the item or items that have changed.

Return Values

The application receiving this notification must return zero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


LVN_SETDISPINFO

Notifies a list-view control's parent window that it must update the information it maintains for an item. This notification message is sent in the form of a WM_NOTIFY message.

LVN_SETDISPINFO
    pnmv = (LPNMLVDISPINFO) lParam;

Parameters

pnmv
Address of an NMLVDISPINFO structure that specifies information for the changed item. The item member of this structure is an LVITEM structure that contains information about the item that was changed. The pszText member of item contains a valid value, regardless of whether the LVIF_TEXT flag is set in the mask member of this structure.

Return Values

No return value.

See Also

LVN_GETDISPINFO

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CLICK (list view)

Sent by a list-view control when the user clicks an item with the left mouse button. This notification message is sent in the form of a WM_NOTIFY message.

NM_CLICK
    lpnmitem = (LPNMITEMACTIVATE) lParam;

Parameters

lpnmitem
Version 4.71. Address of an NMITEMACTIVATE structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

Return Values

The return value for this notification is not used.

Remarks

This notification is identical to the standard NM_CLICK notification except that in version 4.71 and later, the list view supplies an NMITEMACTIVATE structure instead of an NMHDR structure for the lParam.

The iItem member of lpnmitem will only be valid if the icon or first-column label has been clicked. To determine which item is selected when a click takes place elsewhere in a row, send an LVM_SUBITEMHITTEST message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (list view)

Sent by a list-view control to notify its parent windows about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMLVCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Pointer to a NMLVCUSTOMDRAW structure that contains information about the drawing operation. The first member of this structure, nmcd, is a pointer to an NMCUSTOMDRAW structure. The dwItemSpec member of the structure pointed to by nmcd contains the identifier of the item being drawn and the lItemlParam member contains its application-defined data.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:

Return Value | Description
CDRF_DODEFAULT | The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW | The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE | The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE | The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT | The control will notify the parent after painting an item.

When dwDrawStage equals CDDS_ITEMPREPAINT:

Return Value | Description
CDRF_NEWFONT | The application specified a new font for the item; the control will use the new font. For more information about changing fonts, see Changing fonts and colors.
CDRF_NOTIFYSUBITEMDRAW | Version 4.71. Your application will receive an NM_CUSTOMDRAW message with dwDrawStage set to CDDS_ITEMPREPAINT | CDDS_SUBITEM before each list-view subitem is drawn. You can then specify font and color for each subitem separately or return CDRF_DODEFAULT for default processing.
CDRF_SKIPDEFAULT | The application drew the item manually. The control will not draw the item.

Remarks

Version 5.80. If you change the font by returning CDRF_NEWFONT, the list-view control might display clipped text. This behavior is necessary for backward compatibility with earlier versions of the common controls. If you want to change the font of a list-view control, you will get better results if you send a CCM_SETVERSION message with the wParam value set to 5 before adding any items to the control.

See Also

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_DBLCLK (list view)

Sent by a list-view control when the user double-clicks an item with the left mouse button. This notification message is sent in the form of a WM_NOTIFY message.

NM_DBLCLK
    lpnmitem = (LPNMITEMACTIVATE) lParam;

Parameters

lpnmitem
Version 4.71. Address of an NMITEMACTIVATE structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

Return Values

The return value for this notification is not used.

Remarks

This notification is identical to the standard NM_DBLCLK notification except that in version 4.71 and later, the list view supplies an NMITEMACTIVATE structure instead of an NMHDR structure for the lParam.

The iItem member of lpnmitem will only be valid if the icon or first-column label has been clicked. To determine which item is selected when a click takes place elsewhere in a row, send an LVM_SUBITEMHITTEST message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_HOVER (list view)

Sent by a list-view control when the mouse hovers over an item. This notification message is sent in the form of a WM_NOTIFY message.

NM_HOVER
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return zero to allow the list view to process the hover normally, or nonzero to prevent the hover from being processed.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_KILLFOCUS (list view)

Notifies a list-view control's parent window that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.

NM_KILLFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RCLICK (list view)

Sent by a list-view control when the user clicks an item with the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnmitem = (LPNMITEMACTIVATE) lParam;

Parameters

lpnmitem
Version 4.71. Address of an NMITEMACTIVATE structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

Return Values

Return nonzero to not allow the default processing, or zero to allow the default processing.

Remarks

This notification is identical to the standard NM_RCLICK notification except that in version 4.71 and later, the list view supplies an NMITEMACTIVATE structure instead of an NMHDR structure for the lParam.

The iItem member of lpnmitem will only be valid if the icon or first-column label has been clicked. To determine which item is selected when a click takes place elsewhere in a row, send an LVM_SUBITEMHITTEST message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RDBLCLK (list view)

Sent by a list-view control when the user double-clicks an item with the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

NM_RDBLCLK
    lpnmitem = (LPNMITEMACTIVATE) lParam;

Parameters

lpnmitem
Version 4.71. Address of an NMITEMACTIVATE structure that contains additional information about this notification message. The iItem, iSubItem, and ptAction members of this structure contain information about the item.

Return Values

The return value for this notification is not used.

Remarks

This notification is identical to the standard NM_RDBLCLK notification except that, in version 4.71 and later, the list view supplies an NMITEMACTIVATE structure instead of an NMHDR structure for the lParam.

The iItem member of the structure pointed to by lpnmitem will only be valid if the icon or first-column label has been clicked. To determine which item is selected when a click takes place elsewhere in a row, send an LVM_SUBITEMHITTEST message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (list view)

Notifies a list-view control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_RETURN (list view)

Notifies a list-view control's parent window that the control has the input focus and that the user has pressed the ENTER key. NM_RETURN is sent in the form of a WM_NOTIFY message.

NM_RETURN
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_SETFOCUS (list view)

Notifies a list-view control's parent window that the control has received the input focus. NM_SETFOCUS is sent in the form of a WM_NOTIFY message.

NM_SETFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVBKIMAGE

Contains information about the background image of a list-view control. This structure is used for both setting and retrieving background image information.

typedef struct tagLVBKIMAGE
{
    ULONG ulFlags;
    HBITMAP hbm;
    LPTSTR pszImage;
    UINT cchImageMax;
    int xOffsetPercent;
    int yOffsetPercent;
} LVBKIMAGE, FAR *LPLVBKIMAGE;

Members

ulFlags
One or more of the following flags. The LVBKIF_SOURCE_MASK value can be used to mask off all but the source flags. The LVBKIF_STYLE_MASK value can be used to mask off all but the style flags.
LVBKIF_SOURCE_NONE | The list-view control has no background image.
LVBKIF_SOURCE_URL | The pszImage member contains the URL of the background image.
LVBKIF_STYLE_NORMAL | The background image is displayed normally.
LVBKIF_STYLE_TILE | The background image will be tiled to fill the entire background of the control.
hbm
Not currently used.
pszImage
Address of a NULL-terminated string that contains the URL of the background image. This member is only valid if the LVBKIF_SOURCE_URL flag is set in ulFlags. This member must be initialized to point to the buffer that contains or receives the text before sending the message.
cchImageMax
Size of the buffer at the address in pszImage. If information is being sent to the control, this member is ignored.
xOffsetPercent
Percentage of the control's client area that the image should be offset horizontally. For example, at 0 percent, the image will be displayed against the left edge of the control's client area. At 50 percent, the image will be displayed horizontally centered in the control's client area. At 100 percent, the image will be displayed against the right edge of the control's client area. This member is only valid when LVBKIF_STYLE_NORMAL is specified in ulFlags.
yOffsetPercent
Percentage of the control's client area that the image should be offset vertically. For example, at 0 percent, the image will be displayed against the top edge of the control's client area. At 50 percent, the image will be displayed vertically centered in the control's client area. At 100 percent, the image will be displayed against the bottom edge of the control's client area. This member is only valid when LVBKIF_STYLE_NORMAL is specified in ulFlags.

Remarks

This structure is used with the LVM_GETBKIMAGE and LVM_SETBKIMAGE messages.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


LVCOLUMN

Contains information about a column in report view. This structure is used both for creating and manipulating columns. This structure supersedes the LV_COLUMN structure.

typedef struct _LVCOLUMN {
    UINT mask;
    int fmt;
    int cx;
    LPTSTR pszText;
    int cchTextMax;
    int iSubItem;
#if (_WIN32_IE >= 0x0300)
    int iImage;
    int iOrder;
#endif
} LVCOLUMN, FAR *LPLVCOLUMN;

Members

mask
Variable specifying which members contain valid information. This member can be zero, or one or more of the following values.

Value | Description
LVCF_FMT | The fmt member is valid.
LVCF_IMAGE | Version 4.70. The iImage member is valid.
LVCF_ORDER | Version 4.70. The iOrder member is valid.
LVCF_SUBITEM | The iSubItem member is valid.
LVCF_TEXT | The pszText member is valid.
LVCF_WIDTH | The cx member is valid.
fmt
Alignment of the column header and the subitem text in the column. This member can be one of the following values.
Value | Description
LVCFMT_BITMAP_ON_RIGHT | Version 4.70. The bitmap appears to the right of text. This does not affect an image from an image list assigned to the header item.
LVCFMT_CENTER | Text is centered.
LVCFMT_COL_HAS_IMAGES | Version 4.70. The header item contains an image in the image list.
LVCFMT_IMAGE | Version 4.70. The item displays an image from an image list.
LVCFMT_JUSTIFYMASK | A bitmask used to select those bits of fmt that control field justification. To check the format of a column, use a logical "and" to combine LCFMT_JUSTIFYMASK with fmt. You can then use a switch statement to determine whether the LVCFMT_LEFT, LVCFMT_RIGHT, or LVCFMT_CENTER bits are set.
LVCFMT_LEFT | Text is left-aligned.
LVCFMT_RIGHT | Text is right-aligned.

The alignment of the leftmost column is always left-justified; it cannot be changed.

cx
Width of the column, in pixels.
pszText
If column information is being set, this member is the address of a null-terminated string that contains the column header text. If the structure is receiving information about a column, this member specifies the address of the buffer that receives the column header text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information about a column, this member is ignored.
iSubItem
Index of subitem associated with the column.
iImage
Version 4.70. Zero-based index of an image within the image list. The specified image will appear within the column.
iOrder
Version 4.70. Zero-based column offset. Column offset is in left-to-right order. For example, zero indicates the leftmost column.

Remarks

If a column is added to a list-view control with index 0 (the leftmost column) and with LVCFMT_RIGHT or LVCFMT_CENTER specified, the text is not right-aligned or centered. The text in the index 0 column is left-aligned. Therefore if you keep inserting columns with index 0, the text in all columns are left-aligned. If you want the first column to be right-aligned or centered you can make a dummy column, then insert one or more columns with index 1 or higher and specify the alignment you require. Finally delete the dummy column.

See Also

LVM_GETCOLUMN, LVM_SETCOLUMN, LVM_INSERTCOLUMN, LVM_DELETECOLUMN

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


LVFINDINFO

Contains information used when searching for a list-view item. This structure is identical to LV_FINDINFO but has been renamed to fit standard naming conventions.

typedef struct tagLVFINDINFO
{
    UINT flags;
    LPCTSTR psz;
    LPARAM lParam;
    POINT pt;
    UINT vkDirection;
} LVFINDINFO, FAR* LPFINDINFO;

Members

flags
Type of search to perform. This member can be set to one or more of the following values:
LVFI_PARAM | Searches for a match between this structure's lParam member and the lParam member of an item's LVITEM structure. If LVFI_PARAM is specified, all other flags are ignored.
LVFI_PARTIAL | Checks to see if the item text begins with the string pointed to by the psz member. This value implies use of LVFI_STRING.
LVFI_STRING | Searches based on the item text. Unless additional values are specified, the item text of the matching item must exactly match the string pointed to by the psz member.
LVFI_WRAP | Continues the search at the beginning if no match is found.
LVFI_NEARESTXY | Finds the item nearest to the position specified in the pt member, in the direction specified by the vkDirection member. This flag is supported only by large icon and small icon modes.
psz
Address of a null-terminated string to compare with the item text. It is valid only if LVFI_STRING or LVFI_PARTIAL is set in the flags member.
lParam
Value to compare with the lParam member of a list-view item's LVITEM structure. It is valid only if LVFI_PARAM is set in the the flags member.
pt
POINT structure with the initial search position. It is valid only if LVFI_NEARESTXY is set in the flags member.
vkDirection
Virtual key code that specifies the direction to search. The following codes are supported:
  • VK_LEFT
  • VK_RIGHT
  • VK_UP
  • VK_DOWN
  • VK_HOME
  • VK_END
  • VK_PRIOR
  • VK_NEXT

This member is valid only if LVFI_NEARESTXY is set in the flags member.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVHITTESTINFO

Has been extended to accommodate subitem hit-testing. The LVHITTESTINFO structure contains information about a hit test. It is used in association with the LVM_HITTEST and LVM_SUBITEMHITTEST messages and their related macros. This structure supersedes the LV_HITTESTINFO structure.

typedef struct _LVHITTESTINFO {
    POINT pt;
    UINT flags;
    int iItem;
    int iSubItem;
 } LVHITTESTINFO, FAR *LPLVHITTESTINFO;

Members

pt
Position to hit test, in client coordinates.
flags
Variable that receives information about the results of a hit test. This member can be one or more of the following values:
LVHT_ABOVE | The position is above the control's client area.
LVHT_BELOW | The position is below the control's client area.
LVHT_NOWHERE | The position is inside the list-view control's client window, but it is not over a list item.
LVHT_ONITEMICON | The position is over a list-view item's icon.
LVHT_ONITEMLABEL | The position is over a list-view item's text.
LVHT_ONITEMSTATEICON | The position is over the state image of a list-view item.
LVHT_TOLEFT | The position is to the left of the list-view control's client area.
LVHT_TORIGHT | The position is to the right of the list-view control's client area.

You can use LVHT_ABOVE, LVHT_BELOW, LVHT_TOLEFT, and LVHT_TORIGHT to determine whether to scroll the contents of a list-view control. Two of these values may be combined. For example, if the position is above and to the left of the client area, you could use both LVHT_ABOVE and LVHT_TOLEFT.

You can test for LVHT_ONITEM to determine whether a specified position is over a list-view item. This value is a bitwise-OR operation on LVHT_ONITEMICON, LVHT_ONITEMLABEL, and LVHT_ONITEMSTATEICON.

iItem
Receives the index of the matching item. Or if hit-testing a subitem, this value represents the subitem's parent item.
iSubItem
Version 4.70. Receives the index of the matching subitem. When hit-testing an item, this member will be zero.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


LVITEM

Specifies or receives the attributes of a list-view item. This structure has been updated to support a new mask value (LVIF_INDENT) that enables item indenting. This structure supersedes the LV_ITEM structure.

typedef struct _LVITEM {
    UINT mask;
    int iItem;
    int iSubItem;
    UINT state;
    UINT stateMask;
    LPTSTR pszText;
    int cchTextMax;
    int iImage;
    LPARAM lParam;
#if (_WIN32_IE >= 0x0300)
    int iIndent;
#endif
#if (_WIN32_IE >= 0x560)
    int iGroupId;
    UINT cColumns; // tile view columns
    PUINT puColumns;
#endif

} LVITEM, FAR *LPLVITEM;

Members

mask
Set of flags that specify which members of this structure contain data to be set or which members are being requested. This member can have one or more of the following flags set:
Flag | Description
LVIF_DI_SETITEM | The operating system should store the requested list item information and not ask for it again. This flag is used only with the LVN_GETDISPINFO notification message.
LVIF_IMAGE | The iImage member is valid or must be filled in.
LVIF_INDENT | The iIndent member is valid or must be filled in.
LVIF_NORECOMPUTE | The control will not generate LVN_GETDISPINFO to retrieve text information if it receives an LVM_GETITEM message. Instead, the pszText member will contain LPSTR_TEXTCALLBACK.
LVIF_PARAM | The lParam member is valid or must be filled in.
LVIF_STATE | The state member is valid or must be filled in.
LVIF_TEXT | The pszText member is valid or must be filled in.
iItem
Zero-based index of the item to which this structure refers.
iSubItem
One-based index of the subitem to which this structure refers, or zero if this structure refers to an item rather than a subitem.
state
Indicates the item's state, state image, and overlay image. The stateMask member indicates the valid bits of this member.

Bits 0 through 7 of this member contain the item state flags. This can be one or more of the item state values.

Bits 8 through 11 of this member specify the one-based overlay image index. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To set the overlay image index in this member, you should use the INDEXTOOVERLAYMASK macro. The image list's overlay images are set with the ImageList_SetOverlayImage function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item's icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To set the state image index, use the INDEXTOSTATEIMAGEMASK macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the LVM_SETIMAGELIST message.

stateMask
Value specifying which bits of the state member will be retrieved or modified. For example, setting this member to LVIS_SELECTED will cause only the item's selection state to be retrieved.

This member allows you to modify one or more item states without having to retrieve all of the item states first. For example, setting this member to LVIS_SELECTED and state to zero will cause the item's selection state to be cleared, but none of the other states will be affected.

To retrieve or modify all of the states, set this member to (UINT)-1.

You can use the macro ListView_SetItemState both to set and to clear bits.

pszText
If the structure specifies item attributes, pszText is a pointer to a null-terminated string containing the item text. If the structure receives item attributes, pszText is a pointer to a buffer that receives the item text.

If the value of pszText is LPSTR_TEXTCALLBACK, the item is a callback item. If the callback text changes, you must explicitly set pszText to LPSTR_TEXTCALLBACK and notify the list-view control of the change by sending an LVM_SETITEM OR LVM_SETITEMTEXT message.

Do not set pszText to LPSTR_TEXTCALLBACK if the list-view control has the LVS_SORTASCENDING or LVS_SORTDESCENDING style.

cchTextMax
Number of characters in the buffer pointed to by pszText. This member is only used when the structure receives item attributes. It is ignored when the structure specifies item attributes.
iImage
Index of the item's icon in the control's image list. This applies to both the large and small image list.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the list-view control sends the parent an LVN_GETDISPINFO notification message to retrieve the index when it needs to display the image.

lParam
Value specific to the item. If you use the LVM_SORTITEMS message, the list-view control passes this value to the application-defined comparison function. You can also use the LVM_FINDITEM message to search a list-view control for an item with a specified lParam value.
iIndent
Version 4.70. Number of image widths to indent the item. A single indentation equals the width of an item image. Therefore, the value 1 indents the item by the width of one image, the value 2 indents by two images, and so on. Note that this field is supported only for items. Attempting to set subitem indentation will cause the calling function to fail.
iGroupId
Version 6.0 Identifier of the tile view group that receives the item.
cColumns
Version 6.0 Number of tile view columns to display for this item.
puColumns;
Version 6.0 Pointer to the array of column indices; length of cColumns.

Remarks

The LVITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM, LVM_INSERTITEM, and LVM_DELETEITEM.

Use the last three items in this structure to insert an item into a tile view.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMITEMACTIVATE

Contains information about an LVN_ITEMACTIVATE notification message.

typedef struct tagNMITEMACTIVATE{
    NMHDR   hdr;
    int     iItem;
    int     iSubItem;
    UINT    uNewState;
    UINT    uOldState;
    UINT    uChanged;
    POINT   ptAction;
    LPARAM  lParam;
    UINT    uKeyFlags;
} NMITEMACTIVATE, FAR *LPNMITEMACTIVATE;

Members

hdr
NMHDR structure that contains information about this notification message.
iItem
Index of the list-view item. If the item index is not used for the notification, this member will contain -1.
iSubItem
One-based index of the subitem. If the subitem index is not used for the notification or the notification does not apply to a subitem, this member will contain zero.
uNewState
New item state. This member is zero for notification messages that do not use it.
uOldState
Old item state. This member is zero for notification messages that do not use it.
uChanged
Set of flags that indicate the item attributes that have changed. This member is zero for notifications that do not use it. Otherwise, it can have the same values as the mask member of the LVITEM structure.
ptAction
POINT structure that indicates the location at which the event occurred. This member is undefined for notification messages that do not use it.
lParam
Application-defined value of the item. This member is undefined for notification messages that do not use it.
uKeyFlags
Modifier keys that were pressed at the time of the activation. This member contains zero or a combination of the following flags:
LVKF_ALT | The ALT key is pressed.
LVKF_CONTROL | The CTRL key is pressed.
LVKF_SHIFT | The SHIFT key is pressed.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMLISTVIEW

Contains information about a list-view notification message. This structure is the same as the NM_LISTVIEW structure but has been renamed to fit standard naming conventions.

typedef struct tagNMLISTVIEW{
    NMHDR   hdr;
    int     iItem;
    int     iSubItem;
    UINT    uNewState;
    UINT    uOldState;
    UINT    uChanged;
    POINT   ptAction;
    LPARAM  lParam;
} NMLISTVIEW, FAR *LPNMLISTVIEW;

Members

hdr
NMHDR structure that contains information about this notification message.
iItem
Identifies the list-view item, or -1 if not used.
iSubItem
Identifies the subitem, or zero if none.
uNewState
New item state. This member is zero for notification messages that do not use it.
uOldState
Old item state. This member is zero for notification messages that do not use it.
uChanged
Set of flags that indicate the item attributes that have changed. This member is zero for notifications that do not use it. Otherwise, it can have the same values as the mask member of the LVITEM structure.
ptAction
POINT structure that indicates the location at which the event occurred. This member is undefined for notification messages that do not use it.
lParam
Application-defined value of the item. This member is undefined for notification messages that do not use it.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMLVCACHEHINT

Contains information used to update the cached item information for use with a virtual list view.

typedef struct tagNMLVCACHEHINT {
    NMHDR   hdr;
    int     iFrom;
    int     iTo;
} NMLVCACHEHINT, *PNMLVCACHEHINT;

Members

hdr
NMHDR structure that contains information about this notification message.
iFrom
Starting index of the requested range of items. This value is inclusive.
iTo
Ending index of the requested range of items. This value is inclusive.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMLVCUSTOMDRAW

Contains information specific to an NM_CUSTOMDRAW notification message sent by a list-view control.

typedef struct tagNMLVCUSTOMDRAW {
    NMCUSTOMDRAW nmcd;
    COLORREF clrText;
    COLORREF clrTextBk;
#if (_WIN32_IE >= 0x0400)
    int iSubItem;
#endif
} NMLVCUSTOMDRAW, *LPNMLVCUSTOMDRAW;

Members

nmcd
NMCUSTOMDRAW structure that contains general custom draw information.
clrText
COLORREF value representing the color that will be used to display text foreground in the list-view control.
clrTextBk
COLORREF value representing the color that will be used to display text background in the list-view control.
iSubItem
Version 4.71. Index of the subitem that is being drawn. If the main item is being drawn, this member will be zero.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMLVDISPINFO

Contains information about an LVN_GETDISPINFO or LVN_SETDISPINFO notification message. This structure is the same as the LV_DISPINFO structure, but has been renamed to fit standard naming conventions.

typedef struct tagLVDISPINFO {
    NMHDR hdr;
    LVITEM item;
} NMLVDISPINFO, FAR *LPNMLVDISPINFO;

Members

hdr
NMHDR structure that contains information about this notification message.
item
LVITEM structure that identifies the item or subitem. The structure either contains or receives information about the item. The mask member contains a set of bit flags that specify which item attributes are relevant. You can set one or more of the following bit flags:
LVIF_DI_SETITEM | Set this flag when processing LVN_GETDISPINFO, so the listview control will retain the supplied information and not request it again.
LVIF_IMAGE | The iImage member specifies, or is to receive, the index of the item's icon in the image list.
LVIF_STATE | The state member specifies, or is to receive, the state of the item.
LVIF_TEXT | The pszText member specifies the new item text or the address of a buffer that is to receive the item text.

If the LVITEM structure is receiving item text, the pszText and cchTextMax members specify the address and size of a buffer. You can either copy text to the buffer or assign the address of a string to the pszText member. In the latter case, you must not change or delete the string until the corresponding item text is deleted or two additional LVN_GETDISPINFO messages have been sent.

If you are handling the LVN_GETDISPINFO message, you can set the LVIF_DI_SETITEM flag in the mask member of the LVITEM structure. This tells the operating system to store the requested list item information and not ask for it again. For list-view controls with the LVS_REPORT style, this flag only applies to the first (subitem 0) column's information. The control will not store information for subitems.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMLVFINDITEM

Contains information the owner needs to find items requested by a virtual list view control. This structure is used with the LVN_ODFINDITEM notification message.

typedef struct _NMLVFINDITEM {
    NMHDR hdr;
    int iStart;
    LVFINDINFO lvfi;
} NMLVFINDITEM, *PNMLVFINDITEM;

Members

hdr
NMHDR structure that contains information on this notification message.
iStart
Index of the item at which the search will start.
lvfi
LVFINDINFO structure that contains information necessary to perform a search.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMLVGETINFOTIP

Contains and receives list-view item information needed to display a ToolTip for an item. This structure is used with the LVN_GETINFOTIP notification message.

typedef struct tagNMLVGETINFOTIP{
    NMHDR hdr;
    DWORD dwFlags;
    LPTSTR pszText;
    int cchTextMax;
    int iItem;
    int iSubItem;
    LPARAM lParam;
} NMLVGETINFOTIP, *LPNMLVGETINFOTIP;

Members

hdr
NMHDR structure that contains information on this notification message.
dwFlags
Either zero or LVGIT_UNFOLDED.
pszText
Address of a string buffer that receives any additional text information. If dwFlags is zero, this member will contain the existing item text. In this case, you should append any additional text onto the end of this string. The size of this buffer is specified by the ccTextMax structure.
cchTextMax
Size, in characters, of the buffer pointed to by pszText. Although you should never assume that this buffer will be of any particular size, the INFOTIPSIZE value can be used for design purposes.
iItem
Zero-based index of the item to which this structure refers.
iSubItem
One-based index of the subitem to which this structure refers. If this member is zero, the structure is referring to the item and not a subitem. This member is not currently used and will always be zero.
lParam
Application-defined value associated with the item. This member is not currently used and will always be zero.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMLVKEYDOWN

Contains information used in processing the LVN_KEYDOWN notification message. This structure is the same as the LV_KEYDOWN structure but has been renamed to fit standard naming conventions.

typedef struct tagLVKEYDOWN {
    NMHDR hdr;
    WORD  wVKey;
    UINT  flags;
} NMLVKEYDOWN, FAR *LPNMLVKEYDOWN;

Members

hdr
NMHDR structure that contains additional information about the notification message.
wVKey
Virtual key code.
flags
This member must always be zero.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMLVODSTATECHANGE

Structure that contains information for use in processing the LVN_ODSTATECHANGED notification message.

typedef struct tagNMLVODSTATECHANGE {
    NMHDR hdr;
    int   iFrom;
    int   iTo;
    UINT  uNewState;
    UINT  uOldState;
} NMLVODSTATECHANGE, FAR *LPNMLVODSTATECHANGE;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iFrom
Zero-based index of the first item in the range of items.
iTo
Zero-based index of the last item in the range of items.
uNewState and uOldState
Values indicating the new and old states for the item or items. These members can be any valid combination of the list-view item states.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Listview1

List-View Sample Application

This sample program implements a simple Hello application with a list-view control added. It is implemented in the following source files:

  • Hello.c: The C source code.
  • Hello.h: The header file for Hello.c.
  • Hello.rc: The Resource file.


HELLO.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:ListView1

--*/

/**************************************************************
This is the simple Hello program with three application-defined
functions added. CreateListView creates a list-view control.
OnGetDispInfo and OnEndLabelEdit handle notification messages.
CreateListView creates a list view with three columns. The icon
files used to create the image lists are not included.
**************************************************************/

#include <windows.h>
#include <commctrl.h>
#include "hello.h"

long PASCAL WndProc (HWND, UINT, WPARAM, LPARAM);
HWND CreateListView (HWND);
VOID OnGetDispInfo(NMLVDISPINFO *);
BOOL OnEndLabelEdit(NMLVDISPINFO *);

HINSTANCE hInst;
HWND hWndListView;

// Used for subitems.
PETINFO rgPetInfo [ ] =
{
{"Dog", "Poodle", "$300.00"},
{"Cat", "Siamese", "$100.00"},
{"Fish", "Angel Fish", "$10.00"},
};

int APIENTRY WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,
     LPSTR lpszCmdParam, int nCmdShow)
{
    static char    szAppName[ ] = "HelloWin";
    HWND           hwnd;
    MSG            msg;
    WNDCLASS       wndclass;

    if (!hPrevInstance)
    {
        wndclass.style          = CS_HREDRAW|CS_VREDRAW;
        wndclass.lpfnWndProc    = WndProc;
        wndclass.cbClsExtra     = 0;
        wndclass.cbWndExtra     = 0;
        wndclass.hInstance      = hInstance;
        wndclass.hIcon          = LoadIcon (NULL,
                                  IDI_APPLICATION);
        wndclass.hCursor        = LoadCursor (NULL, IDC_ARROW);
        wndclass.hbrBackground  = GetStockObject (WHITE_BRUSH);
        wndclass.lpszMenuName   = NULL;
        wndclass.lpszClassName  = szAppName;

        RegisterClass (&wndclass);
    }

    hInst = hInstance;
    hwnd = CreateWindow(szAppName,
                "The List-View Program - ICON VIEW",
                WS_OVERLAPPEDWINDOW,
                CW_USEDEFAULT,
                CW_USEDEFAULT,
                CW_USEDEFAULT,
                CW_USEDEFAULT,
                NULL,
                NULL,
                hInstance,
                NULL);

    ShowWindow (hwnd, nCmdShow);
    UpdateWindow (hwnd);

    while (GetMessage (&msg, NULL, 0, 0))
    {
        TranslateMessage (&msg);
        DispatchMessage (&msg);
    }
    return msg.wParam;
}

long APIENTRY WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
    {
    switch (message)
        {
        case WM_CREATE:
                   CreateListView (hwnd);
                   return 0;
        case WM_NOTIFY:
                   // Process notification messages.
                   switch (((LPNMHDR) lParam)->code)
                   {
                   // Fill subitems.
                   case LVN_GETDISPINFO:
                      OnGetDispInfo((NMLVDISPINFO *) lParam);
                      break;
                   // Change labels.
                   case LVN_ENDLABELEDIT:
                      return OnEndLabelEdit(
                      (NMLVDISPINFO *) lParam );
                      break;
                   }
                   return 0;
                case WM_DESTROY:
                   PostQuitMessage (0);
                   return 0;
        }

    return DefWindowProc (hwnd, message, wParam, lParam);
    }

HWND CreateListView (HWND hWndParent)
{
RECT rcl;
HICON hIcon;
int index;
HIMAGELIST hSmall, hLarge;
LV_COLUMN lvC;
char szText[50];
LV_ITEM lvI;
INITCOMMONCONTROLSEX icex;

// Ensure that the common control DLL is loaded.
icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
icex.dwICC  = ICC_LISTVIEW_CLASSES;
InitCommonControlsEx(&icex);

GetClientRect(hWndParent, &rcl);

// Create a list-view control in icon view.
hWndListView = CreateWindowEx(0L, WC_LISTVIEW, "", WS_VISIBLE | WS_CHILD |
                          WS_BORDER | LVS_ICON | LVS_EDITLABELS | WS_EX_CLIENTEDGE,
                          0, 0, rcl.right - rcl.left, rcl.bottom - rcl.top, hWndParent,
                          (HMENU) ID_LISTVIEW, hInst, NULL);
if(hWndListView == NULL)
  return NULL;

// Create the image lists.
hSmall = ImageList_Create(16, 16, FALSE, 3, 0);
hLarge = ImageList_Create(32, 32, FALSE, 3, 0);
for(index = 500; index < 503; index++)     // Index is based on IDs
{                                          // of icons. These are
                                           // assigned in the header
                                           // file.
    hIcon = LoadIcon (hInst, MAKEINTRESOURCE(index));
        ImageList_AddIcon(hSmall, hIcon);
    ImageList_AddIcon(hLarge, hIcon);
}

// Check to be sure that the icons are in the image list.
if(ImageList_GetImageCount(hSmall) < 3)
   return FALSE;
if(ImageList_GetImageCount(hLarge) < 3)
   return FALSE;

// Set the image lists.
ListView_SetImageList(hWndListView, hSmall, LVSIL_SMALL);
ListView_SetImageList(hWndListView, hLarge, LVSIL_NORMAL);

// Create columns.
lvC.mask = LVCF_FMT | LVCF_WIDTH | LVCF_TEXT | LVCF_SUBITEM;
lvC.fmt = LVCFMT_LEFT;
lvC.cx = 75;
lvC.pszText = szText;

// Load the column labels from the resource file.
for (index = 0; index < 3; index++)
{
    lvC.iSubItem = index;
    LoadString(hInst, IDS_PETS + index, szText, sizeof(szText));
    if(ListView_InsertColumn(hWndListView, index, &lvC) == -1)
        return NULL;
}

// Insert items.
lvI.mask = LVIF_TEXT | LVIF_IMAGE | LVIF_STATE;
lvI.state = 0;
lvI.stateMask = 0;

for (index = 0; index < 3; index++)
{
    lvI.iItem = index;
    lvI.iImage = index;
    lvI.iSubItem = 0;
    lvI.pszText = LPSTR_TEXTCALLBACK;

if(ListView_InsertItem(hWndListView, &lvI) == -1)
return NULL;
}

return (hWndListView);
}

// OnGetDispInfo - processes the LVN_GETDISPINFO
// notification message.

 VOID OnGetDispInfo(NMLVDISPINFO *plvdi)
 {
  switch (plvdi->item.iSubItem)
    {
    case 0:
      plvdi->item.pszText = rgPetInfo[plvdi->item.iItem].szKind;
      break;
    case 1:
      plvdi->item.pszText = rgPetInfo[plvdi->item.iItem].szBreed;
      break;
    case 2:
      plvdi->item.pszText = rgPetInfo[plvdi->item.iItem].szPrice;
      break;
    default:
      break;
    }
 }

 // OnEndLabelEdit - processes the LVN_ENDLABELEDIT
 // notification message.
 // Returns TRUE if the label is changed, or FALSE otherwise.

 BOOL OnEndLabelEdit(NMLVDISPINFO *plvdi)
 {
    if (plvdi->item.iItem == -1)
        return FALSE;

    // Copy the new label text to the application-defined structure.
    lstrcpyn(rgPetInfo[plvdi->item.iItem].szKind,
            plvdi->item.pszText, 10);

    return TRUE;
    // To make a more robust application you should send an EM_LIMITTEXT
    // message to the edit control to prevent the user from entering too
    // many characters in the field.
 }

Built on: Wednesday, October 20, 1999


HELLO.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/

#define IDS_PETS 10
#define IDS_BREED 11
#define IDS_PRICE 12

#define ID_LISTVIEW 400

#define DOG_ICO   500
#define CAT_ICO   501
#define FISH_ICO  502

#define IDS_COL1  600
#define IDS_COL2  601
#define IDS_COL3  602

typedef struct tagPETINFO
{
    char szKind[10];
    char szBreed[50];
    char szPrice[20];
}PETINFO;

Built on: Wednesday, October 20, 1999


HELLO.RC

#include "hello.h"

STRINGTABLE
{
IDS_PETS, "PET"
IDS_BREED, "TYPE"
IDS_PRICE, "PRICE"
}

DOG_ICO            ICON  DISCARDABLE   "dog.ico"
CAT_ICO            ICON  DISCARDABLE   "cat.ico"
FISH_ICO           ICON  DISCARDABLE   "fish.ico"

Built on: Wednesday, October 20, 1999


Palletized

Palletized Sample Application

This sample program implements the Palletized application. It is implemented in the following source files:

  • Palletized.cpp: The C source code.
  • Resource.h: The header file for Palletized.c.
  • Palletized.rc: The Resource file.


PALLETIZED.CPP

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:Palletized

--*/

// Palettized List View
// By MarkFi, April 1998
// Requires at least COMCTL32 4.70 (IE3)

// Included files
#include <windows.h>
#include <commctrl.h>
#include "resource.h"

// Global variables
HWND hLV = NULL;
HPALETTE hLVPalette = NULL;

// Create palette from DIB Section
HPALETTE CreateDIBSectionPalette(HBITMAP hBitmap)
{
    BITMAP bm;
    HPALETTE hPalette;

    // Get the color depth of the DIBSection
    GetObject(hBitmap,sizeof(BITMAP),&bm);
    // If the DIBSection is 256 color or less, it has a color table
    if((bm.bmBitsPixel*bm.bmPlanes) <= 8)
    {
        HDC hMemDC;
        HBITMAP hOldBitmap;
        RGBQUAD rgb[256];
        LPLOGPALETTE pLogPal;
        WORD i;
        int nColors;

        // Find out how many colors are in the color table
        nColors = 1 << (bm.bmBitsPixel*bm.bmPlanes);
        // Create a memory DC and select the DIBSection into it
        hMemDC = CreateCompatibleDC(NULL);
        hOldBitmap = SelectObject(hMemDC,hBitmap);
        // Get the DIBSection's color table
        GetDIBColorTable(hMemDC,0,nColors,rgb);
        // Create a palette from the color table
        pLogPal = malloc(sizeof(LOGPALETTE)+(nColors*sizeof(PALETTEENTRY)));
        pLogPal->palVersion = 0x300;
        pLogPal->palNumEntries = nColors;
        for(i=0;i<nColors;i++)
        {
            pLogPal->palPalEntry[i].peRed = rgb[i].rgbRed;
            pLogPal->palPalEntry[i].peGreen = rgb[i].rgbGreen;
            pLogPal->palPalEntry[i].peBlue = rgb[i].rgbBlue;
            pLogPal->palPalEntry[i].peFlags = 0;
        }
        hPalette = CreatePalette(pLogPal);
        // Clean up
        free(pLogPal);
        SelectObject(hMemDC,hOldBitmap);
        DeleteDC(hMemDC);
    }
    else   // It has no color table
        return NULL;

    return hPalette;
}

// Main window procedure
LRESULT CALLBACK WndProc(HWND hwnd,UINT iMsg,WPARAM wParam,LPARAM lParam)
{
    switch(iMsg)
    {
        case WM_NOTIFY:
        {
            // Handle custom draw notifications
            LPNMHDR pNM = (LPNMHDR)lParam;
            if(pNM->hwndFrom == hLV && pNM->code == NM_CUSTOMDRAW)
            {
                // Custom draw from List View
                LPNMLVCUSTOMDRAW pCD = (LPNMLVCUSTOMDRAW)lParam;
                if(pCD->nmcd.dwDrawStage == CDDS_PREPAINT)
                    return CDRF_NOTIFYITEMDRAW;
                else if(pCD->nmcd.dwDrawStage == CDDS_ITEMPREPAINT)
                {
                    // Select and realize palette
                    SelectPalette(pCD->nmcd.hdc,hLVPalette,FALSE);
                    RealizePalette(pCD->nmcd.hdc);
                    return CDRF_DODEFAULT;
                }
            }
        }
            break;

        case WM_QUERYNEWPALETTE:
        case WM_PALETTECHANGED:
            // Invalidate List View to refresh palette
            InvalidateRect(hLV,NULL,FALSE);
            break;

        case WM_COMMAND:
            // Check for menu selection
            if(!HIWORD(wParam))
            {
                BOOL bHandled = TRUE;
                LONG dNotView = ~(LVS_ICON|LVS_SMALLICON|LVS_LIST|LVS_REPORT);
                // Menu selection
                switch(LOWORD(wParam))
                {
                    case IDM_ICON:
                        SetWindowLong(hLV,GWL_STYLE,GetWindowLong(hLV,GWL_STYLE)&dNotView|LVS_ICON);
                        break;

                    case IDM_SMALLICON:
                        SetWindowLong(hLV,GWL_STYLE,GetWindowLong(hLV,GWL_STYLE)&dNotView|LVS_SMALLICON);
                        break;

                    case IDM_LIST:
                        SetWindowLong(hLV,GWL_STYLE,GetWindowLong(hLV,GWL_STYLE)&dNotView|LVS_LIST);
                        break;

                    case IDM_REPORT:
                        SetWindowLong(hLV,GWL_STYLE,GetWindowLong(hLV,GWL_STYLE)&dNotView|LVS_REPORT);
                        break;

                    case IDM_ALIGNLEFT:
                        ListView_Arrange(hLV,LVA_ALIGNLEFT);
                        break;

                    case IDM_ALIGNTOP:
                        ListView_Arrange(hLV,LVA_ALIGNTOP);
                        break;

                    case IDM_DEFAULT:
                        ListView_Arrange(hLV,LVA_DEFAULT);
                        break;

                    case IDM_SNAPTOGRID:
                        ListView_Arrange(hLV,LVA_SNAPTOGRID);
                        break;

                    default:
                        bHandled = FALSE;
                        break;
                }

                if(bHandled)
                    return 0;
            }
            break;

        case WM_SIZE:
        {
            RECT rectClient;
            GetClientRect(hwnd,&rectClient);
            SetWindowPos(hLV,NULL,0,0,rectClient.right-rectClient.left,rectClient.bottom-rectClient.top,SWP_NOZORDER|SWP_NOACTIVATE|SWP_NOMOVE);
        }
            break;

        case WM_DESTROY:
            PostQuitMessage(0);
            return 0;
    }
    return DefWindowProc(hwnd,iMsg,wParam,lParam);
}

int WINAPI WinMain(HINSTANCE hInstance,HINSTANCE hPrevInstance,PSTR szCmdLine,int iCmdShow)
{
    static char szAppName[ ] = "SimpleLV";
    HWND hwnd;
    MSG msg;
    RECT rectClient;
    WNDCLASSEX wndclass;

    // Initialize common controls
    InitCommonControls();

    // Setup window class
    wndclass.cbSize = sizeof(wndclass);
    wndclass.style = CS_HREDRAW|CS_VREDRAW;
    wndclass.lpfnWndProc = WndProc;
    wndclass.cbClsExtra = 0;
    wndclass.cbWndExtra = 0;
    wndclass.hInstance = hInstance;
    wndclass.hIcon = LoadIcon(NULL,IDI_APPLICATION);
    wndclass.hCursor = LoadCursor(NULL,IDC_ARROW);
    wndclass.hbrBackground = (HBRUSH)GetStockObject(WHITE_BRUSH);
    wndclass.lpszMenuName = NULL;
    wndclass.lpszClassName = szAppName;
    wndclass.hIconSm = LoadIcon(NULL,IDI_APPLICATION);

    RegisterClassEx(&wndclass);

    // Create main window
    hwnd = CreateWindowEx(0,szAppName,"Palettized List View",WS_OVERLAPPEDWINDOW,275,200,400,300,NULL,NULL,hInstance,NULL);
    SetMenu(hwnd,LoadMenu(hInstance,MAKEINTRESOURCE(IDR_MENU)));

    GetClientRect(hwnd,&rectClient);

    // Create and fill list view
    hLV = CreateWindowEx(0,WC_LISTVIEW,NULL,WS_CHILD|WS_VISIBLE,0,0,rectClient.right-rectClient.left,
        rectClient.bottom-rectClient.top,hwnd,NULL,hInstance,NULL);

    {
        LPSTR pLabel[ ] = { "Mercury","Venus","Earth","Mars","Jupiter","Saturn","Uranus","Neptune","Pluto" };
        CHAR szLabel[81];
        HIMAGELIST hILLarge;
        HIMAGELIST hILSmall;
        HBITMAP hBitmap;
        LVITEM lvItem;
        LVCOLUMN lvColumn;
        INT dIndex;
        INT x;
        INT y;

        // Create image lists as DIB Section 24-bit color
        // Large image list
        hILLarge = ImageList_Create(32,32,ILC_COLOR24|ILC_MASK,9,1);
        hBitmap = LoadImage(hInstance,MAKEINTRESOURCE(IDB_PLANETS),IMAGE_BITMAP,0,0,LR_CREATEDIBSECTION);

        // Get palette of large bitmap and use as List-View's palette
        hLVPalette = CreateDIBSectionPalette(hBitmap);

        ImageList_AddMasked(hILLarge,hBitmap,RGB(0,255,255));
        DeleteObject(hBitmap);

        // Small image list
        hILSmall = ImageList_Create(16,16,ILC_COLOR24|ILC_MASK,9,1);
        hBitmap = LoadImage(hInstance,MAKEINTRESOURCE(IDB_PLANETSSMALL),IMAGE_BITMAP,0,0,LR_CREATEDIBSECTION);
        ImageList_AddMasked(hILSmall,hBitmap,RGB(0,255,255));
        DeleteObject(hBitmap);

        // Assign image lists to control
        ListView_SetImageList(hLV,hILLarge,LVSIL_NORMAL);
        ListView_SetImageList(hLV,hILSmall,LVSIL_SMALL);

        // Add columns
        lvColumn.mask = LVCF_TEXT|LVCF_WIDTH;
        lvColumn.cx = 125;
        lvColumn.pszText = szLabel;

        // Column 0
        strcpy(szLabel,"Column 2");
        ListView_InsertColumn(hLV,0,&lvColumn);

        // Column 1
        strcpy(szLabel,"Column 1");
        ListView_InsertColumn(hLV,0,&lvColumn);

        // Column 2
        strcpy(szLabel,"Column 0");
        ListView_InsertColumn(hLV,0,&lvColumn);

        // Add items
        ZeroMemory(&lvItem,sizeof(LVITEM));
        for(x=8;x>=0;x--)
        {
            lvItem.mask = LVIF_TEXT|LVIF_IMAGE;
            lvItem.iItem = 0;
            lvItem.iSubItem = 0;
            lvItem.pszText = pLabel[x];
            lvItem.iImage = x;

            dIndex = ListView_InsertItem(hLV,&lvItem);

            // Add subitems
            for(y=1;y<3;y++)
            {
                lvItem.mask = TVIF_TEXT;
                lvItem.iItem = dIndex;
                lvItem.iSubItem = y;
                lvItem.pszText = szLabel;
                wsprintf(szLabel,"Sub Item %d,%d",x,y-1);

                ListView_SetItem(hLV,&lvItem);
            }
        }
    }

    // Show main window
    ShowWindow(hwnd,iCmdShow);
    UpdateWindow(hwnd);

    // Message loop
    while(GetMessage(&msg,NULL,0,0))
    {
        TranslateMessage(&msg);
        DispatchMessage(&msg);
    }

    return msg.wParam;
}

Built on: Wednesday, October 20, 1999


PALLETIZED.RC

//Microsoft Developer Studio generated resource script.
//
#include "resource.h"

#define APSTUDIO_READONLY_SYMBOLS
/////////////////////////////////////////////////////////////////////////////
//
// Generated from the TEXTINCLUDE 2 resource.
//
#include "afxres.h"

/////////////////////////////////////////////////////////////////////////////
#undef APSTUDIO_READONLY_SYMBOLS

/////////////////////////////////////////////////////////////////////////////
// English (U.S.) resources

#if !defined(AFX_RESOURCE_DLL) || defined(AFX_TARG_ENU)
#ifdef _WIN32
LANGUAGE LANG_ENGLISH, SUBLANG_ENGLISH_US
#pragma code_page(1252)
#endif //_WIN32

/////////////////////////////////////////////////////////////////////////////
//
// Menu
//

IDR_MENU MENU DISCARDABLE
BEGIN
    POPUP "View"
    BEGIN
        MENUITEM "Icon",                        IDM_ICON
        MENUITEM "Small Icon",                  IDM_SMALLICON
        MENUITEM "List",                        IDM_LIST
        MENUITEM "Report",                      IDM_REPORT
    END
    POPUP "Arrange"
    BEGIN
        MENUITEM "Align Left",                  IDM_ALIGNLEFT
        MENUITEM "Align Top",                   IDM_ALIGNTOP
        MENUITEM "Default",                     IDM_DEFAULT
        MENUITEM "Snap To Grid",                IDM_SNAPTOGRID
    END
END

#ifdef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// TEXTINCLUDE
//

1 TEXTINCLUDE DISCARDABLE
BEGIN
    "resource.h\0"
END

2 TEXTINCLUDE DISCARDABLE
BEGIN
    "#include ""afxres.h""\r\n"
    "\0"
END

3 TEXTINCLUDE DISCARDABLE
BEGIN
    "\r\n"
    "\0"
END

#endif    // APSTUDIO_INVOKED

/////////////////////////////////////////////////////////////////////////////
//
// Bitmap
//

IDB_PLANETS             BITMAP  DISCARDABLE     "Planets 256.bmp"
IDB_PLANETSSMALL        BITMAP  DISCARDABLE     "Planets Small 256.bmp"
#endif    // English (U.S.) resources
/////////////////////////////////////////////////////////////////////////////

#ifndef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// Generated from the TEXTINCLUDE 3 resource.
//

/////////////////////////////////////////////////////////////////////////////
#endif    // not APSTUDIO_INVOKED

Built on: Wednesday, October 20, 1999


RESOURCE.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
//{{NO_DEPENDENCIES}}
// Microsoft Developer Studio generated include file.
// Used by Palettized List View.rc
//
#define IDR_MENU1                       101
#define IDR_MENU                        101
#define IDB_LARGE                       102
#define IDB_SMALL                       103
#define IDB_STATE                       104
#define IDB_PLANETS                     104
#define IDB_PLANETSSMALL                105
#define IDM_ICON                        40001
#define IDM_SMALLICON                   40002
#define IDM_LIST                        40003
#define IDM_REPORT                      40004
#define IDM_ALIGNLEFT                   40005
#define IDM_ALIGNTOP                    40006
#define IDM_DEFAULT                     40007
#define IDM_SNAPTOGRID                  40008

// Next default values for new objects
//
#ifdef APSTUDIO_INVOKED
#ifndef APSTUDIO_READONLY_SYMBOLS
#define _APS_NEXT_RESOURCE_VALUE        106
#define _APS_NEXT_COMMAND_VALUE         40009
#define _APS_NEXT_CONTROL_VALUE         1000
#define _APS_NEXT_SYMED_VALUE           101
#endif
#endif

Built on: Wednesday, October 20, 1999


Month Calendar Controls

A month calendar control implements a calendar-like user interface. This provides the user with a very intuitive and recognizable method of entering or selecting a date. The control also provides the application with the means to obtain and set the date information in the control using existing data types.

  • About Month Calendar Controls
  • Using Month Calendar Controls
  • Month Calendar Control Reference

About Month Calendar Controls

The month calendar control is implemented in version 4.70 and later of Comctl32.dll. It provides a simple and intuitive way for a user to select a date from a familiar interface. The following illustration shows a month calendar control in a dialog box.

Month calendar control in a dialog box.

An application creates a month calendar control by calling the CreateWindowEx function and specifying MONTHCAL_CLASS as the window class. The class is registered when the month calendar class is loaded from the common controls dynamic-link library (DLL). Register this class by calling the InitCommonControlsEx function, specifying the ICC_DATE_CLASSES bit flag in the accompanying INITCOMMONCONTROLSEX structure.

Notes:

  • Microsoft® Windows® does not support dates prior to 1601. See FILETIME for details.
  • The month-calendar control is based on the Gregorian calendar, which was introduced in 1753. It will not calculate dates that are consistent with the Julian calendar that was in use prior to 1753.

The Month Calendar Control User Interface

The month calendar control user interface allows the user to select a date from the displayed days or change the control's display in various ways.

  • Scrolling the control's display.

    By default, when a user clicks the arrow buttons in the top left or top right of the month calendar control, the control updates its display to show the previous or next month. If the month calendar control is displaying more than one month at a time, the display changes by the number of months currently in view. That is, if the month calendar displays January, February, and March and the user clicks the top right arrow button, the control updates its display to show April, May, and June. The user can also perform the same action by clicking the partial months displayed before the first month and after the last month.

    The following keyboard commands can also be used to change the current month.

      PAGE UP (VK_NEXT)
      Move to the next month.
      PAGE DOWN (VK_PRIOR)
      Move to the previous month.
      HOME (VK_HOME)
      Move to the first day of the current month.
      END (VK_END)
      Move to the last day of the current month.
      CTRL + HOME
      Move to the first visible month.
      CTRL + END
      Move to the last visible month.

    An application can change the number of months by which the control updates its display by using the MCM_SETMONTHDELTA message or the corresponding macro, MonthCal_SetMonthDelta. However, the PAGE UP and PAGE DOWN keys change the selected month by one, regardless of the number of months displayed or the value set by MCM_SETMONTHDELTA.

  • Selecting a nonadjacent month.

    When a user clicks the name of a displayed month, a pop-up menu appears that lists all months within the year. The user can select a month on the list. If the user's selection is not visible, the month calendar control scrolls its display to show the chosen month.

  • Selecting a different year.

    If the user clicks the year displayed next to a month name, an up-down control appears in place of the year. The user can change the year with this control. The month calendar control updates its display for the selected year when the up-down control loses focus. The related keyboard commands are:

      CTRL + VK_NEXT
      Move to the next year.
      CTRL + VK_PRIOR
      Move to the previous year.

  • Selecting the current day.

    If a month calendar control is not using the MCS_NOTODAY style, the user can return to the current day by clicking the "Today" text at the bottom of the control. If the current day is not visible, the control updates its display to show it. Related keyboard commands are:

      VK_LEFT
      Move to the previous day.
      VK_RIGHT.
      Move to the next day.
      VK_UP
      Move to the previous week.
      VK_DOWN
      Move to the next week.

Day States

Month calendar controls that use the MCS_DAYSTATE style support day states. The control uses day state information to determine how it draws specific days within the control. Day state information is expressed as a 32-bit data type, MONTHDAYSTATE. Each bit in a MONTHDAYSTATE bit field (1 through 31) represents the state of a day in a month. If a bit is on, the corresponding day will be displayed in bold; otherwise, it will be displayed with no emphasis.

An application can explicitly set day state information by sending the MCM_SETDAYSTATE message or by using the corresponding macro, MonthCal_SetDayState. Additionally, month calendar controls that use the MCS_DAYSTATE style send MCN_GETDAYSTATE notification messages to request day state information. For more information on supporting day states, see Processing the MCN_GETDAYSTATE Notification Message and Preparing the MONTHDAYSTATE Array.

Month Calendar Control Styles

Month calendar controls have several styles that determine their appearance and behavior. When you create the control using CreateWindowEx, include the desired styles in the dwStyle parameter.

After creating the control, you can change all of the styles except for MCS_DAYSTATE and MCS_MULTISELECT. To change these styles, you will need to destroy the existing control and create a new one that has the desired styles. To retrieve or change any other window styles, use the GetWindowLong and SetWindowLong functions.

Month calendar controls that use the MCS_MULTISELECT style allow the user to select a range of days. By default, the control allows the user to select seven contiguous days. Your application can change the control's default behavior by using the MCM_SETMAXSELCOUNT message or the accompanying macro, MonthCal_SetMaxSelCount.

When a month calendar control uses the MCS_WEEKNUMBERS style, it displays week numbers at the left side of each month. If the MCS_NOTODAY style is applied, the control no longer circles the current day.

The MCS_DAYSTATE style is helpful when you want the control to highlight specific dates by displaying them in bold. For more information, see Day States.

Localization

The month-calendar control gets its format and all strings from LOCALE_USER_DEFAULT. For Windows 2000 and later systems, it gets the month title format from LOCALE_SYEARMONTH. Thus even with the same DLL version, the appearance of the control may vary slightly depending on the system software on which your application runs. For example, with Windows NT 4.0, the month title will look like: "September 1998". With Windows 2000, it will look like: "September, 1998".

Month Calendar Control Notification Messages

A month calendar control sends notification messages when it receives user input or must request day state information (MCS_DAYSTATE style only). The control's parent receives these notifications as WM_NOTIFY messages.

The following notification messages are used with month calendar controls.
Notification | Description
MCN_GETDAYSTATE | Requests information about which days should be displayed in bold. For more information, see Preparing the MONTHDAYSTATE Array.
MCN_SELCHANGE | Notifies the parent that the selected date or range of dates has changed. The control sends this notification when the user explicitly changes the selection within the current month, or when the selection is implicitly changed in response to next/previous month navigation.
MCN_SELECT | Notifies the parent that the user has explicitly selected a date.

Times in the Month Calendar Control

Because the month calendar control cannot be used to select a time, the time related fields of the SYSTEMTIME structure need to be handled differently. When the control is created, it will insert the current time into its "Today" date and time.

When a time is later set programmatically, the control will either copy the time fields as they are or validate them first and then, if invalid, store the current default times. Following is a list of the messages that set a date and a description of how the time fields are treated by the message.

MCM_SETCURSEL | The control will copy the time fields as they are, without validation or modification.
MCM_SETRANGE | The time fields of the structures passed in will be validated. If they are valid, the time fields will be copied without modification. If they are invalid, the control will copy the time fields from the "Today" date and time.
MCM_SETSELRANGE | The time fields of the structures passed in will be validated. If they are valid, the time fields will be copied without modification. If they are invalid, the control will retain the time fields from the current selection ranges.
MCM_SETTODAY | The control will copy the time fields as they are, without validation or modification.

When a date is retrieved from the control, the time fields will be copied from the stored times without modification. Handling of the time fields by the control is provided as a convenience to the programmer. The control does not examine or modify the time fields as a result of any operation other than those listed above.

Using Month Calendar Controls

This section provides information and sample code for implementing month calendar controls.

Creating a Month Calendar Control

To create a month calendar control, use the CreateWindowEx function, specifying MONTHCAL_CLASS as the window class. You must first register the window class by calling the InitCommonControlsEx function, specifying the ICC_DATE_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.

The following example demonstrates how to create a month calendar control in an existing modeless dialog box. Note that the size values passed to CreateWindowEx are all zeros. Because the minimum required size depends on the font the control uses, the DoNotify example function uses the MonthCal_GetMinReqRect macro to request size information and then resizes the control by calling SetWindowPos. If you subsequently change the font with WM_SETFONT, the dimensions of the control will not change. You must call MonthCal_GetMinReqRect again and resize the control to fit the new font.

//   CreateMonthCal -- Creates a month calendar control in a dialog box.
//                   Returns the handle to the month calendar control
//                   if successful, or NULL otherwise.
//
//    hwndOwner   -- Handle to the owner of the dialog box.
//    g_hinst     -- Global handle to the program instance.
//
/////
HWND WINAPI CreateMonthCal(HWND hwndOwner)
{
   HWND hwnd;
   RECT rc;
   INITCOMMONCONTROLSEX icex;

   // Load the window class.
   icex.dwSize = sizeof(icex);
   icex.dwICC  = ICC_DATE_CLASSES;
   InitCommonControlsEx(&icex);

   // Create a modeless dialog box to hold the control.
   g_hwndDlg = CreateDialog(g_hinst,
                     MAKEINTRESOURCE(IDD_DIALOG1),
                     hwndOwner,
                     DlgProc);

   // Create the month calendar.
   hwnd = CreateWindowEx(0,
                     MONTHCAL_CLASS,
                     "",
                     WS_BORDER | WS_CHILD | WS_VISIBLE | MCS_DAYSTATE,
                     0,0,0,0, // resize it later
                     g_hwndDlg,
                     NULL,
                     g_hinst,
                     NULL);

   // Get the size required to show an entire month.
   MonthCal_GetMinReqRect(hwnd, &rc);

// Arbitrary values
#define LEFT 35
#define TOP  40

   // Resize the control now that the size values have been obtained.
   SetWindowPos(hwnd, NULL, TOP, LEFT,
                LEFT + rc.right, TOP + rc.bottom,
                SWP_NOZORDER);

   // Set colors for aesthetics.
   MonthCal_SetColor(hwnd, MCSC_BACKGROUND, RGB(175,175,175));
   MonthCal_SetColor(hwnd, MCSC_MONTHBK, RGB(248,245,225));

   return(hwnd);
}

Processing the MCN_GETDAYSTATE Notification Message

Month calendar controls send the MCN_GETDAYSTATE notification message to request information about how the days within the visible months should be displayed. The following application-defined function, DoNotify, processes MCN_GETDAYSTATE by filling an array of MONTHDAYSTATE values to highlight the 15th day of each month.

DoNotify extracts the number of MONTHDAYSTATE values needed from the cDayState member of the NMDAYSTATE structure that lParam points to. The function then loops to set the 15th bit in each element of the array, using the application-defined BOLDDAY macro.

BOOL WINAPI DoNotify(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
#define BOLDDAY(ds,iDay) if(iDay>0 && iDay<32)\
                            (ds)|=(0x00000001<<(iDay-1))

#define lpnmDS ((NMDAYSTATE *)lParam)
#define MAX_MONTHS 12

   MONTHDAYSTATE mds[MAX_MONTHS];
   INT i, iMax;
   LPNMHDR hdr = (LPNMHDR)lParam;

   switch(hdr->code){
      case MCN_GETDAYSTATE:
         iMax=lpnmDS->cDayState;

         for(i=0;i<iMax;i++){
            mds[i] = (MONTHDAYSTATE)0;
            BOLDDAY(mds[i],15);
         }
         lpnmDS->prgDayState = mds;
         break;
   }
   return FALSE;
}

Preparing the MONTHDAYSTATE Array

Both the MCM_SETDAYSTATE message and MCN_GETDAYSTATE notification message require an array of MONTHDAYSTATE values to determine how dates will be displayed. Each month that the control displays must have a corresponding element within the array.

To support these messages, your application must properly prepare the array. The following is a simple macro that sets a bit in a MONTHDAYSTATE value for a given day within that month.

#define BOLDDAY(ds,iDay) if(iDay>0 && iDay<32)\
                            (ds)|=(0x00000001<<(iDay-1))

Using this macro, an application can loop through an array of important dates, setting bits within the corresponding array elements. This approach is not the most efficient, of course, but works well for many purposes. As long as your application sets MONTHDAYSTATE bits appropriately, it does not matter how those bits were set.


Month Calendar Control Styles

The following are the styles used with month calendar controls.

MCS_DAYSTATE
Version 4.70. The month calendar will send MCN_GETDAYSTATE notifications to request information about which days should be displayed in bold. For more information about supporting this style, see Processing the MCN_GETDAYSTATE Notification Message.
MCS_MULTISELECT
Version 4.70. The month calendar will allow the user to select a range of dates within the control. By default, the maximum range is one week. You can change the maximum range that can be selected by using the MCM_SETMAXSELCOUNT message.
MCS_NOTODAY
Version 4.70. The month calendar control will not display the "today" date at the bottom of the control.
MCS_NOTODAYCIRCLE
Version 4.70. The month calendar control will not circle the "today" date.
MCS_WEEKNUMBERS
Version 4.70. The month calendar control will display week numbers (1-52) to the left of each row of days. Week 1 is defined as the first week that contains at least four days.


Month Calendar Day Numbers

The following list contains the numeric representations of the days of the week that are used by the month calendar control.
Value | Day of Week
0 | Monday
1 | Tuesday
2 | Wednesday
3 | Thursday
4 | Friday
5 | Saturday
6 | Sunday


MCM_GETCOLOR

Retrieves the color for a given portion of a month calendar control. You can send this message explicitly or by using the MonthCal_GetColor macro.

MCM_GETCOLOR
    wParam = (WPARAM)(INT)iColor;
    lParam = 0;

Parameters

iColor
INT value specifying which month calendar color to retrieve. This value can be one of the following:
MCSC_BACKGROUND | Retrieve the background color displayed between months.
MCSC_MONTHBK | Retrieve the background color displayed within the month.
MCSC_TEXT | Retrieve the color used to display text within a month.
MCSC_TITLEBK | Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT | Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. Otherwise, this message returns -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETCURSEL

Retrieves the currently selected date. You can send this message explicitly or by using the MonthCal_GetCurSel macro.

MCM_GETCURSEL
    wParam = 0;
    lParam = (LPARAM) (LPSYSTEMTIME) lpSysTime;

Parameters

lpSysTime
Address of a SYSTEMTIME structure that will receive the currently selected date information. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero if successful, or zero otherwise. This message will always fail when applied to month calendar controls set to the MCS_MULTISELECT style.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETFIRSTDAYOFWEEK

Retrieves the first day of the week for a month calendar control. You can send this message explicitly or by using the MonthCal_GetFirstDayOfWeek macro.

MCM_GETFIRSTDAYOFWEEK
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that contains two values. The high word is a BOOL value that is nonzero if the first day of the week is set to something other than LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low word is an INT value that represents the first day of the week. This will be one of the day numbers.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETMAXSELCOUNT

Retrieves the maximum date range that can be selected in a month calendar control. You can send this message explicitly or by using the MonthCal_GetMaxSelCount macro.

MCM_GETMAXSELCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns an INT value that represents the total number of days that can be selected for the control.

Remarks

You can change the maximum date range that can be selected by using the MCM_SETMAXSELCOUNT message.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETMAXTODAYWIDTH

Retrieves the maximum width of the "today" string in a month calendar control. This includes the label text and the date text. You can send this message explicitly or by using the MonthCal_GetMaxTodayWidth macro.

MCM_GETMAXTODAYWIDTH
    wParam = 0;
    lParam = 0;

Return Values

Returns the width of the "today" string, in pixels.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETMINREQRECT

Retrieves the minimum size required to display a full month in a month calendar control. You can send this message explicitly or by using the MonthCal_GetMinReqRect macro.

MCM_GETMINREQRECT
    wParam = 0;
    lParam = (LPARAM) (LPRECT) lpRectInfo;

Parameters

lpRectInfo
Address of a RECT structure that will receive bounding rectangle information. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero and lpRectInfo receives the applicable bounding information if successful. Otherwise, the message returns zero.

Remarks

The minimum required window size for a month calendar control depends on the currently selected font, control styles, system metrics, and regional settings. When an application changes anything that affects the minimum window size, or processes a WM_SETTINGCHANGE message, it should send MCM_GETMINREQRECT to determine the new minimum size.

Note: The rectangle returned by MCM_GETMINREQRECT does not include the width of the "Today" string, if it is present. If the MCS_NOTODAY style is not set, your application should also retrieve the rectangle that defines the "Today" string width by sending a MCM_GETMAXTODAYWIDTH message. Use the larger of the two rectangles to ensure that the "Today" string is not clipped.

The top and left members of the structure pointed to by lpRectInfo will always be zero. The right and bottom members represent the minimum cx and cy required for the control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETMONTHDELTA

Retrieves the scroll rate for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button. You can send this message explicitly or by using the MonthCal_GetMonthDelta macro.

MCM_GETMONTHDELTA
    wParam = 0;
    lParam = 0;

Return Values

If the month delta was previously set using the MCM_SETMONTHDELTA message, returns an INT value that represents the month calendar's current scroll rate. If the month delta was not previously set using the MCM_SETMONTHDELTA message, or the month delta was reset to the default, returns an INT value that represents the current number of months visible.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETMONTHRANGE

Retrieves date information (using SYSTEMTIME structures) that represents the high and low limits of a month calendar control's display. You can send this message explicitly or by using the MonthCal_GetMonthRange macro.

MCM_GETMONTHRANGE
    wParam = (WPARAM)(DWORD) dwFlag;
    lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

dwFlag
Value specifying the scope of the range limits to be retrieved. This value must be one of the following:
GMR_DAYSTATE | Include preceding and trailing months of visible range that are only partially displayed.
GMR_VISIBLE | Include only those months that are entirely displayed.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the scope specified by dwFlag. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. This parameter must be a valid address and cannot be NULL.

Return Values

Returns an INT value that represents the range, in months, spanned by the two limits returned at lprgSysTimeArray.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETRANGE

Retrieves the minimum and maximum allowable dates set for a month calendar control. You can send this message explicitly or by using the MonthCal_GetRange macro.

MCM_GETRANGE
    wParam = 0;
    lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the date limit information. The minimum limit is set in lprgSysTimeArray[0], and lprgSysTimeArray[1] receives the maximum limit. If either element is set to all zeros, then no corresponding limit is set for the month calendar control. This parameter must be a valid address and cannot be NULL.

Return Values

Returns a DWORD that can be zero (no limits are set) or a combination of the following values that specify limit information:
GDTR_MAX | A maximum limit is set for the control; lprgSysTimeArray[0] is valid and contains the applicable date information.
GDTR_MIN | A minimum limit is set for the control; lprgSysTimeArray[1] is valid and contains the applicable date information.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETSELRANGE

Retrieves date information that represents the upper and lower limits of the date range currently selected by the user. You can send this message explicitly or by using the MonthCal_GetSelRange macro.

MCM_GETSELRANGE
    wParam = 0;
    lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the user's selection. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero if successful, or zero otherwise. MCM_GETSELRANGE will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETTODAY

Retrieves the date information for the date specified as "today" for a month calendar control. You can send this message explicitly or by using the MonthCal_GetToday macro.

MCM_GETTODAY
    wParam = 0;
    lParam = (LPARAM)(LPSYSTEMTIME) lpToday;

Parameters

lpToday
Address of a SYSTEMTIME structure that will receive the date information. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the MonthCal_GetUnicodeFormat macro.

MCM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

MCM_SETUNICODEFORMAT

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_HITTEST

Determines which portion of a month calendar control is at a given point on the screen. You can send this message explicitly or by using the MonthCal_HitTest macro.

MCM_HITTEST
    wParam = 0;
    lParam = (LPARAM)(PMCHITTESTINFO) pMCHitTest;

Parameters

pMCHitTest
Address of an MCHITTESTINFO structure. Upon sending the message, the cbSize member must be set to the size of the MCHITTESTINFO structure, and pt must be set to the point you want to hit test.

Return Values

Sets values in members of the MCHITTESTINFO structure at pMCHitTest and returns a DWORD value that contains one or more of the following:
MCHT_CALENDAR | The given point was within the calendar.
MCHT_CALENDARBK | The given point was in the calendar's background.
MCHT_CALENDARDATE | The given point was on a particular date within the calendar. The SYSTEMTIME structure at lpMCHitTest->st is set to the date at the given point.
MCHT_CALENDARDATENEXT | The given point was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_CALENDARDATEPREV | The given point was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_CALENDARDAY | The given point was over a day abbreviation ("Fri", for example). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the top row.
MCHT_CALENDARWEEKNUM | The given point was over a week number (MCS_WEEKNUMBERS style only). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the leftmost column.
MCHT_NEXT | The given point is in an area that will cause the month calendar to scroll its display to the next month or set of months. This flag is used to modify other hit test flags.
MCHT_NOWHERE | The given point was not on the month calendar control, or it was in an inactive portion of the control.
MCHT_PREV | The given point is in an area that will cause the month calendar to scroll its display to the previous month or set of months. This flag is used to modify other hit test flags.
MCHT_TITLE | The given point was over a month's title.
MCHT_TITLEBK | The given point was over the background of a month's title.
MCHT_TITLEBTNNEXT | The given point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_TITLEBTNPREV | The given point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLEMONTH | The given point was in a month's title bar, over a month name.
MCHT_TITLEYEAR | The given point was in a month's title bar, over the year value.
MCHT_TODAYLINK | The given point was on the "today" link at the bottom of the month calendar control.

The uHit member of the MCHITTESTINFO structure at pMCHitTest will equal the return value.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETCOLOR

Sets the color for a given portion of a month calendar control. You can send this message explicitly or by using the MonthCal_SetColor macro.

MCM_SETCOLOR
    wParam = (WPARAM)(INT) iColor;
    lParam = (LPARAM)(COLORREF) clr;

Parameters

iColor
INT value specifying which month calendar color to set. This value can be one of the following:
MCSC_BACKGROUND | Set the background color displayed between months.
MCSC_MONTHBK | Set the background color displayed within the month.
MCSC_TEXT | Set the color used to display text within a month.
MCSC_TITLEBK | Set the background color displayed in the calendar's title.
MCSC_TITLETEXT | Set the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Set the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.
clr
COLORREF value that represents the color that will be set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, the return is -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETCURSEL

Sets the currently selected date for a month calendar control. If the specified date is not in view, the control updates the display to bring it into view. You can send this message explicitly or by using the MonthCal_SetCurSel macro.

MCM_SETCURSEL
    wParam = 0;
    lParam = (LPARAM)(LPSYSTEMTIME) lpSysTime;

Parameters

lpSysTime
Address of a SYSTEMTIME structure that contains the date to be set as the current selection.

Return Values

Returns nonzero if successful, or zero otherwise. This message will fail if applied to a month calendar control that uses the MCS_MULTISELECT style.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETDAYSTATE

Sets the day states for all months that are currently visible within a month calendar control. You can send this message explicitly or by using the MonthCal_SetDayState macro.

MCM_SETDAYSTATE
    wParam = (WPARAM) iMonths;
    lParam = (LPARAM)(LPMONTHDAYSTATE) lpDayStateArray;

Parameters

iMonths
Value indicating how many elements are in the array that lpDayStateArray points to.
lpDayStateArray
Address of an array of MONTHDAYSTATE values that define how the month calendar control will draw each day in its display.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

The array at lpDayStateArray must contain as many elements as the value returned by the following macro:

MonthCal_GetMonthRange(hwndMC, GMR_DAYSTATE, NULL);

Keep in mind that the array at lpDayStateArray must contain MONTHDAYSTATE values that correspond with all months currently in the control's display, in chronological order. This includes the two months only partially displayed before the first month and after the last month. For more information about preparing your array, see Preparing the MONTHDAYSTATE Array.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETFIRSTDAYOFWEEK

Sets the first day of the week for a month calendar control. You can send this message explicitly or by using the MonthCal_SetFirstDayOfWeek macro.

MCM_SETFIRSTDAYOFWEEK
    wParam = 0;
    lParam = (LPARAM)(INT) iDay;

Parameters

iDay
INT value representing which day is to be set as the first day of the week. This value must be one of the day numbers.

Return Values

Returns a DWORD value that contains two values. The high word is a BOOL value that is nonzero if the previous first day of the week did not equal LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low word is an INT value that represents the previous first day of the week.

Remarks

If the first day of the week is set to anything other than the default (LOCALE_IFIRSTDAYOFWEEK), the control will not automatically update first-day-of-the-week changes based on locale changes.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETMAXSELCOUNT

Sets the maximum number of days that can be selected in a month calendar control. You can send this message explicitly or by using the MonthCal_SetMaxSelCount macro.

MCM_SETMAXSELCOUNT
    wParam = (WPARAM)(INT) iMax;
    lParam = 0;

Parameters

iMax
INT value that will be set to represent the maximum number of days that can be selected.

Return Values

Returns nonzero if successful, or zero otherwise. This message will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETMONTHDELTA

Sets the scroll rate for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button. You can send this message explicitly or by using the MonthCal_SetMonthDelta macro.

MCM_SETMONTHDELTA
    wParam = (WPARAM)(INT) iDelta;
    lParam = 0;

Parameters

iDelta
Value representing the number of months to be set as the control's scroll rate. If this value is zero, the month delta is reset to the default, which is the number of months displayed in the control.

Return Values

Returns an INT value that represents the previous scroll rate. If the scroll rate was not previously set, the return value is zero.

Remarks

The PAGE UP and PAGE DOWN keys, VK_PRIOR and VK_NEXT, change the selected month by one, regardless of the number of months displayed or the value set by MCM_SETMONTHDELTA.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETRANGE

Sets the minimum and maximum allowable dates for a month calendar control. You can send this message explicitly or by using the MonthCal_SetRange macro.

MCM_SETRANGE
    wParam = (WPARAM)(SHORT) fWhichLimit;
    lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

fWhichLimit
Flag values that specify which date limits are being set. This value must be one or both of the following:
GDTR_MAX | The maximum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[1] must contain date information.
GDTR_MIN | The minimum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[0] must contain date information.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that contain the date limits. The maximum limit must be in lpSysTimeArray[1] if GDTR_MAX is specified, and lpSysTimeArray[0] must contain the minimum limit if GDTR_MIN is specified.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETSELRANGE

Sets the selection for a month calendar control to a given date range. You can send this message explicitly or by using the MonthCal_SetSelRange macro.

MCM_SETSELRANGE
    wParam = 0;
    lParam = (LPARAM)(LPSYSTEMTIME) lprgSysTimeArray;

Parameters

lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that contain date information representing the selection limits. The first selected date must be specified in lpSysTimeArray[0], and the last selected date must be specified in lpSysTimeArray[1].

Return Values

Returns nonzero if successful, or zero otherwise. This message will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETTODAY

Sets the "today" selection for a month calendar control. You can send this message explicitly or by using the MonthCal_SetToday macro.

MCM_SETTODAY
    wParam = 0;
    lParam = (LPARAM)(LPSYSTEMTIME) lpSysTime;

Parameters

lpSysTime
Address of a SYSTEMTIME structure that contains the date to be set as the "today" selection for the control. If this parameter is set to NULL, the control returns to the default setting.

Return Values

The return value for this message is not used.

Remarks

If the "today" selection is set to any date other than the default, the following conditions apply:

  • The control will not automatically update the "today" selection when the time passes midnight for the current day.
  • The control will not automatically update its display based on locale changes.

See Also

Times in the Month Calendar Control

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the MonthCal_SetUnicodeFormat macro.

MCM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

MCM_GETUNICODEFORMAT

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetColor

Retrieves the color for a given portion of a month calendar control. You can use this macro or send the MCM_GETCOLOR message explicitly.

COLORREF MonthCal_GetColor(
    HWND hwndMC,
    INT iColor
);

Parameters

hwndMC
Handle to a month calendar control.
iColor
INT value specifying which month calendar color to retrieve. This value can be one of the following:
MCSC_BACKGROUND | Retrieve the background color displayed between months.
MCSC_MONTHBK | Retrieve the background color displayed within the month.
MCSC_TEXT | Retrieve the color used to display text within a month.
MCSC_TITLEBK | Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT | Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.

Return Values

Returns a COLORREF value that represents the color setting for the specified portion of the month calendar control if successful. Otherwise, the return is -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetCurSel

Retrieves the currently selected date. You can use this macro or send the MCM_GETCURSEL message explicitly.

BOOL MonthCal_GetCurSel(
    HWND hwndMC,
    LPSYSTEMTIME lpSysTime
);

Parameters

hwndMC
Handle to a month calendar control.
lpSysTime
Address of a SYSTEMTIME structure that will receive the currently selected date information. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero if successful, or zero otherwise. This macro will always fail when applied to month calendar controls that are set to the MCS_MULTISELECT style.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetFirstDayOfWeek

Retrieves the first day of the week for a month calendar control. You can use this macro or send the MCM_GETFIRSTDAYOFWEEK message explicitly.

DWORD MonthCal_GetFirstDayOfWeek(
    HWND hwndMC
);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

Returns a DWORD value that contains two values. The high word is a BOOL value that is nonzero if the first day of the week is set to something other than LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low word is an INT value that represents the first day of the week. This will be one of the day numbers.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetMaxSelCount

Retrieves the maximum date range that can be selected in a month calendar control. You can use this macro or send the MCM_GETMAXSELCOUNT message explicitly.

DWORD MonthCal_GetMaxSelCount(
    HWND hwndMC
);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

Returns an INT value that represents the total number of days that can be selected for the control.

Remarks

You can change the maximum date range that can be selected by using the MCM_SETMAXSELCOUNT message.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetMaxTodayWidth

Retrieves the maximum width of the "today" string in a month calendar control. This includes the label text and the date text. You can use this macro or send the MCM_GETMAXTODAYWIDTH message explicitly.

DWORD MonthCal_GetMaxTodayWidth(
    HWND hwndMC
);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

Returns the width of the "today" string, in pixels.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetMinReqRect

Retrieves the minimum size required to display a full month in a month calendar control. Size information is presented in the form of a RECT structure. You can use this macro or send the MCM_GETMINREQRECT message explicitly.

BOOL MonthCal_GetMinReqRect(
    HWND hwndMC,
    LPRECT lpRectInfo
);

Parameters

hwndMC
Handle to a month calendar control.
lpRectInfo
Address of a RECT structure that will receive bounding rectangle information. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero and lpRectInfo receives the applicable bounding information if successful. Otherwise, the return is zero.

Remarks

The minimum required window size for a month calendar control depends on the currently selected font, control styles, system metrics, and regional settings. When an application changes anything that affects the minimum window size, or processes a WM_SETTINGCHANGE message, it should call MonthCal_GetMinReqRect to determine the new minimum size.

Note: The rectangle returned by MonthCal_GetMinReqRect does not include the width of the "Today" string, if it is present. If the MCS_NOTODAY style is not set, your application should also retrieve the rectangle that defines the "Today" string width by calling the MonthCal_GetMaxTodayWidth macro. Use the larger of the two rectangles to ensure that the "Today" string is not clipped.

The top and left members of lpRectInfo will always be zero. The right and bottom members represent the minimum cx and cy required for the control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetMonthDelta

Retrieves the scroll rate for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button. You can use this macro or send the MCM_GETMONTHDELTA message explicitly.

INT MonthCal_GetMonthDelta(
    HWND hwndMC
);

Parameters

hwndMC
Handle to a month calendar control.

Return Values

If the month delta was previously set using the MonthCal_SetMonthDelta macro, returns an INT value that represents the month calendar's current scroll rate. If the month delta was not previously set using the MonthCal_SetMonthDelta macro, or the month delta was reset to the default, returns an INT value that represents the current number of months visible.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetMonthRange

Retrieves date information (using SYSTEMTIME structures) that represents the high and low limits of a month calendar control's display. You can use this macro or send the MCM_GETMONTHRANGE message explicitly.

DWORD MonthCal_GetMonthRange(
    HWND hwndMC,
    DWORD dwFlag,
    LPSYSTEMTIME lprgSysTimeArray
);

Parameters

hwndMC
Handle to a month calendar control.
dwFlag
Value specifying the scope of the range limits to be retrieved. This value must be one of the following:
GMR_DAYSTATE | Include preceding and trailing months of visible range that are only partially displayed.
GMR_VISIBLE | Include only those months that are entirely displayed.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the scope specified by dwFlag. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures will not be modified. This parameter must be a valid address and cannot be NULL.

Return Values

Returns an INT value that represents the range, in months, spanned by the two limits returned at lprgSysTimeArray.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetRange

Retrieves the minimum and maximum allowable dates set for a month calendar control. You can use this macro or send the MCM_GETRANGE message explicitly.

DWORD MonthCal_GetRange(
    HWND hwndMC,
    LPSYSTEMTIME lprgSysTimeArray
);

Parameters

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the date limit information. The minimum limit is set in lprgSysTimeArray[0], and lprgSysTimeArray[1] receives the maximum limit. If either element is set to all zeros, then no corresponding limit is set for the month calendar control. The time members of these structures will not be modified. This parameter must be a valid address and cannot be NULL.

Return Values

Returns a DWORD value that can be zero (no limits are set) or a combination of the following values that specify limit information:
GDTR_MAX | There is a maximum limit set for the control; lprgSysTimeArray[0] is valid and contains the applicable date information.
GDTR_MIN | There is a minimum limit set for the control; lprgSysTimeArray[1] is valid and contains the applicable date information.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetSelRange

Retrieves date information that represents the upper and lower limits of the date range currently selected by the user. You can use this macro or send the MCM_GETSELRANGE message explicitly.

BOOL MonthCal_GetSelRange(
    HWND hwndMC,
    LPSYSTEMTIME lprgSysTimeArray
);

Parameters

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that will receive the lower and upper limits of the user's selection. The lower and upper limits are placed in lprgSysTimeArray[0] and lprgSysTimeArray[1], respectively. The time members of these structures will not be modified. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero if successful, or zero otherwise. MonthCal_GetSelRange will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetToday

Retrieves the date information for the date specified as "today" for a month calendar control. You can use this macro or send the MCM_GETTODAY message explicitly.

BOOL MonthCal_GetToday(
    HWND hwndMC,
    LPSYSTEMTIME lpToday
);

Parameters

hwndMC
Handle to a month calendar control.
lpToday
Address of a SYSTEMTIME structure that will receive the date information. The time members of this structure will not be modified. This parameter must be a valid address and cannot be NULL.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_GetUnicodeFormat

Retrieves the UNICODE character format flag for the control. You can use this macro or send the MCM_GETUNICODEFORMAT message explicitly.

BOOL MonthCal_GetUnicodeFormat(
    HWND hwnd
);

Parameters

hwnd
Handle to the control.

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

See Also

MonthCal_SetUnicodeFormat

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_HitTest

Determines which portion of a month calendar control is at a given point on the screen. You can use this macro or send the MCM_HITTEST message explicitly.

DWORD MonthCal_HitTest(
    HWND hwndMC,
    PMCHITTESTINFO pMCHitTest
);

Parameters

hwndMC
Handle to a month calendar control.
pMCHitTest
Address of an MCHITTESTINFO structure. Upon calling the macro, the cbSize member must be set to the size of the MCHITTESTINFO structure, and pt must be set to the point you want to hit test.

Return Values

Sets values in members of the MCHITTESTINFO structure at pMCHitTest and returns a DWORD value that contains a set of hit test result flags. See the return value description of MCM_HITTEST for a list of the hit test result flags.

The uHit member of the MCHITTESTINFO structure at pMCHitTest will equal the return value.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetColor

Sets the color for a given portion of a month calendar control. You can use this macro or send the MCM_SETCOLOR message explicitly.

COLORREF MonthCal_SetColor(
    HWND hwndMC,
    INT iColor,
    COLORREF clr
);

Parameters

hwndMC
Handle to a month calendar control.
iColor
INT value specifying which month calendar color to set. This value can be one of the following:
MCSC_BACKGROUND | Retrieve the background color displayed between months.
MCSC_MONTHBK | Retrieve the background color displayed within the month.
MCSC_TEXT | Retrieve the color used to display text within a month.
MCSC_TITLEBK | Retrieve the background color displayed in the calendar's title.
MCSC_TITLETEXT | Retrieve the color used to display text within the calendar's title.
MCSC_TRAILINGTEXT | Retrieve the color used to display header day and trailing day text. Header and trailing days are the days from the previous and following months that appear on the current month calendar.
clr
COLORREF value that represents the color that will be set for the specified area of the month calendar.

Return Values

Returns a COLORREF value that represents the previous color setting for the specified portion of the month calendar control if successful. Otherwise, the return is -1.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetCurSel

Sets the currently selected date for a month calendar control. If the specified date is not in view, the control updates the display to bring it into view. You can use this macro or send the MCM_SETCURSEL message explicitly.

BOOL MonthCal_SetCurSel(
    HWND hwndMC,
    LPSYSTEMTIME lpSysTime
);

Parameters

hwndMC
Handle to a month calendar control.
lpSysTime
Address of a SYSTEMTIME structure that contains the date to be set as the current selection. The time members of this structure are ignored.

Return Values

Returns nonzero if successful, or zero otherwise. This macro will fail if applied to a month calendar control that uses the MCS_MULTISELECT style.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetDayState

Sets the day states for all months that are currently visible within a month calendar control. You can use this macro or send the MCM_SETDAYSTATE message explicitly.

BOOL MonthCal_SetDayState(
    HWND hwndMC,
    INT iMonths,
    LPMONTHDAYSTATE lpDayStateArray
);

Parameters

hwndMC
Handle to a month calendar control.
iMonths
INT value indicating how many elements are in the array that lpDayStateArray points to.
lpDayStateArray
Address of an array of MONTHDAYSTATE values that define how the month calendar control will draw each day in its display.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

The array at lpDayStateArray must contain as many elements as the value returned by the following macro:

MonthCal_GetMonthRange(hwndMC, GMR_DAYSTATE, NULL);

The preceding macro returns the total number of months that are in complete or partial view within the month calendar's display.

Keep in mind that the array at lpDayStateArray must contain MONTHDAYSTATE values that correspond with all months currently in the control's display, in chronological order. This includes the two months only partially displayed before the first month and after the last month. For more information about preparing your array, see Preparing the MONTHDAYSTATE Array.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetFirstDayOfWeek

Sets the first day of the week for a month calendar control. You can use this macro or send the MCM_SETFIRSTDAYOFWEEK message explicitly.

DWORD MonthCal_SetFirstDayOfWeek(
    HWND hwndMC,
    INT iDay
);

Parameters

hwndMC
Handle to a month calendar control.
iDay
INT value representing which day is to be set as the first day of the week. This value must be one of the day numbers.

Return Values

Returns a DWORD value that contains two values. The high word is a BOOL value that is nonzero if the previous first day of the week did not equal LOCALE_IFIRSTDAYOFWEEK, or zero otherwise. The low word is an INT value that represents the previous first day of the week.

Remarks

If the first day of the week is set to anything other than the default (LOCALE_IFIRSTDAYOFWEEK), the control will not automatically update first-day-of-the-week changes based on locale changes.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetMaxSelCount

Sets the maximum number of days that can be selected in a month calendar control. You can use this macro or send the MCM_SETMAXSELCOUNT message explicitly.

BOOL MonthCal_SetMaxSelCount(
    HWND hwndMC,
    UINT iMax
);

Parameters

hwndMC
Handle to a month calendar control.
iMax
INT value that will be set to represent the maximum number of days that can be selected.

Return Values

Returns nonzero if successful, or zero otherwise. This macro will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetMonthDelta

Sets the scroll rate for a month calendar control. The scroll rate is the number of months that the control moves its display when the user clicks a scroll button. You can use this macro or send the MCM_SETMONTHDELTA message explicitly.

INT MonthCal_SetMonthDelta(
    HWND hwndMC,
    INT iDelta
);

Parameters

hwndMC
Handle to a month calendar control.
iDelta
Value representing the number of months to be set as the control's scroll rate. If this value is zero, the month delta is reset to the default, which is the number of months displayed in the control.

Return Values

Returns an INT value that represents the previous scroll rate. If the scroll rate was not previously set, the return value is zero.

Remarks

The PAGE UP and PAGE DOWN keys, VK_PRIOR and VK_NEXT, change the selected month by one, regardless of the number of months displayed or the value set by MCM_SETMONTHDELTA.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetRange

Sets the minimum and maximum allowable dates for a month calendar control. You can use this macro or send the MCM_SETRANGE message explicitly.

BOOL MonthCal_SetRange(
    HWND hwndMC,
    DWORD fWhichLimit,
    LPSYSTEMTIME lprgSysTimeArray
);

Parameters

hwndMC
Handle to a month calendar control.
fWhichLimit
Flag values that specify which date limits are being set. This value must be one or both of the following:
GDTR_MAX | The maximum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[1] must contain date information.
GDTR_MIN | The minimum allowable date is being set. The SYSTEMTIME structure at lprgSysTimeArray[0] must contain date information.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that contain the date limits. The maximum limit must be in lpSysTimeArray[1] if GDTR_MAX is specified, and lpSysTimeArray[0] must contain the minimum limit if GDTR_MIN is specified.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetSelRange

Sets the selection for a month calendar control to a given date range. You can use this macro or send the MCM_SETSELRANGE message explicitly.

BOOL MonthCal_SetSelRange(
    HWND hwndMC,
    LPSYSTEMTIME lprgSysTimeArray
);

Parameters

hwndMC
Handle to a month calendar control.
lprgSysTimeArray
Address of a two-element array of SYSTEMTIME structures that contain date information representing the selection limits. The first selected date must be specified in lpSysTimeArray[0], and the last selected date must be specified in lpSysTimeArray[1]. The time members of these structures are ignored.

Return Values

Returns nonzero if successful, or zero otherwise. This macro will fail if applied to a month calendar control that does not use the MCS_MULTISELECT style.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetToday

Sets the "today" selection for a month calendar control. You can use this macro or send the MCM_SETTODAY message explicitly.

void MonthCal_SetToday(
    HWND hwndMC,
    LPSYSTEMTIME lpSysTime
);

Parameters

hwndMC
Handle to a month calendar control.
lpSysTime
Address of a SYSTEMTIME structure that contains the date to be set as the "today" selection for the control. If this parameter is set to NULL, the control returns to the default setting. The time members of this structure are ignored.

If the "today" selection is set to any date other than the default, the following conditions apply:

  • The control will not automatically update the "today" selection when the time passes midnight for the current day.
  • The control will not automatically update its display based on locale changes.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MonthCal_SetUnicodeFormat

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the MCM_SETUNICODEFORMAT message explicitly.

BOOL MonthCal_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Parameters

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

See Also

MonthCal_GetUnicodeFormat

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCN_GETDAYSTATE

Sent by a month calendar control to request information about how individual days should be displayed. This notification message is sent only by month calendar controls that use the MCS_DAYSTATE style, and it is sent in the form of a WM_NOTIFY message.

MCN_GETDAYSTATE
    lpNMDayState = (LPNMDAYSTATE) lParam;

Parameters

lpNMDayState
Address of an NMDAYSTATE structure. The structure contains information about the time frame for which the control needs information, and it receives the address of an array that provides this data.

Remarks

Handling this notification message allows your application to customize its display by specifying that certain days be displayed in bold. For more information about processing this message, see Processing the MCN_GETDAYSTATE Notification Message.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCN_SELCHANGE

Sent by a month calendar control when the currently selected date or range of dates changes. This notification message is sent in the form of a WM_NOTIFY message.

MCN_SELCHANGE
    lpNMSelChange = (LPNMSELCHANGE) lParam;

Parameters

lpNMSelChange
Address of an NMSELCHANGE structure that contains information about the currently selected date range.

Remarks

For example, the control sends MCN_SELCHANGE when the user explicitly changes his or her selection within the current month or when the selection is implicitly changed in response to next/previous month navigation.

This notification message is similar to MCN_SELECT, but it is sent in response to any selection change. MCN_SELECT is sent only for an explicit date selection.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MCN_SELECT

Sent by a month calendar control when the user makes an explicit date selection within a month calendar control. This notification is sent in the form of a WM_NOTIFY message.

MCN_SELECT
    lpNMSelChange = (LPNMSELCHANGE) lParam;

Parameters

lpNMSelChange
Address of an NMSELCHANGE structure that contains information about the currently selected date range.

Remarks

This notification message is similar to MCN_SELCHANGE, but it is sent only in response to a user's explicit date selections. MCN_SELCHANGE applies to any selection change.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (monthcal)

Notifies a monthcal control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


MCHITTESTINFO

Carries information specific to hit-testing points for a month calendar control. This structure is used with the MCM_HITTEST message and the corresponding MonthCal_HitTest macro.

typedef struct {
    UINT       cbSize;
    POINT      pt;
    UINT       uHit;   // An output member
    SYSTEMTIME st;     // An output member
} MCHITTESTINFO, *PMCHITTESTINFO;

Members

cbSize
Size of this structure, in bytes.
pt
POINT structure that contains information about the point to be hit-tested.
uHit
Output member that receives a bit flag representing the result of the hit-test operation. This value will be one of the following:
MCHT_CALENDARBK | The given point was in the calendar's background.
MCHT_CALENDARDATE | The given point was on a particular date within the calendar. The SYSTEMTIME structure at lpMCHitTest->st is set to the date at the given point.
MCHT_CALENDARDATENEXT | The given point was over a date from the next month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_CALENDARDATEPREV | The given point was over a date from the previous month (partially displayed at the end of the currently displayed month). If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_CALENDARDAY | The given point was over a day abbreviation ("Fri", for example). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the top row.
MCHT_CALENDARWEEKNUM | The given point was over a week number (MCS_WEEKNUMBERS style only). The SYSTEMTIME structure at lpMCHitTest->st is set to the corresponding date in the leftmost column.
MCHT_NOWHERE | The given point was not on the month calendar control, or it was in an inactive portion of the control.
MCHT_TITLEBK | The given point was over the background of a month's title.
MCHT_TITLEBTNNEXT | The given point was over the button at the top right corner of the control. If the user clicks here, the month calendar will scroll its display to the next month or set of months.
MCHT_TITLEBTNPREV | The given point was over the button at the top left corner of the control. If the user clicks here, the month calendar will scroll its display to the previous month or set of months.
MCHT_TITLEMONTH | The given point was in a month's title bar, over a month name.
MCHT_TITLEYEAR | The given point was in a month's title bar, over the year value.
st
SYSTEMTIME structure that receives date and time information specific to the location that was hit-tested.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMDAYSTATE

Carries information required to process the MCN_GETDAYSTATE notification message. All members of this structure are for input, except prgDayState, which the receiving application must set when processing MCN_GETDAYSTATE.

typedef struct tagNMDAYSTATE {
    NMHDR           nmhdr;
    SYSTEMTIME      stStart;
    int             cDayState;
    LPMONTHDAYSTATE prgDayState;
} NMDAYSTATE, FAR * LPNMDAYSTATE;

Members

nmhdr
NMHDR structure that contains information about this notification message.
stStart
SYSTEMTIME structure that contains the starting date.
cDayState
INT value specifying the total number of elements that must be in the array at prgDayState.
prgDayState
Address of an array of MONTHDAYSTATE values. The buffer at this address must be large enough to contain at least cDayState elements. The first element in the array corresponds to the date in stStart.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMSELCHANGE

Carries information required to process the MCN_SELCHANGE notification message.

typedef struct tagNMSELCHANGE{
    NMHDR           nmhdr;
    SYSTEMTIME      stSelStart;
    SYSTEMTIME      stSelEnd;
} NMSELCHANGE, FAR * LPNMSELCHANGE;

Members

nmhdr
NMHDR structure that contains information about this notification message.
stSelStart
SYSTEMTIME structure that contains the date for the first day in the user's selection range.
stSelEnd
SYSTEMTIME structure that contains the date for the last day in the user's selection range.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


MONTHDAYSTATE

This is a new data type that is defined in Commctrl.h as follows:

typedef DWORD MONTHDAYSTATE, FAR * LPMONTHDAYSTATE;

The MONTHDAYSTATE type is a bit field, where each bit (1 through 31) represents the state of a day in a month. If a bit is on, the corresponding day will be displayed in bold; otherwise it will be displayed with no emphasis.

This data type is used with the MCM_SETDAYSTATE message and the corresponding macro, MonthCal_SetDayState. When MONTHDAYSTATE values are used in reference to months shorter than 31 days, only the needed bits will be accessed.

Version 4.70.


Pager Controls

A pager control is a window container that is used with a window that does not have enough display area to show all of its content. The pager control allows the user to scroll to the area of the window that is not currently in view.

  • About Pager Controls
  • Using Pager Controls
  • Pager Control Reference

About Pager Controls

Microsoft® Internet Explorer Version 4.0 (commctrl.dll version 4.71) introduces the pager control. This control is useful in situations where a window does not have enough area to display a child window. For example, if your application has a toolbar that is not wide enough to show all of its items, you can assign the toolbar to a pager control and users will be able to scroll to the left or right to access all of the items. You can also create pager controls that scroll vertically.

A window assigned to the pager control is referred to as the contained window.

The following illustration shows a toolbar contained inside of a pager control. The pager control is displayed in red to show what areas of the control are visible.

Note The pager control is implemented in version 4.71 and later of Comctl32.dll.

Using Pager Controls

This section describes how to implement the pager control in your application.

Initializing the Pager Control

To use the pager control, you must call InitCommonControlsEx with the ICC_PAGESCROLLER_CLASS flag set in the dwICC member of the INITCOMMONCONTROLSEX structure.

Creating the Pager Control

Use the CreateWindow or the CreateWindowEx API to create a pager control. The class name for the control is WC_PAGESCROLLER, which is defined in Commctrl.h. The PGS_HORZ style is used to create a horizontal pager, and the PGS_VERT style is used to create a vertical pager. Because this is a child control, the WS_CHILD style should also be used.

Once the pager control is created, you will most likely want to assign a contained window to it. If the contained window is a child window, you should make the child window a child of the pager control so that the size and position will be calculated correctly. You then assign the window to the pager control with the PGM_SETCHILD message. Be aware that this message does not actually change the parent window of the contained window; it simply assigns the contained window. If the contained window is one of the common controls, it must have the CCS_NORESIZE style to prevent the control from attempting to resize itself to the pager control's size.

Processing Pager Control Notifications

At a minimum, it is necessary to process the PGN_CALCSIZE notification. If you don't process this notification and enter a value for the width or height, the scroll arrows in the pager control will not be displayed. This is because the pager control uses the width or height supplied in the PGN_CALCSIZE notification to determine the "ideal" size of the contained window.

The following example demonstrates how to process the PGN_CALCSIZE notification case. In this example, the contained window is a toolbar control that contains an unknown number of buttons at an unknown size. The example shows how to use the TB_GETMAXSIZE message to determine the size of all of the items in the toolbar. The example then places the width of all of the items into the iWidth member of the NMPGCALCSIZE structure passed to the notification.

case PGN_CALCSIZE:
  {
  LPNMPGCALCSIZE   pCalcSize = (LPNMPGCALCSIZE)lParam;

  switch(pCalcSize->dwFlag)
     {
     case PGF_CALCWIDTH:
        {
        SIZE  size;

        //Get the optimum width of the toolbar.
        SendMessage(hwndToolbar, TB_GETMAXSIZE, 0, (LPARAM)&size);
        pCalcSize->iWidth = size.cx;
        }
        break;

     }

  }
  return 0;

Processing the PGN_SCROLL notification is optional. Process this notification if you need to know when a scroll action occurs, need to track the scroll position, or wish to change the scroll delta. To cancel the scroll, simply place zero in the iScroll member of the NMPGSCROLL structure passed to the notification.

The following example shows how to modify the scroll delta.

case PGN_SCROLL:
  {
  LPNMPGSCROLL   pScroll = (LPNMPGSCROLL)lParam;

  switch(pScroll->iDir)
     {
     case PGF_SCROLLLEFT:
     case PGF_SCROLLRIGHT:
     case PGF_SCROLLUP:
     case PGF_SCROLLDOWN:
        pScroll->iScroll = 20;
        break;
     }
  }
  return 0;


Pager Control Styles

The following window styles are used when creating pager controls.
PGS_AUTOSCROLL | The pager control will scroll when the user hovers the mouse over one of the scroll buttons.
PGS_DRAGNDROP | The contained window can be a drag-and-drop target. The pager control will automatically scroll if an item is dragged from outside the pager over one of the scroll buttons.
PGS_HORZ | Creates a pager control that can be scrolled horizontally. This style and the PGS_VERT style are mutually exclusive and cannot be combined.
PGS_VERT | Creates a pager control that can be scrolled vertically. This is the default direction if no direction style is specified. This style and the PGS_HORZ style are mutually exclusive and cannot be combined.


PGM_FORWARDMOUSE

Enables or disables mouse forwarding for the pager control. When mouse forwarding is enabled, the pager control forwards WM_MOUSEMOVE messages to the contained window. You can send this message explicitly or use the Pager_ForwardMouse macro.

PGM_FORWARDMOUSE
    wParam = (WPARAM)(BOOL)bForward;
    lParam = 0;

Parameters

bForward
BOOL value that determines if mouse forwarding is enabled or disabled. If this value is nonzero, mouse forwarding is enabled. If this value is zero, mouse forwarding is disabled.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_GETBKCOLOR

Retrieves the current background color for the pager control. You can send this message explicitly or use the Pager_GetBkColor macro.

PGM_GETBKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that contains the current background color.

Remarks

By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_GETBORDER

Retrieves the current border size for the pager control. You can send this message explicitly or use the Pager_GetBorder macro.

PGM_GETBORDER
    wParam = 0;
    lParam = 0;

Return Values

Returns an INT value that contains the current border size, in pixels.

See Also

PGM_SETBORDER

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_GETBUTTONSIZE

Retrieves the current button size for the pager control. You can send this message explicitly or use the Pager_GetButtonSize macro.

PGM_GETBUTTONSIZE
    wParam = 0;
    lParam = 0;

Return Values

Returns an INT value that contains the current button size, in pixels.

See Also

PGM_SETBUTTONSIZE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_GETBUTTONSTATE

Retrieves the state of the specified button in a pager control. You can send this message explicitly or use the Pager_GetButtonState macro.

PGM_GETBUTTONSTATE
    wParam = 0;
    lParam = (LPARAM)(int)iButton;

Parameters

iButton
Indicates which button to retrieve the state for. This can be one of the following values:
PGB_TOPORLEFT | Indicates the top button in a PGS_VERT pager control or the left button in a PGS_HORZ pager control.
PGB_BOTTOMORRIGHT | Indicates the bottom button in a PGS_VERT pager control or the right button in a PGS_HORZ pager control.

Return Values

Returns the state of the button specified in iButton. This will be one of the following values:
PGF_INVISIBLE | The button is not visible.
PGF_NORMAL | The button is in normal state.
PGF_GRAYED | The button is in grayed state.
PGF_DEPRESSED | The button is in pressed state.
PGF_HOT | The button is in hot state.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_GETDROPTARGET

Retrieves a pager control's IDropTarget interface pointer. You can send this message explicitly or use the Pager_GetDropTarget macro.

PGM_GETDROPTARGET
    wParam = 0;
    lParam = (IDropTarget**)ppDropTarget;

Parameters

ppDropTarget
Address of an IDropTarget pointer that receives the interface pointer. It is the caller's responsibility to call Release on this pointer when it is no longer needed.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_GETPOS

Retrieves the current scroll position of the pager control. You can send this message explicitly or use the Pager_GetPos macro.

PGM_GETPOS
    wParam = 0;
    lParam = 0;

Return Values

Returns an INT value that contains the current scroll position, in pixels.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_RECALCSIZE

Forces the pager control to recalculate the size of the contained window. Sending this message will result in a PGN_CALCSIZE notification being sent. You can send this message explicitly or use the Pager_RecalcSize macro.

PGM_RECALCSIZE
    wParam = 0;
    lParam = 0;

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_SETBKCOLOR

Sets the current background color for the pager control. You can send this message explicitly or use the Pager_SetBkColor macro.

PGM_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBk;

Parameters

clrBk
COLORREF value that contains the new background color of the pager control.

Return Values

Returns a COLORREF value that contains the previous background color.

Remarks

By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_SETBORDER

Sets the current border size for the pager control. You can send this message explicitly or use the Pager_SetBorder macro.

PGM_SETBORDER
    wParam = 0;
    lParam = (LPARAM)(int)iBorder;

Parameters

iBorder
New size of the border, in pixels. This value should not be larger than the pager button or less than zero. If iBorder is too large, the border will be drawn the same size as the button. If iBorder is negative, the border size will be set to zero.

Return Values

Returns an INT value that contains the previous border size, in pixels.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_SETBUTTONSIZE

Sets the current button size for the pager control. You can send this message explicitly or use the Pager_SetButtonSize macro.

PGM_SETBUTTONSIZE
    wParam = 0;
    lParam = (LPARAM)(int)iButtonSize;

Parameters

iButtonSize
INT value that contains the new button size, in pixels.

Return Values

Returns an INT value that contains the previous button size, in pixels.

Remarks

If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons. If the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. By default, the pager control sets its button size to three-fourths of the width of the scroll bar.

See Also

PGM_GETBUTTONSIZE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_SETCHILD

Sets the contained window for the pager control. This message will not change the parent of the contained window; it only assigns a window handle to the pager control for scrolling. In most cases, the contained window will be a child window. If this is the case, the contained window should be a child of the pager control. You can send this message explicitly or use the Pager_SetChild macro.

PGM_SETCHILD
    wParam = 0;
    lParam = (LPARAM)(HWND)hwndChild;

Parameters

hwndChild
Handle to the window to be contained.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGM_SETPOS

Sets the current scroll position for the pager control. You can send this message explicitly or use the Pager_SetPos macro.

PGM_SETPOS
    wParam = 0;
    lParam = (LPARAM)(int)iPos;

Parameters

iPos
INT value that contains the new scroll position, in pixels.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_ForwardMouse

Enables or disables mouse forwarding for the pager control. When mouse forwarding is enabled, the pager control forwards WM_MOUSEMOVE messages to the contained window. You can use this macro or send the PGM_FORWARDMOUSE message explicitly.

VOID Pager_ForwardMouse(
    HWND hwndPager,
    BOOL bForward
);

Parameters

hwndPager
Handle to the pager control.
bForward
BOOL value that determines if mouse forwarding is enabled or disabled. If this value is nonzero, mouse forwarding is enabled. If this value is zero, mouse forwarding is disabled.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_GetBkColor

Retrieves the current background color for the pager control. You can use this macro or send the PGM_GETBKCOLOR message explicitly.

COLORREF Pager_GetBkColor(
    HWND hwndPager
);

Parameters

hwndPager
Handle to the pager control.

Return Values

Returns a COLORREF value that contains the current background color.

Remarks

By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_GetBorder

Retrieves the current border size for the pager control. You can use this macro or send the PGM_GETBORDER message explicitly.

int Pager_GetBorder(
    HWND hwndPager
);

Parameters

hwndPager
Handle to the pager control.

Return Values

Returns an INT value that contains the current border size, in pixels.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_GetButtonSize

Retrieves the current button size for the pager control. You can use this macro or send the PGM_GETBUTTONSIZE message explicitly.

int Pager_GetButtonSize(
    HWND hwndPager
);

Parameters

hwndPager
Handle to the pager control.

Return Values

Returns an INT value that contains the current button size, in pixels.

See Also

Pager_SetButtonSize

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_GetButtonState

Retrieves the state of the specified button in a pager control. You can use this macro or send the PGM_GETBUTTONSTATE message explicitly.

DWORD Pager_GetButtonState(
    HWND hwndPager;
    int iButton
);

Parameters

hwndPager
Handle to the pager control.
iButton
Indicates which button to retrieve the state for. See the description for iButton in PGM_GETBUTTONSTATE for a list of possible values.

Return Values

Returns the state of the button specified in iButton. See the return value description in PGM_GETBUTTONSTATE for a list of possible values.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_GetDropTarget

Retrieves a pager control's IDropTarget interface pointer. You can use this macro or send the PGM_GETDROPTARGET message explicitly.

void Pager_GetDropTarget(
    HWND hwndPager,
    IDropTarget **ppDropTarget
);

Parameters

hwndPager
Handle to the pager control.
ppDropTarget
Address of an IDropTarget pointer that receives the interface pointer. It is the caller's responsibility to call Release on this pointer when it is no longer needed.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_GetPos

Retrieves the current scroll position of the pager control. You can use this macro or send the PGM_GETPOS message explicitly.

COLORREF Pager_GetPos(
    HWND hwndPager
);

Parameters

hwndPager
Handle to the pager control.

Return Values

Returns an INT value that contains the current scroll position, in pixels.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_RecalcSize

Forces the pager control to recalculate the size of the contained window. Using this macro will result in a PGN_CALCSIZE notification being sent. You can use this macro or send the PGM_RECALCSIZE message explicitly.

COLORREF Pager_RecalcSize(
    HWND hwndPager
);

Parameters

hwndPager
Handle to the pager control.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_SetBkColor

Sets the current background color for the pager control. You can use this macro or send the PGM_SETBKCOLOR message explicitly.

COLORREF Pager_SetBkColor(
    HWND hwndPager,
    COLORREF clrBk
);

Parameters

hwndPager
Handle to the pager control.
clrBk
COLORREF value that contains the new background color of the pager control.

Return Values

Returns a COLORREF value that contains the previous background color.

Remarks

By default, the pager control will use the system button face color as the background color. This is the same color that can be retrieved by calling GetSysColor with COLOR_BTNFACE.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_SetBorder

Sets the current border size for the pager control. You can use this macro or send the PGM_SETBORDER message explicitly.

INT Pager_SetBorder(
    HWND hwndPager,
    int iBorder
);

Parameters

hwndPager
Handle to the pager control.
iBorder
New size of the border, in pixels. This value should not be larger than the pager button or less than zero. If iBorder is too large, the border will be drawn the same size as the button. If iBorder is negative, the border size will be set to zero.

Return Values

Returns an INT value that contains the previous border size, in pixels.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_SetButtonSize

Sets the current button size for the pager control. You can use this macro or send the PGM_SETBUTTONSIZE message explicitly.

int Pager_SetButtonSize(
    HWND hwndPager,
    Int iButtonSize
);

Parameters

hwndPager
Handle to the pager control.
iButtonSize
INT value that contains the new button size, in pixels.

Return Values

Returns an INT value that contains the previous button size, in pixels.

Remarks

If the pager control has the PGS_HORZ style, the button size determines the width of the pager buttons. If the pager control has the PGS_VERT style, the button size determines the height of the pager buttons. By default, the pager control sets its button size to three-fourths of the width of the scroll bar.

See Also

Pager_GetButtonSize

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_SetChild

Sets the contained window for the pager control. This macro will not change the parent of the contained window; it only assigns a window handle to the pager control for scrolling. In most cases, the contained window will be a child window. If this is the case, the contained window should be a child of the pager control. You can use this macro or send the PGM_SETCHILD message explicitly.

COLORREF Pager_SetChild(
    HWND hwndPager,
    HWND hwndChild
);

Parameters

hwndPager
Handle to the pager control.
hwndChild
Handle to the window to be contained.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Pager_SetPos

Sets the scroll position for the pager control. You can use this macro or send the PGM_SETPOS message explicitly.

INT Pager_SetPos(
    HWND hwndPager,
    int iPos
);

Parameters

hwndPager
Handle to the pager control.
iPos
INT value that contains the new scroll position, in pixels.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (pager)

Notifies a pager control's parent window that the control has released the mouse capture. NM_RELEASEDCAPTURE is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the pager control.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGN_CALCSIZE

Notification sent by a pager control to obtain the scrollable dimensions of the contained window. These dimensions are used by the pager control to determine the scrollable size of the contained window. This notification is sent in the form of a WM_NOTIFY message.

PGN_CALCSIZE
    lpnmcs = (LPNMPGCALCSIZE) lParam;

Parameters

lpnmcs
Address of an NMPGCALCSIZE structure that contains and receives information about the notification. The dwFlag member of this structure indicates which dimension is being calculated. Depending on the value of dwFlags, you should place the desired dimension in the iWidth or iHeight member of this structure.

Return Values

The return value is ignored.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PGN_SCROLL

Notification sent by a pager control prior to the contained window being scrolled. This notification is sent in the form of a WM_NOTIFY message.

PGN_SCROLL
    lpnms = (LPNMPGSCROLL) lParam;

Parameters

lpnms
Address of an NMPGSCROLL structure that contains and receives information about the notification. The iDir member of this structure indicates the direction of the scroll. The iXpos and iYpos members contain the horizontal and vertical position of the contained window prior to the scroll. The iScroll member contains the default scroll delta amount. You can modify this member to a different scroll amount if desired.

Return Values

The return value is ignored.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMPGCALCSIZE

Contains and receives information that the pager control uses to calculate the scrollable area of the contained window. It is used with the PGN_CALCSIZE notification.

typedef struct {
    NMHDR   hdr;
    DWORD   dwFlag;
    int     iWidth;
    int     iHeight;
}NMPGCALCSIZE, *LPNMPGCALCSIZE;

Members

hdr
NMHDR structure that contains information about the notification message.
dwFlag
Value that indicates which dimension is being requested. This will be one of the following values:
PGF_CALCHEIGHT | The height of the scrollable area is being requested. The height must be placed in the iHeight member before returning from the notification.
PGF_CALCWIDTH | The width of the scrollable area is being requested. The width must be placed in the iWidth member before returning from the notification.
iWidth
Receives the desired width of the scrollable area, in pixels.
iHeight
Receives the desired height of the scrollable area, in pixels.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMPGSCROLL

Contains and receives information that the pager control uses when scrolling the contained window. It is used with the PGN_SCROLL notification.

typedef struct {
    NMHDR hdr;
    BOOL fwKeys;
    RECT rcParent;
    int  iDir;
    int  iXpos;
    int  iYpos;
    int  iScroll;
}NMPGSCROLL, *LPNMPGSCROLL;

Members

hdr
NMHDR structure that contains information about the notification message.
fwKeys
Modifier keys that are down when the scroll occurs. This can be one or more of the following values:
0 | None of the modifier keys are down.
PGK_SHIFT | The SHIFT key is down.
PGK_CONTROL | The CONTROL key is down.
PGK_MENU | The ALT key is down.
rcParent
Contains the client rectangle of the pager control.
iDir
Value that indicates in which direction the scroll is occurring. This will be one of the following values:
PGF_SCROLLDOWN | The contained window is being scrolled down.
PGF_SCROLLLEFT | The contained window is being scrolled to the left.
PGF_SCROLLRIGHT | The contained window is being scrolled to the right.
PGF_SCROLLUP | The contained window is being scrolled up.
iXpos
Contains the horizontal scroll position of the contained window, in pixels, before the scroll action.
iYpos
Contains the vertical scroll position of the contained window, in pixels, before the scroll action.
iScroll
On entry, contains the default scroll delta in pixels. This member can be modified to contain a different scroll delta amount if desired. This value is always positive, regardless of the scroll direction.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Progress Bar Control

A progress bar is a window that an application can use to indicate the progress of a lengthy operation. It consists of a rectangle that is gradually filled with the system highlight color as an operation progresses. The following illustration shows a progress bar positioned along the bottom of a window.

Progress bar positioned along the bottom of a window.

  • Using Progress Bars
  • Progress Bar Control Updates in Internet Explorer
  • Progress Bar Control Reference

Using Progress Bars

You create a progress bar by using the CreateWindowEx function, specifying the PROGRESS_CLASS window class. This window class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, use the InitCommonControls function first.

Range and Current Position

A progress bar's range represents the entire duration of the operation, and the current position represents the progress that the application has made toward completing the operation. The window procedure uses the range and the current position to determine the percentage of the progress bar to fill with the highlight color. Because the range and current position values are expressed as unsigned integers, the highest possible range or current position value is 65,535.

The minimum value in the range can be from 0 to 65,535. Likewise, the maximum value can be from 0 to 65,535. If you do not set the range values, the system sets the minimum value to 0 and the maximum value to 100. You can adjust the range to convenient integers by using the PBM_SETRANGE message.

A progress bar provides several messages that you can use to set the current position. The PBM_SETPOS message sets the position to a given value. The PBM_DELTAPOS message advances the position by adding a specified value to the current position.

The PBM_SETSTEP message allows you to specify a step increment for a progress bar. Subsequently, whenever you send the PBM_STEPIT message to the progress bar, the current position advances by the specified increment. By default, the step increment is set to 10.

Default Progress Bar Message Processing

This section describes the messages handled by the window procedure for the PROGRESS_CLASS class.
Message | Processing performed
WM_CREATE | Allocates and initializes an initial structure.
WM_DESTROY | Frees all resources associated with the progress bar.
WM_ERASEBKGND | Draws the background and borders of the progress bar.
WM_GETFONT | Returns the handle to the current font. The progress bar does not currently draw text, so sending this message has no effect on the control.
WM_PAINT | Draws the progress bar. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETFONT | Saves the handle to the new font and returns the handle to the previous font. The progress bar does not currently draw text, so sending this message has no effect on the control.

Progress Bar Example

The following example shows how to use a progress bar to indicate the progress of a lengthy file-parsing operation. The example creates a progress bar and positions it along the bottom of the parent window's client area. The height of the progress bar is based on the height of the arrow bitmap used in a scroll bar. The range is based on the size of the file divided by 2048, which is the size of each "chunk" of data read from the file. The example also sets an increment and advances the current position of the progress bar by the increment after parsing each chunk.

// ParseALargeFile - parses a large file and uses a progress bar to
//   indicate the progress of the parsing operation.
// Returns TRUE if successful, or FALSE otherwise.
// hwndParent - parent window of the progress bar.
// lpszFileName - name of the file to parse.
//
// Global variable
//     g_hinst - instance handle
extern HINSTANCE g_hinst;

BOOL ParseALargeFile(HWND hwndParent, LPSTR lpszFileName)
{
    RECT rcClient;  // client area of parent window
    int cyVScroll;  // height of scroll bar arrow
    HWND hwndPB;    // handle of progress bar
    HANDLE hFile;   // handle of file
    DWORD cb;       // size of file and count of bytes read
    LPCH pch;       // address of data read from file
    LPCH pchTmp;    // temporary pointer

    // Ensure that the common control DLL is loaded and create a
    // progress bar along the bottom of the client area of the
    // parent window. Base the height of the progress bar on
    // the height of a scroll bar arrow.
    InitCommonControls();
    GetClientRect(hwndParent, &rcClient);
    cyVScroll = GetSystemMetrics(SM_CYVSCROLL);
    hwndPB = CreateWindowEx(0, PROGRESS_CLASS, (LPSTR) NULL,
        WS_CHILD | WS_VISIBLE, rcClient.left,
        rcClient.bottom - cyVScroll,
        rcClient.right, cyVScroll,
        hwndParent, (HMENU) 0, g_hinst, NULL);

    // Open the file for reading, and retrieve the size of the file.
    hFile = CreateFile(lpszFileName, GENERIC_READ, FILE_SHARE_READ,
        (LPSECURITY_ATTRIBUTES) NULL, OPEN_EXISTING,
        FILE_ATTRIBUTE_NORMAL, (HANDLE) NULL);

    if (hFile == (HANDLE) INVALID_HANDLE_VALUE)
        return FALSE;

    cb = GetFileSize(hFile, (LPDWORD) NULL);

    // Set the range and increment of the progress bar.
    SendMessage(hwndPB, PBM_SETRANGE, 0, MAKELPARAM(0, cb / 2048));
    SendMessage(hwndPB, PBM_SETSTEP, (WPARAM) 1, 0);

    // Parse the file.
    pch = (LPCH) LocalAlloc(LPTR, sizeof(char) * 2048);
    pchTmp = pch;
    do {
        ReadFile(hFile, pchTmp, sizeof(char) * 2048, &cb,
            (LPOVERLAPPED) NULL);
        .
        . // Include here any code that parses the file.
        .

        // Advance the current position of the progress bar
        // by the increment.
        SendMessage(hwndPB, PBM_STEPIT, 0, 0);
    } while (cb);
    CloseHandle((HANDLE) hFile);

    DestroyWindow(hwndPB);
    return TRUE;
}

Progress Bar Control Updates in Internet Explorer

Progress bar controls in Microsoft® Internet Explorer support the following new features.

New Progress Bar Control Styles
Progress bar controls can now display progress information vertically, using the PBS_VERTICAL style. Also, a smooth progress mode is supported using the PBS_SMOOTH style. Using the PBS_SMOOTH style causes the control to display a contiguous progress bar instead of a segmented bar.
Extended Range Values
Progress bar controls now support 32-bit range values. To set range values in excess of 65,535, use the PBM_SETRANGE32 message. To retrieve 32-bit range values, use the PBM_GETRANGE message. The progress bar high limit, low limit, and position parameters are signed integers. To make full use of the 32-bit range, set the range to -0x7FFFFFFF to 0x7FFFFFFF and treat the position as a signed integer.
Programmable Colors
An application can now control the colors used in a progress bar control with the PBM_SETBARCOLOR and PBM_SETBKCOLOR messages.


Progress Bar Control Styles

Progress bar controls now support control styles. You can set progress bar styles in the same way as other common controls (CreateWindowEx, GetWindowLong, SetWindowLong). The following are the supported styles:
PBS_SMOOTH | Version 4.70. The progress bar displays progress status in a smooth scrolling bar instead of the default segmented bar.
PBS_VERTICAL | Version 4.70. The progress bar displays progress status vertically, from bottom to top.


PBM_DELTAPOS

Advances the current position of a progress bar by a specified increment and redraws the bar to reflect the new position.

PBM_DELTAPOS
    wParam = (WPARAM) nIncrement
    lParam = 0;

Parameters

nIncrement
Amount to advance the position.

Return Values

Returns the previous position.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


PBM_GETPOS

Retrieves the current position of the progress bar.

PBM_GETPOS
    wParam = 0;
    lParam = 0;

Return Values

Returns a UINT value that represents the current position of the progress bar.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


PBM_GETRANGE

Retrieves information about the current high and low limits of a given progress bar control.

PBM_GETRANGE
    wParam = (WPARAM)(BOOL) fWhichLimit;
    lParam = (LPARAM)(PPBRANGE) ppBRange;

Parameters

fWhichLimit
Flag value specifying which limit value is to be used as the message's return value. This parameter can be one of the following values:
TRUE | Return the low limit.
FALSE | Return the high limit.
ppBRange
Address of a PBRANGE structure that is to be filled with the high and low limits of the progress bar control. If this parameter is set to NULL, the control will return only the limit specified by fWhichLimit.

Return Values

Returns an INT that represents the limit value specified by fWhichLimit. If lParam is not NULL, lParam must point to a PBRANGE structure that is to be filled with both limit values.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


PBM_SETBARCOLOR

Sets the color of the progress indicator bar in the progress bar control.

PBM_SETBARCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBar;

Parameters

clrBar
COLORREF value that specifies the new progress indicator bar color. Specify the CLR_DEFAULT value to cause the progress bar to use its default progress indicator bar color.

Return Values

Returns the previous progress indicator bar color, or CLR_DEFAULT if the progress indicator bar color is the default color.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PBM_SETBKCOLOR

Sets the background color in the progress bar.

PBM_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBk;

Parameters

clrBk
COLORREF value that specifies the new background color. Specify the CLR_DEFAULT value to cause the progress bar to use its default background color.

Return Values

Returns the previous background color, or CLR_DEFAULT if the background color is the default color.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PBM_SETPOS

Sets the current position for a progress bar and redraws the bar to reflect the new position.

PBM_SETPOS
    wParam = (WPARAM) nNewPos;
    lParam = 0;

Parameters

nNewPos
Signed integer that becomes the new position.

Return Values

Returns the previous position.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


PBM_SETRANGE

Sets the minimum and maximum values for a progress bar and redraws the bar to reflect the new range.

PBM_SETRANGE
    wParam = 0;
    lParam = MAKELPARAM(nMinRange, nMaxRange);

Parameters

nMinRange
Minimum range value. By default, the minimum value is zero.
nMaxRange
Maximum range value. By default, the maximum value is 100.

Return Values

Returns the previous range values if successful, or zero otherwise. The low-order word specifies the previous minimum value, and the high-order word specifies the previous maximum value.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


PBM_SETRANGE32

Sets the range of a progress bar control to a 32-bit value.

PBM_SETRANGE32
    wParam = (WPARAM)(int) iLowLim;
    lParam = (LPARAM)(int) iHighLim;

Parameters

iLowLim
A signed integer that represents the low limit to be set for the progress bar control.
iHighLim
A signed integer that represents the high limit to be set for the progress bar control.

Return Values

Returns a DWORD value that holds the previous 16-bit low limit in its low word and the previous 16-bit high limit in its high word. If the previous ranges were 32-bit values, the return value consists of the low words of both 32-bit limits.

Remarks

To retrieve the entire high and low 32-bit values, use the PBM_GETRANGE message.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


PBM_SETSTEP

Specifies the step increment for a progress bar. The step increment is the amount by which the progress bar increases its current position whenever it receives a PBM_STEPIT message. By default, the step increment is set to 10.

PBM_SETSTEP
    wParam = (WPARAM) nStepInc;
    lParam = 0;

Parameters

nStepInc
New step increment.

Return Values

Returns the previous step increment.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


PBM_STEPIT

Advances the current position for a progress bar by the step increment and redraws the bar to reflect the new position. An application sets the step increment by sending the PBM_SETSTEP message.

PBM_STEPIT
    wParam = 0;
    lParam = 0;

Return Values

Returns the previous position.

Remarks

When the position exceeds the maximum range value, this message resets the current position so that the progress indicator starts over again from the beginning.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


PBRANGE

Contains information about the high and low limits of a progress bar control. This structure is used with the PBM_GETRANGE message.

typedef struct {
    int iLow;
    int iHigh;
} PBRANGE, *PPBRANGE;

Members

iLow
Low limit for the progress bar control. This is a signed integer.
iHigh
High limit for the progress bar control. This is a signed integer.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Property Sheets

A property sheet is a window that allows the user to view and edit the properties of an item. For example, a spreadsheet application can use a property sheet to allow the user to set the font and border properties of a cell or to view and set the properties of a device, such as a disk drive, printer, or mouse.

  • About Property Sheets
  • Using Property Sheets
  • Property Sheet Updates in Internet Explorer
  • Creating Wizards
  • Property Sheet Reference

About Property Sheets

This document assumes that you have a thorough understanding of dialog box templates and dialog box procedures. If you don't, read the "Dialog Boxes" chapter in the Platform SDK before continuing with this overview chapter.

To implement property sheets in your application, include the Prsht.h header file in your project. Prsht.h contains all of the identifiers used with property sheets.

A property sheet contains one or more overlapping child windows called pages, each containing control windows for setting a group of related properties. For example, a page can contain the controls for setting the font properties of an item, including the type style, point size, color, and so on. Each page has a tab that the user can select to bring the page to the foreground of the property sheet. For example, the Date-Time control panel application displays the following property sheet:

The Date-Time control panel application property sheet.

There is also a special type of property sheet called a wizard. Wizards are designed to present pages one at a time in a sequence that is controlled by the application. Instead of selecting from a group of pages by clicking a tab, users navigate forward and backward through the sequence, one page at a time, by clicking Next or Back buttons located at the bottom of the wizard. For example, this is the welcome page from the Hardware control panel application's wizard:

The Hardware control panel application wizard.

See Creating Wizards for a complete discussion of wizards.

Property Sheet Dialog Boxes

A property sheet and the pages it contains are actually dialog boxes. The property sheet is a system-defined dialog box that manages the pages and provides a common container for them. The property sheet dialog box can be modal or modeless. It includes a frame, a title bar, and four buttons: OK, Cancel, Apply, and Help. (The Help button may be hidden as in the preceding illustration.) The dialog box procedures for the pages receive notification messages when the user clicks the buttons.

Each page in a property sheet is an application-defined modeless dialog box that manages the control windows used to view and edit the properties of an item. You provide the dialog box template used to create each page as well as the dialog box procedure that manages the controls and sets the properties of the corresponding item.

A property sheet sends notification messages to the dialog box procedure for a page when the page is gaining or losing the activation and when the user clicks the OK, Cancel, Apply, or Help button. The notifications are sent in the form of WM_NOTIFY messages. The lParam parameter is the address of an NMHDR structure that includes the window handle to the property sheet dialog box.

Some notification messages require a page to return either TRUE or FALSE in response to the WM_NOTIFY message. To do this, the page must use the SetWindowLong function to set the DWL_MSGRESULT value for the page dialog box to either TRUE or FALSE.

Pages

A property sheet must contain at least one page, but it cannot contain more than the value of MAXPROPPAGES as defined in the Win32 header files. Each page has a zero-based index that the property sheet assigns according to the order in which the page is added to the property sheet. The indexes are used in messages that you send to the property sheet.

A property page can contain a nested dialog box. If it does, you must include the WS_EX_CONTROLPARENT style for the top-level dialog box and call the IsDialogMessage function with the handle to the parent dialog box. This ensures that the user can use mnemonics and the dialog box navigation keys to move the focus to controls in the nested dialog box.

Each page has a corresponding icon and label. The property sheet creates a tab for each page and displays the icon and label in the tab. All property sheet pages are expected to use a nonbold font. To ensure that the font is not bold, specify the DS_3DLOOK style in the dialog box template.

The dialog box procedure for a page must not call the EndDialog function. Doing so will destroy the entire property sheet, not just the page.

The minimum size for a property sheet page is 212 dialog units horizontally and 114 dialog units vertically. If a page dialog is smaller than this, the page will be enlarged until it meets the minimum size. The Prsht.h header file contains three sets of recommended sizes for property sheet pages. PROP_SM_CXDLG and PROP_SM_CYDLG define the recommended dimensions for a small property sheet page. PROP_MED_CXDLG and PROP_MED_CYDLG define the recommended dimensions for a medium-sized property sheet page. PROP_LG_CXDLG and PROP_LG_CYDLG define the recommended dimensions for a large property sheet page. Using these recommended sizes will help ensure visual consistency between your application and other Microsoft® Windows® applications.

Use the following values to set the sizes of the elements in your property sheet pages:

PROP_SM_CXDLG | Width, in dialog units, of a small property sheet page.
PROP_SM_CYDLG | Height, in dialog units, of a small property sheet page.
PROP_MED_CXDLG | Width, in dialog units, of a medium-sized property sheet page.
PROP_MED_CYDLG | Height, in dialog units, of a medium-sized property sheet page.
PROP_LG_CXDLG | Width, in dialog units, of a large property sheet page.
PROP_LG_CYDLG | Height, in dialog units, of a large property sheet page.

Property Sheet Creation

Before creating a property sheet, you must define one or more pages. This involves filling a PROPSHEETPAGE structure with information about the page—its icon, label, dialog box template, dialog box procedure, and so on—and then specifying the address of the structure in a call to the CreatePropertySheetPage function. The function returns a handle to the HPROPSHEETPAGE type that uniquely identifies the page.

To create a property sheet, you specify the address of a PROPSHEETHEADER structure in a call to the PropertySheet function. The structure defines the icon and title for the property sheet and also includes the address of an array of HPROPSHEETPAGE handles. When PropertySheet creates the property sheet, it includes the pages identified in the array. The pages appear in the property sheet in the same order that they are contained in the array.

Another way to create a property sheet is to specify an array of PROPSHEETPAGE structures instead of an array of HPROPSHEETPAGE handles. In this case, PropertySheet creates handles for the pages before adding them to the property sheet.

When a page is created, its dialog box procedure receives a WM_INITDIALOG message. The message's lParam parameter is a pointer to a copy of the PROPSHEETPAGE structure that is defined when the page is created. In particular, when a page is created, the structure's lParam member can be used to pass application-defined information to the dialog box procedure. With the exception of the lParam member, this structure must be treated as read-only. Modifying anything other than lParam will have unpredictable consequences.

When the system subsequently passes a copy of the page's PROPSHEETPAGE structure to your application, it uses the same pointer. Any changes to the structure will be passed along. Because the lParam member is ignored by the system, it can safely be modified to send information to other parts of your application. You can, for instance, use lParam to pass information to the page's callback function.

PropertySheet automatically sets the size and initial position of a property sheet. The position is based on the position of the owner window, and the size is based on the largest page specified in the array of pages when the property sheet was created. If you want the pages to match the width of the four buttons at the bottom of the property sheet, set the width of the widest page to 190 dialog units.

Adding and Removing Pages

After creating a property sheet, an application can add a page to the end of the existing set of pages by sending a PSM_ADDPAGE message. To insert a page between existing pages, send a PSM_INSERTPAGE message. Note that the size of the property sheet cannot change after it has been created. Any added or inserted pages must be no larger than the largest page currently in the property sheet. To remove a page, send a PSM_REMOVEPAGE message.

When you define a page, you can specify the address of a PropSheetPageProc callback function that the property sheet calls when it is creating or removing the page. Using PropSheetPageProc gives you an opportunity to perform initialization and cleanup operations for individual pages.

Note: A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Do not add, insert, or remove pages in your implementation of PropSheetPageProc, or while handling the following notifications and Windows messages.

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • PSN_WIZBACK
  • PSN_WIZNEXT
  • WM_INITDIALOG
  • WM_DESTROY

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

When a property sheet is destroyed, it automatically destroys all of the pages that have been added to it. The pages are destroyed in reverse order from that specified in the array used to create the pages. To destroy a page that was created by the CreatePropertySheetPage function but was not added to the property sheet, use the DestroyPropertySheetPage function.

Property Sheet Title and Page Labels

You specify the title of a property sheet in the PROPSHEETHEADER structure used to create the property sheet. If the dwFlags member includes the PSH_PROPTITLE value, the property sheet adds the "Properties for" prefix to the specified title string. You can change the title after a property sheet is created by using the PSM_SETTITLE message.

By default, a property sheet uses the name string specified in the dialog box template as the label for a page. You can override the name string by including the PSP_USETITLE value in the dwFlags member of the PROPSHEETPAGE structure that defines the page. When PSP_USETITLE is specified, the pszTitle member must contain the address of the label string for the page.

Page Activation

A property sheet can have only one active page at a time. The page that has the activation is at the foreground of the overlapping stack of pages. The user activates a page by selecting its tab; an application activates a page by using the PSM_SETCURSEL message.

The property sheet sends the PSN_KILLACTIVE notification message to the page that is about to lose the activation. In response, the page must validate any changes that the user has made to the page. If the page requires additional user input before losing the activation, use the SetWindowLong function to set the DWL_MSGRESULT value of the page to TRUE. Also, the page must display a message box that describes the problem and provides the recommended action. Set DWL_MSGRESULT to FALSE when it is okay to lose the activation.

Before the page that is gaining the activation is visible, the property sheet sends the PSN_SETACTIVE notification message to the page. The page must respond by initializing its control windows.

Help Button

Property sheets can display two Help buttons: a property sheet Help button that is displayed at the bottom of the frame, next to the OK/Cancel/Apply buttons, and a standard caption bar button that provides context-sensitive Help.

The property sheet Help button is optional, and can be enabled on a page by page basis. To display the property sheet Help button for one or more pages:

  • Set the PSH_HASHELP flag in the dwFlags member of the property sheet's PROPSHEETHEADER structure.
  • For each page that will display a Help button, set the PSP_HASHELP flag in the dwFlags member of the page's PROPSHEETPAGE structure.

When the user clicks the Help button, the active page receives a PSN_HELP notification message. The page must respond by displaying Help information, typically by calling the WinHelp function.

Removing the Caption Bar Help Button

The caption bar Help button is displayed by default, so that context-sensitive Help is always available for the OK/Cancel/Apply buttons. However, this button can be removed, if necessary. To remove a property sheet's caption bar Help button:

  • For versions of the common controls prior to version 5.80, you must implement a property sheet callback function.
  • For version 5.80 and later of the common controls, you can simply set the PSH_NOCONTEXTHELP flag in the dwFlags member of the property sheet's PROPSHEETHEADER structure. However, if you need backward compatibility with earlier common control versions, you must implement the callback function.
To implement a property sheet callback function that removes the caption bar Help button:
  • Set the PSH_USECALLBACK flag in the dwFlags member of the property sheet's PROPSHEETHEADER structure.
  • Set the pfnCallBack member of the PROPSHEETHEADER structure to point to the callback function.
  • Implement the callback function. When this function receives the PSCB_PRECREATE message, it will also receive a pointer to the property sheet's dialog box template. Remove the DS_CONTEXTHELP style from this template.

The following sample illustrates how to implement such a callback function:

int CALLBACK RemoveContextHelpProc(HWND hwnd, UINT message, LPARAM lParam)
{
    switch (message) {
    case PSCB_PRECREATE:
        // Remove the DS_CONTEXTHELP style from the dialog box template
        if (((LPDLGTEMPLATEEX)lParam)->signature ==  0xFFFF){
            ((LPDLGTEMPLATEEX)lParam)->style &= ~DS_CONTEXTHELP;
        }
        else {
            ((LPDLGTEMPLATE)lParam)->style &= ~DS_CONTEXTHELP;
        }
        return TRUE;
    }
    return TRUE;
}

If the DLGTEMPLATEEX structure is not defined, include the following declaration:

#include <pshpack1.h>
typedef struct DLGTEMPLATEEX
{
    WORD dlgVer;
    WORD signature;
    DWORD helpID;
    DWORD exStyle;
    DWORD style;
    WORD cDlgItems;
    short x;
    short y;
    short cx;
    short cy;
} DLGTEMPLATEEX, *LPDLGTEMPLATEEX;
#include <poppack.h>

OK, Cancel, and Apply Buttons

The OK and Apply buttons are similar; both direct a property sheet's pages to validate and apply the property changes that the user has made. The only difference is that clicking the OK button causes the property sheet to be destroyed after the changes are applied.

When the user clicks the OK or Apply button, the property sheet sends a PSN_KILLACTIVE notification to the active page, giving it an opportunity to validate the user's changes. If the changes are valid, the page must call the SetWindowLong function with the DWL_MSGRESULT value set to FALSE. If the user's changes are not valid, the page must set DWL_MSGRESULT to TRUE and display a dialog box informing the user of the problem. The page remains active until it sets DWL_MSGRESULT to FALSE in response to a PSN_KILLACTIVE message.

After a page responds to a PSN_KILLACTIVE notification by setting DWL_MSGRESULT to FALSE, the property sheet will send a PSN_APPLY notification to each page. When a page receives this notification, it must apply the new properties to the corresponding item. To indicate to the property sheet that the changes are valid for the page, call SetWindowLong with DWL_MSGRESULT set to PSNRET_NOERROR. If the changes are invalid for the page, return an error. Doing so prevents the property sheet from being destroyed and returns focus to either the page that received the PSN_APPLY notification or the page that had focus when the Apply button was pressed. To return an error, and indicate which page will receive focus, set DWL_MSGRESULT to one of the following values.

  • PSNRET_INVALID. The property sheet will not be destroyed, and focus will be returned to this page.
  • PSNRET_INVALID_NOCHANGEPAGE. The property sheet will not be destroyed, and focus will be returned to the page that had focus when the button was pressed.

An application can use the PSM_APPLY message to simulate the selection of the Apply button.

The Apply button is initially disabled when a page becomes active, indicating that there are not yet any property changes to apply. When the page receives input through one of its controls indicating that the user has edited a property, the page must send the PSM_CHANGED message to the property sheet. The message causes the property sheet to enable the Apply button. If the user subsequently clicks the Apply or Cancel button, the page must reinitialize its controls and then send the PSM_UNCHANGED message to again disable the Apply button.

Sometimes the Apply button causes a page to make a change to a property sheet, and the change cannot be undone. When this happens, the page must send the PSM_CANCELTOCLOSE message to the property sheet. The message causes the property sheet to change the text of the OK button to "Close," indicating that the applied changes cannot be canceled.

Sometimes a page makes a change to the system configuration that requires Windows to be restarted or the system rebooted before the change can take effect. After making such a change, a page must send either the PSM_RESTARTWINDOWS or PSM_REBOOTSYSTEM message to the property sheet. These messages cause the PropertySheet function to return the ID_PSRESTARTWINDOWS or ID_PSREBOOTSYSTEM value after the property sheet is destroyed.

When a user clicks the Cancel button, the property sheet sends the PSN_RESET notification message to all pages, indicating that the property sheet is about to be destroyed. A page must use the notification to perform cleanup operations.

Using Property Sheets

This section contains examples that demonstrate how to create a property sheet and process notification messages.

Creating a Property Sheet

The example in this section creates a property sheet that contains two pages—one for setting the font properties of a cell in a spreadsheet and another for setting the border properties of the cell. The example defines the pages by filling a pair of PROPSHEETPAGE structures and specifying the address in the PROPSHEETHEADER structure that is passed to the PropertySheet function. The dialog box templates, icons, and labels for the pages are loaded from the resources contained in the application's executable file. The icon for the property sheet is also loaded from the application's resources.

// DoPropertySheet - creates a property sheet that contains two pages.
// hwndOwner - handle to the owner window of the property sheet.
//
// Global variables
//     g_hinst - instance handle
extern HINSTANCE g_hinst;

VOID DoPropertySheet(HWND hwndOwner)
{
    PROPSHEETPAGE psp[2];
    PROPSHEETHEADER psh;

    psp[0].dwSize = sizeof(PROPSHEETPAGE);
    psp[0].dwFlags = PSP_USEICONID | PSP_USETITLE;
    psp[0].hInstance = g_hinst;
    psp[0].pszTemplate = MAKEINTRESOURCE(DLG_FONT);
    psp[0].pszIcon = MAKEINTRESOURCE(IDI_FONT);
    psp[0].pfnDlgProc = FontDialogProc;
    psp[0].pszTitle = MAKEINTRESOURCE(IDS_FONT)
    psp[0].lParam = 0;
    psp[0].pfnCallback = NULL;

    psp[1].dwSize = sizeof(PROPSHEETPAGE);
    psp[1].dwFlags = PSP_USEICONID | PSP_USETITLE;
    psp[1].hInstance = g_hinst;
    psp[1].pszTemplate = MAKEINTRESOURCE(DLG_BORDER);
    psp[1].pszIcon = MAKEINTRESOURCE(IDI_BORDER);
    psp[1].pfnDlgProc = BorderDialogProc;
    psp[1].pszTitle = MAKEINTRESOURCE(IDS_BORDER);
    psp[1].lParam = 0;
    psp[1].pfnCallback = NULL;

    psh.dwSize = sizeof(PROPSHEETHEADER);
    psh.dwFlags = PSH_USEICONID | PSH_PROPSHEETPAGE;
    psh.hwndParent = hwndOwner;
    psh.hInstance = g_hinst;
    psh.pszIcon = MAKEINTRESOURCE(IDI_CELL_PROPERTIES);
    psh.pszCaption = (LPSTR) "Cell Properties";
    psh.nPages = sizeof(psp) / sizeof(PROPSHEETPAGE);
    psh.nStartPage = 0;
    psh.ppsp = (LPCPROPSHEETPAGE) &psp;
    psh.pfnCallback = NULL;

    PropertySheet(&psh);
    return;
}

Processing Notification Messages

A property sheet sends WM_NOTIFY messages to retrieve information from the pages and to notify the pages of user actions. The lParam parameter of the message is the address of an NMHDR structure, which contains the handle to the property sheet dialog box, the handle to the page dialog box, and a notification code. The page must respond to some notification messages by setting the DWL_MSGRESULT value of the page to either TRUE or FALSE.

The following example is a code fragment from the dialog box procedure for a page. It shows how to process the PSN_HELP notification message.

case WM_NOTIFY:
    switch (((NMHDR FAR *) lParam)->code) {

        case PSN_HELP:
             {
             char szBuf[FILE_LEN]; // buffer for name of Help file

             // Display Help for the font properties page.
             LoadString(g_hinst, IDS_HELPFILE, &szBuf, FILE_LEN)
             WinHelp(((NMHDR FAR *) lParam)->hwndFrom, &szBuf,
                 HELP_CONTEXT, IDH_FONT_PROPERTIES);
             break;
             }
        .
        . // Process other property sheet notifications here.
        .
    }

Property Sheet Updates in Internet Explorer

Property sheets in Microsoft® Internet Explorer support the following new features.

New Notification
The PSN_GETOBJECT notification has been added to allow a page to be an OLE drop target.
Updated Structures
The PROPSHEETHEADER and PROPSHEETPAGE structures have been updated to support new features. See the references for these structures for more information.


AddPropSheetPageProc

Specifies an application-defined callback function that a property sheet extension uses to add a page to a property sheet.

BOOL CALLBACK AddPropSheetPageProc(
    HPROPSHEETPAGE hpage,
    LPARAM lParam
);

Parameters

hpage
Handle to a property sheet page.
lParam
Application-defined 32-bit value.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: None.
Import Library: user-defined.


CreatePropertySheetPage

Creates a new page for a property sheet.

HPROPSHEETPAGE CreatePropertySheetPage(
    LPCPROPSHEETPAGE lppsp
);

Parameters

lppsp
Address of a PROPSHEETPAGE structure that defines a page to be included in a property sheet.

Return Values

Returns the handle to the new property page if successful, or NULL otherwise.

Remarks

An application uses the PropertySheet function to create a property sheet that includes the new page, or it uses the PSM_ADDPAGE message to add the new page to an existing property sheet.

Windows 95: The system can support a maximum of 16,364 window handles.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.
Import Library: comctl32.lib.


DestroyPropertySheetPage

Destroys a property sheet page. An application must call this function for pages that have not been passed to the PropertySheet function.

BOOL DestroyPropertySheetPage(
    HPROPSHEETPAGE hPSPage
);

Parameters

hPSPage
Handle to the property sheet page to delete.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.
Import Library: comctl32.lib.


PropertySheet

Creates a property sheet and adds the pages defined in the specified property sheet header structure.

int PropertySheet(
    LPCPROPSHEETHEADER lppsph
);

Parameters

lppsph
Pointer to a PROPSHEETHEADER structure that defines the frame and pages of a property sheet.

Return Values

Returns a positive value if successful, or -1 otherwise for modal property sheets.

Returns the property sheet's window handle for modeless property sheets.

The following return values have a special meaning:

ID_PSREBOOTSYSTEM | A page sent the PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect.
ID_PSRESTARTWINDOWS | A page sent the PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect.

To retrieve extended error information, call GetLastError.

Remarks

By default, the PropertySheet function creates a modal dialog box. If the dwFlags member of the PROPSHEETHEADER structure specifies the PSH_MODELESS flag, PropertySheet creates a modeless dialog box and returns immediately after it is created. In this case, the PropertySheet return value is the window handle to the modeless dialog box.

For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog box. Your message loop should use PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL. You can then use the DestroyWindow function to destroy the dialog box.

Version 5.80. The PropertySheet return value carries different information for modal and modeless property sheets. In some cases, modeless property sheets may need the information they would have received from PropertySheet if they had been modal. In particular, they may need to know whether ID_PSREBOOTSYSTEM or ID_PSRESTARTWINDOWS would have been returned. A modeless property sheet can retrieve the value that a modal property sheet would have received from PropertySheet by waiting until PSM_GETCURRENTPAGEHWND returns NULL and then sending a PSM_GETRESULT message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.
Import Library: comctl32.lib.


PropSheetPageProc

Specifies an application-defined callback function that a property sheet calls when a page is created and when it is about to be destroyed. An application can use this function to perform initialization and cleanup operations for the page.

UINT CALLBACK PropSheetPageProc(
    HWND hwnd,
    UINT uMsg,
    LPPROPSHEETPAGE ppsp
);

Parameters

hwnd
Reserved; must be NULL.
uMsg
[in] Action flag. This parameter can be one of the following values:
PSPCB_ADDREF | Version 5.80. A page is being created. The return value is not used.
PSPCB_CREATE | A dialog box for a page is being created. Return nonzero to allow it to be created, or zero to prevent it.
PSPCB_RELEASE | A page is being destroyed. The return value is ignored.
ppsp
[in/out] Address of a PROPSHEETPAGE structure that defines the page being created or destroyed. See the Remarks section for further discussion.

Return Values

The return value depends on the value of the uMsg parameter.

Remarks

An application must specify the address of this callback function in the pfnCallback member of a PROPSHEETPAGE structure before passing the structure to the CreatePropertySheetPage function.

Note: The property sheet is in the process of manipulating the list of pages when this function is called. Do not attempt to add, remove, or insert pages while handling this notification. Doing so will have unpredictable results.

With the exception of the lParam member, your application should not modify the PROPSHEETPAGE structure. Doing so will have unpredictable results. The lParam member contains application-defined data and can be modified as needed.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: None.
Import Library: user-defined.


PropSheetProc

An application-defined callback function that the system calls when the property sheet is being created and initialized.

int CALLBACK PropSheetProc(
    HWND hwndDlg,
    UINT uMsg,
    LPARAM lParam
);

Parameters

hwndDlg
Handle to the property sheet dialog box.
uMsg
Message being received. This parameter is one of the following values:
PSCB_INITIALIZED | Indicates that the property sheet is being initialized. The lParam value is zero for this message.
PSCB_PRECREATE | Indicates that the property sheet is about to be created. The hwndDlg parameter is NULL, and the lParam parameter is the address of a dialog template in memory. This template is in the form of a DLGTEMPLATE or DLGTEMPLATEEX structure followed by one or more DLGITEMTEMPLATE structures.
lParam
Additional information about the message. The meaning of this value depends on the uMsg parameter.

Return Values

Returns zero.

Remarks

To enable a PropSheetProc callback function, use the PROPSHEETHEADER structure when you call the PropertySheet function to create the property sheet. Use the pfnCallback member to specify an address of the callback function, and set the PSP_USECALLBACK flag in the dwFlags member.

PropSheetProc is a placeholder for the application-defined function name. The PFNPROPSHEETCALLBACK type is the address of a PropSheetProc callback function.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: None.
Import Library: user-defined.


PSM_ADDPAGE

Adds a new page to the end of an existing property sheet. You can send this message explicitly or by using the PropSheet_AddPage macro.

PSM_ADDPAGE
    wParam = 0;
    lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

Parameters

hpage
Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The new page should be no larger than the largest page currently in the property sheet because the property sheet is not resized to fit the new page.

A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Accordingly, you should not use the PSM_ADDPAGE message in your implementation of PropSheetPageProc or while handling the following notifications and Microsoft® Windows® messages:

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • WM_DESTROY
  • WM_INITDIALOG

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_APPLY

Simulates the selection of the Apply button, indicating that one or more pages have changed and the changes need to be validated and recorded.

PSM_APPLY
    wParam = 0;
    lParam = 0;

Return Values

Returns TRUE if all pages successfully applied the changes, or FALSE otherwise.

Remarks

The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all active pages. You can send the PSM_APPLY message explicitly or by using the PropSheet_Apply macro.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_CANCELTOCLOSE

Sent by an application when it has performed changes since the most recent PSN_APPLY notification that cannot be canceled. You can send this message explicitly or by using the PropSheet_CancelToClose macro.

PSM_CANCELTOCLOSE
    wParam = 0;
    lParam = 0;

Return Values

No return value.

Remarks

PSM_CANCELTOCLOSE disables the Cancel button and changes the text of the OK button to "Close."

Most property sheets wait to perform irreversible changes until a PSN_APPLY notification is received. However, in some circumstances, a property sheet may make irreversible changes outside the standard PSN_APPLY/PSN_RESET sequence. One example is a property sheet that contains an Edit button that is used to display a subdialog box for editing a property. When the user clicks OK to submit the change, the property sheet page has several options:

  • It can record the changes, but wait until it receives a PSN_APPLY notification to apply them. This is the preferred approach.
  • It can apply the changes immediately after exiting the subdialog box, but remember the original settings. Those settings can be used to restore the original state if a PSN_RESET notification is received.
  • It can apply the changes immediately and not attempt to restore the original settings when it receives a PSN_RESET notification. This approach is not recommended, but may be necessary if the changes are too far-reaching for the other two options to be practical.

For the third option, applications should send a PSM_CANCELTOCLOSE message to the property sheet. It indicates to the user that the changes made with the subdialog box cannot be reversed by clicking the Cancel button.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_CHANGED

Informs a property sheet that information in a page has changed. You can send this message explicitly or by using the PropSheet_Changed macro.

PSM_CHANGED
    wParam = (WPARAM) (HWND) hwndPage;
    lParam = 0;

Parameters

hwndPage
Handle to the page that has changed.

Return Values

No return value.

Remarks

The property sheet will enable the Apply button.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_GETCURRENTPAGEHWND

Retrieves a handle to the window of the current page of a property sheet. You can send this message explicitly or by using the PropSheet_GetCurrentPageHwnd macro.

PSM_GETCURRENTPAGEHWND
    wParam = 0;
    lParam = 0;

Return Values

Returns a handle to the window of the current property sheet page.

Remarks

Use the PSM_GETCURRENTPAGEHWND message with modeless property sheets to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

PropertySheet

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_GETRESULT

Used by modeless property sheets to retrieve the information returned to modal property sheets by PropertySheet. You can send this message explicitly or use the PropSheet_GetResult macro.

PSM_GETRESULT
    wParam = 0;
    lParam = 0;

Parameters

None

Return Values

Returns a positive value if successful, or -1 otherwise.

The following return values have a special meaning

ID_PSREBOOTSYSTEM | A page sent a PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect.
ID_PSRESTARTWINDOWS | A page sent a PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect.

To retrieve extended error information, call GetLastError.

This return value is identical to what PropertySheet would have returned had this been a modal property sheet.

Remarks

Version 5.80. The PropertySheet return value carries different information for modal and modeless property sheets. In some cases, modeless property sheets may need the information they would have received from PropertySheet if they had been modal. In particular, they may need to know whether ID_PSREBOOTSYSTEM or ID_PSRESTARTWINDOWS would have been returned.

For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog box, and PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL. You can then retrieve the value that a modal property sheet would have received from PropertySheet by sending a PSM_GETRESULT message.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.
Import Library: comctl32.lib.


PSM_GETTABCONTROL

Retrieves the handle to the tab control of a property sheet. You can send this message explicitly or by using the PropSheet_GetTabControl macro.

PSM_GETTABCONTROL
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the tab control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_HWNDTOINDEX

Takes the window handle of the property sheet page and returns its zero-based index. You can send this message explicitly or use the PropSheet_HwndToIndex macro.

PSM_HWNDTOINDEX
    wParam = (WPARAM) (HWND) hPageDlg;

Parameters

hPageDlg
Handle to the page's window.

Return Values

Returns the zero-based index of the property sheet page specified by hPageDlg if successful. Otherwise, it returns -1.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_IDTOINDEX

Takes the resource identifier (ID) of a property sheet page and returns its zero-based index. You can send this message explicitly or use the PropSheet_IdToIndex macro.

PSM_IDTOINDEX
    lParam = (LPARAM) (int) iPageID;

Parameters

iPageID
Resource ID of the page.

Return Values

Returns the zero-based index of the property sheet page specified by iPageID if successful. Otherwise, it returns -1.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_INDEXTOHWND

Takes the index of a property sheet page and returns its window handle. You can send this message explicitly or use the PropSheet_IndexToHwnd macro.

PSM_INDEXTOHWND
    wParam = (WPARAM) (int) iPageIndex;

Parameters

iPageIndex
Zero-based index of the page.

Return Values

Returns the handle to the window of the property sheet page specified by iPageIndex if successful. Otherwise, it returns zero.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_INDEXTOID

Takes the index of a property sheet page and returns its resource identifier (ID). You can send this message explicitly or use the PropSheet_IndexToId macro.

PSM_INDEXTOID
    wParam = (WPARAM) (int) iPageIndex;

Parameters

iPageIndex
Zero-based index of the page.

Return Values

Returns the resource ID of the property sheet page specified by iPageIndex if successful. Otherwise, it returns zero.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_INDEXTOPAGE

Takes the index of a property sheet page and returns its HPROPSHEETPAGE handle. You can send this message explicitly or use the PropSheet_IndexToPage macro.

PSM_INDEXTOPAGE
    wParam = (WPARAM) (int) iPageIndex;

Parameters

iPageIndex
Zero-based index of the page.

Return Values

Returns the HPROPSHEETPAGE handle of the property sheet page specified by iPageIndex if successful. Otherwise, it returns zero.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_INSERTPAGE

Inserts a new page into an existing property sheet. The page can be inserted either at a specified index or after a specified page. You can send this message explicitly or by using the PropSheet_InsertPage macro.

PSM_INSERTPAGE
    wParam = (WPARAM) index;
    - or -
           = (WPARAM) (HPROPSHEETPAGE) hpageInsertAfter;

    lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

Parameters

wParam
Where the page is to be inserted. Set this parameter to NULL to make the new page the first page. To specify where the new page is to be inserted, you can either pass an index or an existing page's HPROPSHEETPAGE handle.
index
If the wParam parameter is less than MAXUSHORT (the largest unsigned short integer), then the wParam specifies the zero-based index for the new page. For example, to make the inserted page the third page on the property sheet, set index to 2. To make it the first page, set index to 0. If index has a value greater than the number of pages and less than MAXUSHORT, the page will be appended.
hpageInsertAfter
If you set the wParam parameter to an existing page's HPROPSHEETPAGE handle, the new page will be inserted after it.
hpage
Handle to the page to be inserted. The page must first be created by a call to the CreatePropertySheetPage function.

Return Values

Returns a nonzero value if the page was successfully inserted, or zero otherwise.

Remarks

The pages after the insertion point are shifted to the right to accommodate the new page.

The property sheet is not resized to fit the new page. Do not make the new page larger than the property sheet's largest page.

A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Accordingly, you should not use the PSM_INSERTPAGE message in your implementation of PropSheetPageProc or while handling the following notifications and Microsoft® Windows® messages:

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • WM_DESTROY
  • WM_INITDIALOG

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

The following notifications are also affected by property sheet modification.

  • PSN_WIZBACK
  • PSN_WIZNEXT

You can add or remove pages in response to these notifications, provided that you return (via DWL_MSGRESULT) a nonzero value to specify the desired new page. Note, however, that if you insert a page that is located before the current page (that has a smaller index than the current page), PSN_KILLACTIVE might be sent to the wrong page.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


PSM_ISDIALOGMESSAGE

Passes a message to a property sheet dialog box and indicates whether the dialog box processed the message. You can send this message explicitly or by using the PropSheet_IsDialogMessage macro.

PSM_ISDIALOGMESSAGE
    wParam = 0;
    lParam = (LPARAM)pMsg;

Parameters

pMsg
Address of an MSG structure that contains the message to be checked.

Return Values

Returns TRUE if the message has been processed, or FALSE if the message has not been processed.

Remarks

Your message loop should use the PSM_ISDIALOGMESSAGE message with modeless property sheets to pass messages to the property sheet dialog box. On systems that support Unicode, use the Unicode versions of the GetMessage and PeekMessage functions (GetMessageW and PeekMessageW) to retrieve messages.

If the return value indicates that the message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See Also

PropertySheet

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_PAGETOINDEX

Takes the HPROPSHEETPAGE handle of the property sheet page and returns its zero-based index. You can send this message explicitly or use the PropSheet_PageToIndex macro.

PSM_PAGETOINDEX
    lParam = (LPARAM) (HPROPSHEETPAGE) hPage;

Parameters

hPage
HPROPSHEETPAGE handle to the property sheet page.

Return Values

Returns the zero-based index of the property sheet page specified by hPage if successful. Otherwise, it returns -1.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_PRESSBUTTON

Simulates the selection of a property sheet button. You can send this message explicitly or by using the PropSheet_PressButton macro.

PSM_PRESSBUTTON
    wParam = (WPARAM) (int) iButton;
    lParam = 0;

Parameters

iButton
Index of the button to select. This parameter can be one of the following values:
PSBTN_APPLYNOW | Selects the Apply button.
PSBTN_BACK | Selects the Back button.
PSBTN_CANCEL | Selects the Cancel button.
PSBTN_FINISH | Selects the Finish button.
PSBTN_HELP | Selects the Help button.
PSBTN_NEXT | Selects the Next button.
PSBTN_OK | Selects the OK button.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_QUERYSIBLINGS

Sent to a property sheet, which then forwards the message to each of its pages. You can send this message explicitly or by using the PropSheet_QuerySiblings macro.

PSM_QUERYSIBLINGS
    wParam = (WPARAM) param1;
    lParam = (LPARAM) param2;

Parameters

param1
First application-defined parameter.
param2
Second application-defined parameter.

Return Values

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.

Remarks

If a page returns a nonzero value, the property sheet does not send the message to subsequent pages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_REBOOTSYSTEM

Indicates the system needs to be restarted for the changes to take effect. You can send the PSM_REBOOTSYSTEM message explicitly or by using the PropSheet_RebootSystem macro.

PSM_REBOOTSYSTEM
    wParam = 0;
    lParam = 0;

Return Values

No return value.

Remarks

An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

This message causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This message supersedes all PSM_RESTARTWINDOWS messages that precede or follow it.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_RECALCPAGESIZES

Recalculates the page size of a standard or wizard property sheet after pages have been added or removed. You can send this message explicitly or use the PropSheet_RecalcPageSizes macro.

PSM_RECALCPAGESIZES
    wParam = 0;
    lParam = 0;

Parameters

None

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a property sheet is created, it is sized to fit its initial collection of pages. In order to maintain compatibility with previous versions of the common controls, property sheets and wizards do not automatically resize themselves when pages are subsequently added or removed. With common controls version 5.80 and later, applications should send a PSM_RECALCPAGESIZES message after adding or removing pages with PSM_ADDPAGE, PSM_INSERTPAGE, PSM_REMOVEPAGE, or their equivalent macros. It ensures that the property sheet is properly sized for its current collection of pages. If this message is not sent, some property sheet pages may be truncated or too large.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.
Import Library: comctl32.lib.


PSM_REMOVEPAGE

Removes a page from a property sheet. You can send this message explicitly or by using the PropSheet_RemovePage macro.

PSM_REMOVEPAGE
    wParam = (WPARAM) (int) index;
    lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

Parameters

index
Zero-based index of the page to be removed.
hpage
The HPROPSHEETPAGE handle of the page to be removed.

Return Values

No return value.

Remarks

An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

Sending PSM_REMOVEPAGE destroys the property sheet page that is being removed.

A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Accordingly, you should not use the PSM_REMOVEPAGE message in your implementation of PropSheetPageProc or while handling the following notifications and Microsoft® Windows® messages:

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • WM_DESTROY
  • WM_INITDIALOG

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

The following notifications are also affected by property sheet modification.

  • PSN_WIZBACK
  • PSN_WIZNEXT

You can add or remove pages in response to these notifications, provided that you return (via DWL_MSGRESULT) a nonzero value to specify the desired new page. Note, however, that if you remove a page that is located before the current page (that has a smaller index than the current page), PSN_KILLACTIVE might be sent to the wrong page.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_RESTARTWINDOWS

Indicates that Windows needs to be restarted for the changes to take effect.

PSM_RESTARTWINDOWS
    wParam = 0;
    lParam = 0;

Return Values

No return value.

Remarks

An application should send this message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message. You can send the PSM_RESTARTWINDOWS message explicitly or by using the PropSheet_RestartWindows macro.

This message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to restart Windows, which can be done by using the ExitWindowsEx function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_SETCURSEL

Activates the specified page in a property sheet. You can send this message explicitly or by using the PropSheet_SetCurSel macro.

PSM_SETCURSEL
    wParam = (WPARAM) (int) index;
    lParam = (LPARAM) (HPROPSHEETPAGE) hpage;

Parameters

index and hpage
The zero-based index of the page and the handle to the page to activate, respectively. An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_SETCURSELID

Activates the given page in a property sheet based on the resource identifier of the page. You can send this message explicitly or by using the PropSheet_SetCurSelByID macro.

PSM_SETCURSELID
    wParam = 0;
    lParam = (LPARAM) (int) id;

Parameters

id
Resource identifier of the page to activate.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_SETFINISHTEXT

Sets the text of the Finish button in a wizard, shows and enables the button, and hides the Next and Back buttons. You can send this message explicitly or by using the PropSheet_SetFinishText macro.

PSM_SETFINISHTEXT
    wParam = 0;
    lParam = (LPARAM) (LPSTR) lpszText;

Parameters

lpszText
Pointer to the new text for the Finish button.

Return Values

No return value.

Remarks

By default, the Finish button does not have a keyboard accelerator. You can create a keyboard accelerator with this message by including an ampersand (&) in the text string that you assign to lpszText. For example, "&Finish" defines F as the accelerator key.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_SETHEADERSUBTITLE

Sets the subtitle text for the header of a wizard's interior page. You can send this message explicitly or use the PropSheet_SetHeaderSubTitle macro.

PSM_SETHEADERSUBTITLE
    wParam = (WPARAM) (int) iPageIndex;
    lParam = (LPARAM) (LPCTSTR) pszHeaderSubTitle;

Parameters

iPageIndex
Zero-based index of the wizard's page.
pszHeaderSubTitle
New header subtitle.

Return Values

No return value.

Remarks

If you specify the current page, it will immediately be repainted to display the new subtitle.

See Also

PSM_HWNDTOINDEX, PSM_IDTOINDEX, PSM_PAGETOINDEX

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_SETHEADERTITLE

Sets the title text for the header of a wizard's interior page. You can send this message explicitly or use the PropSheet_SetHeaderTitle macro.

PSM_SETHEADERTITLE
    wParam = (WPARAM) (int) iPageIndex;
    lParam = (LPARAM) (LPCTSTR) pszHeaderTitle;

Parameters

iPageIndex
Zero-based index of the wizard's page.
pszHeaderTitle
New header subtitle.

Return Values

No return value.

Remarks

If you specify the current page, it will immediately be repainted to display the new title.

See Also

PSM_HWNDTOINDEX, PSM_IDTOINDEX, PSM_PAGETOINDEX

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PSM_SETTITLE

Sets the title of a property sheet. You can send this message explicitly or by using the PropSheet_SetTitle macro.

PSM_SETTITLE
    wParam = (WPARAM) (DWORD) dwStyle
    lParam = (LPARAM) (LPCSTR) lpszText;

Parameters

dwStyle
Flag that indicates whether to include the prefix "Properties for" with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.
lpszText
Address of a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSM_SETWIZBUTTONS

Enables or disables the Back, Next, and Finish buttons in a wizard. You can also use the PropSheet_SetWizButtons macro to post the message.

PSM_SETWIZBUTTONS
    wParam = 0;
    lParam = (LPARAM) (DWORD) dwFlags;

Parameters

dwFlags
Value that specifies which property sheet buttons are enabled. You can combine one or more of the following flags.
PSWIZB_BACK | Enables the Back button. If this flag is not set, the Back button is displayed as disabled.
PSWIZB_DISABLEDFINISH | Displays a disabled Finish button.
PSWIZB_FINISH | Displays an enabled Finish button.
PSWIZB_NEXT | Enables the Next button. If this flag is not set, the Next button is displayed as disabled.

Return Values

No return value.

Remarks

If your notification handler uses PostMessage to send a PSM_SETWIZBUTTONS message, do nothing that will affect window focus until after the handler returns. For example, if you call MessageBox immediately after using PostMessage to send PSM_SETWIZBUTTONS, the message box will receive focus. Since posted messages are not delivered until they reach the head of the message queue, the PSM_SETWIZBUTTONS message will not be delivered until after the wizard has lost focus to the message box. As a result, the property sheet will not be able to properly set the focus for the buttons.

If you send the PSM_SETWIZBUTTONS message during your handling of the PSN_SETACTIVE notification message, use the PostMessage function rather than the SendMessage function. Otherwise, the system will not update the buttons properly. If you use the PropSheet_SetWizButtons macro to send this message, it will be posted. At any other time, you can use SendMessage to send PSM_SETWIZBUTTONS.

Wizards display either three or four buttons below each page. This message is used to specify which buttons are enabled. Wizards normally display Back, Cancel, and either a Next or Finish button. You typically enable only the Next button for the welcome page, Next and Back for interior pages, and Back and Finish for the completion page. The Cancel button is always enabled. Normally, setting PSWIZB_FINISH or PSWIZB_DISABLEDFINISH replaces the Next button with a Finish button. To display Next and Finish buttons simultaneously, set the PSH_WIZARDHASFINISH FLAG in the dwFlags member of the wizard's PROPSHEETHEADER structure when you create the wizard. Every page will then display all four buttons.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSM_UNCHANGED

Informs a property sheet that information in a page has reverted to the previously saved state. You can send this message explicitly or by using the PropSheet_UnChanged macro.

PSM_UNCHANGED
    wParam = (WPARAM) (HWND) hwndPage;
    lParam = 0;

Parameters

hwndPage
Handle to the page that has reverted to the previously saved state.

Return Values

No return value.

Remarks

The property sheet disables the Apply button if no other pages have registered changes with the property sheet.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_AddPage

Adds a new page to the end of an existing property sheet. You can use this macro or send the PSM_ADDPAGE message explicitly.

BOOL PropSheet_AddPage(
    HWND hPropSheetDlg,
    HPROPSHEETPAGE hpage,
);

Parameters

hPropSheetDlg
Handle to the property sheet.
hpage
Handle to the page to add. The page must have been created by a previous call to the CreatePropertySheetPage function.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The new page should be no larger than the largest page currently in the property sheet because the property sheet is not resized to fit the new page.

A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Accordingly, you should not use the PropSheet_AddPage macro in your implementation of PropSheetPageProc or while handling the following notifications and Microsoft® Windows® messages:

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • WM_DESTROY
  • WM_INITDIALOG

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_Apply

Simulates the selection of the Apply button, indicating that one or more pages have changed and the changes need to be validated and recorded. You can use this macro or send the PSM_APPLY message explicitly.

BOOL PropSheet_Apply(
    HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

Returns TRUE if all pages successfully applied the changes, or FALSE otherwise.

Remarks

The property sheet sends the PSN_KILLACTIVE notification message to the current page. If the current page returns FALSE, the property sheet sends the PSN_APPLY notification message to all active pages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_CancelToClose

Used when changes made since the most recent PSN_APPLY notification cannot be canceled. You can also send a PSM_CANCELTOCLOSE message explicitly.

VOID PropSheet_CancelToClose(
    HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

No return value.

Remarks

PSM_CANCELTOCLOSE disables the Cancel button and changes the text of the OK button to "Close." You can use this macro or send the PSM_CANCELTOCLOSE message explicitly.

Most property sheets wait to perform irreversible changes until a PSN_APPLY notification is received. However, in some circumstances, a property sheet may make irreversible changes outside the standard PSN_APPLY/PSN_RESET sequence. One example is a property sheet that contains an Edit button that is used to display a subdialog box for editing a property. When the user clicks OK to submit the change, the property sheet page has several options:

  • It can record the changes but wait until it receives a PSN_APPLY notification to apply them. This is the preferred approach.
  • It can apply the changes immediately after exiting the subdialog box, but remember the original settings. Those settings can be used to restore the original state if a PSN_RESET notification is received.
  • It can apply the changes immediately and not attempt to restore the original settings when it receives a PSN_RESET notification. This approach is not recommended, but may be necessary if the changes are too far-reaching for the other two options to be practical.

For the third option, applications should send a PSM_CANCELTOCLOSE message to the property sheet. It indicates to the user that the changes made with the subdialog box cannot be reversed by clicking the Cancel button.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_Changed

Informs a property sheet that information in a page has changed. You can use this macro or send the PSM_CHANGED message explicitly.

BOOL PropSheet_Changed(
    HWND hPropSheetDlg,
    HWND hwndPage
);

Parameters

hPropSheetDlg
Handle to the property sheet.
hwndPage
Handle to the page that has changed.

Return Values

No return value.

Remarks

The property sheet enables the Apply button.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_GetCurrentPageHwnd

Retrieves a handle to the window of the current page of a property sheet. You can use this macro or send the PSM_GETCURRENTPAGEHWND message explicitly.

HWND PropSheet_GetCurrentPageHwnd(
    HWND hDlg
);

Parameters

hDlg
Handle to the property sheet.

Return Values

Returns a handle to the window of the current property sheet page.

Remarks

Use the PropSheet_GetCurrentPageHwnd macro with modeless property sheets to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PropSheet_GetCurrentPageHwnd returns NULL, and you can then use the DestroyWindow function to destroy the dialog box.

See Also

PropertySheet

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_GetResult

Used by modeless property sheets to retrieve the information returned to modal property sheets by PropertySheet. You can use this macro or sent the PSM_GETRESULT message explicitly.

int PropSheet_GetResult (
    HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet's dialog box.

Return Values

Returns a positive value if successful, or -1 otherwise.

The following return values have a special meaning.

ID_PSREBOOTSYSTEM | A page sent a PSM_REBOOTSYSTEM message to the property sheet. The computer must be restarted for the user's changes to take effect.
ID_PSRESTARTWINDOWS | A page sent a PSM_RESTARTWINDOWS message to the property sheet. Windows must be restarted for the user's changes to take effect.

To retrieve extended error information, call GetLastError.

This return value is identical to what PropertySheet would have returned had this been a modal property sheet.

Remarks

Version 5.80. The PropertySheet return value carries different information for modal and modeless property sheets. In some cases, modeless property sheets may need the information they would have received from PropertySheet if they had been modal. In particular, they may need to know whether ID_PSREBOOTSYSTEM or ID_PSRESTARTWINDOWS would have been returned.

For a modeless property sheet, your message loop should use PSM_ISDIALOGMESSAGE to pass messages to the property sheet dialog box, and PSM_GETCURRENTPAGEHWND to determine when to destroy the dialog box. When the user clicks the OK or Cancel button, PSM_GETCURRENTPAGEHWND returns NULL. You can then retrieve the value that a modal property sheet would have received from PropertySheet by sending a PSM_GETRESULT message.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.
Import Library: comctl32.lib.


PropSheet_GetTabControl

Retrieves the handle to the tab control of a property sheet. You can use this macro or send the PSM_GETTABCONTROL message explicitly.

HWND PropSheet_GetTabControl(
    HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

Returns the handle to the tab control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_HwndToIndex

Takes a window handle of the property sheet page and returns its zero-based index. You can use this macro or send the PSM_HWNDTOINDEX message explicitly.

int PropSheet_HwndToIndex(
  HWND hPropSheetDlg,
  HWND hPageDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet's window.
hPageDlg
Handle to the page's window.

Return Values

Returns the zero-based index of the property sheet page specified by hPageDlg if successful. Otherwise, it returns -1.

See Also

PropSheet_GetCurrentPageHwnd, GetParent

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_IdToIndex

Takes the resource identifier (ID) of a property sheet page and returns its zero-based index. You can use this macro or send the PSM_IDTOINDEX message explicitly.

int PropSheet_IdToIndex(
  HWND hPropSheetDlg,
  int iPageID
);

Parameters

hPropSheetDlg
Handle to the property sheet window.
iPageID
Resource ID of the page.

Return Values

Returns the zero-based index of the property sheet page specified by iPageID if successful. Otherwise, it returns -1.

See Also

PropSheet_IndexToId

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_IndexToHwnd

Takes the index of a property sheet page and returns its window handle. You can use this macro or send the PSM_INDEXTOHWND message explicitly.

HWND PropSheet_IndexToHwnd(
  HWND hPropSheetDlg,
  int iPageIndex
);

Parameters

hPropSheetDlg
Handle to the property sheet page's window.
iPageIndex
Zero-based index of the page.

Return Values

Returns the handle to the property sheet page's window specified by iPageIndex if successful. Otherwise, it returns zero.

See Also

PropSheet_HwndToIndex

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_IndexToId

Takes the index of a property sheet page and returns its resource identifier (ID). You can use this macro or send the PSM_INDEXTOID message explicitly.

int PropSheet_IndexToId(
  HWND hPropSheetDlg,
  int iPageIndex
);

Parameters

hPropSheetDlg
Handle to the property sheet.
iPageIndex
Zero-based index of the page.

Return Values

Returns the resource ID of the property sheet page specified by iPageIndex if successful. Otherwise, it returns zero.

See Also

PSM_INDEXTOID

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_IndexToPage

Takes the index of a property sheet page and returns its HPROPSHEETPAGE handle. You can use this macro or send the PSM_INDEXTOPAGE message explicitly.

HPROPSHEETPAGE PropSheet_IndexToPage(
  HWND hPropSheetDlg,
  int iPageIndex
);

Parameters

hPropSheetDlg
Handle to the property sheet window.
iPageIndex
Zero-based ndex of the page.

Return Values

Returns the HPROPSHEETPAGE handle of the property sheet page specified by iPageIndex if successful. Otherwise, it returns zero.

See Also

PropSheet_PageToIndex

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_InsertPage

Inserts a new page into an existing property sheet. The page can be inserted either at a specified index or after a specified page. You can use this macro or send the PSM_INSERTPAGE message explicitly.

BOOL PropSheet_InsertPage (
    HWND hPropSheetDlg,
    (WPARAM) int index,
    HPROPSHEETPAGE hpage
);

- or -

BOOL PropSheet_InsertPage (
    HWND hPropSheetDlg,
    (WPARAM) HPROPSHEETPAGE hpageInsertAfter,
    HPROPSHEETPAGE hpage
);

Parameters

hPropSheetDlg
Handle to the property sheet.
wParam
Where the page is to be inserted. Set wParam to NULL to make the new page the first page. To specify where the new page is to be inserted, you can either pass an index or an existing page's HPROPSHEETPAGE handle.
index
If wParam is less than MAXUSHORT (the largest unsigned short integer), it specifies the zero-based index for the new page. For example, to make the inserted page the third page on the property sheet, set index to 2. To make it the first page, set index to 0. If index has a value greater than the number of pages and less than MAXUSHORT, the page will be appended.
hpageInsertAfter
If you set wParam to an existing page's HPROPSHEETPAGE handle, the new page will be inserted after it.
hpage
Handle to the page to be inserted. The page must first be created by a call to the CreatePropertySheetPage function.

Return Values

Returns a nonzero value if the page was successfully inserted, or zero otherwise.

Remarks

The pages after the insertion point are shifted to the right to accommodate the new page.

The property sheet is not resized to fit the new page. Do not make the new page larger than the property sheet's largest page.

A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Accordingly, you should not use the PropSheet_InsertPage macro in your implementation of PropSheetPageProc or while handling the following notifications and Microsoft® Windows® messages:

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • WM_DESTROY
  • WM_INITDIALOG

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

The following notifications are also affected by property sheet modification.

  • PSN_WIZBACK
  • PSN_WIZNEXT

You can add or remove pages in response to these notifications, provided that you return (via DWL_MSGRESULT) a nonzero value to specify the desired new page. Note, however, that if you insert a page that is located before the current page (that has a smaller index than the current page), PSN_KILLACTIVE might be sent to the wrong page.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_IsDialogMessage

Passes a message to a property sheet dialog box and indicates whether the dialog box processed the message. You can use this macro or send the PSM_ISDIALOGMESSAGE message explicitly.

BOOL PropSheet_IsDialogMessage(
    HWND hDlg,
    LPMSG pMsg
);

Parameters

hDlg
Handle to the property sheet.
pMsg
Address of an MSG structure that contains the message to be checked.

Return Values

Returns TRUE if the macro has been processed, or FALSE if the macro has not been processed.

Remarks

Your message loop should use the PropSheet_IsDialogMessage macro with modeless property sheets to pass messages to the property sheet dialog box. On systems that support Unicode, use the Unicode versions of the GetMessage and PeekMessage functions (GetMessageW and PeekMessageW) to retrieve messages.

If the return value indicates that the message was processed, it must not be passed to the TranslateMessage or DispatchMessage function.

See Also

PropertySheet

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_PageToIndex

Takes the HPROPSHEETPAGE handle of a property sheet page and returns its zero-based index. You can use this macro or send the PSM_PAGETOINDEX message explicitly.

int PropSheet_PageToIndex(
  HWND hPropSheetDlg,
  HPROPSHEETPAGE hPage,
);

Parameters

hPropSheetDlg
Handle to the property sheet.
hPage
HPROPSHEETPAGE handle to the property sheet page.

Return Values

Returns the zero-based index of the property sheet page specified by hPage if successful. Otherwise, it returns -1.

See Also

CreatePropertySheetPage, PropSheet_IndexToPage

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_PressButton

Simulates the selection of a property sheet button. You can use this macro or send the PSM_PRESSBUTTON message explicitly.

BOOL PropSheet_PressButton(
    HWND hPropSheetDlg,
    int iButton
);

Parameters

hPropSheetDlg
Handle to the property sheet.
iButton
Index of the button to select. This parameter can be one of the following values:
PSBTN_APPLYNOW | Selects the Apply button.
PSBTN_BACK | Selects the Back button.
PSBTN_CANCEL | Selects the Cancel button.
PSBTN_FINISH | Selects the Finish button.
PSBTN_HELP | Selects the Help button.
PSBTN_NEXT | Selects the Next button.
PSBTN_OK | Selects the OK button.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_QuerySiblings

Causes a property sheet to send the PSM_QUERYSIBLINGS message to each of its pages. You can use this macro or send the PSM_QUERYSIBLINGS message explicitly.

int PropSheet_QuerySiblings(
    HWND hPropSheetDlg,
    WPARAM param1,
    LPARAM param2
);

Parameters

hPropSheetDlg
Handle to the property sheet.
param1
First application-defined parameter.
param2
Second application-defined parameter.

Return Values

Returns the nonzero value from a page in the property sheet, or zero if no page returns a nonzero value.

Remarks

If a page returns a nonzero value, the property sheet does not send the message to subsequent pages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_RebootSystem

Indicates the system needs to be restarted for the changes to take effect. You can use this macro or send the PSM_REBOOTSYSTEM message explicitly.

VOID PropSheet_RebootSystem(
    HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

No return value.

Remarks

An application should send the PSM_REBOOTSYSTEM message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

This macro causes the PropertySheet function to return the ID_PSREBOOTSYSTEM value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to reboot the system, which can be done by using the ExitWindowsEx function.

This macro supersedes all PropSheet_RebootSystem macros that precede or follow it.

See Also

PSM_RESTARTWINDOWS

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_RecalcPageSizes

Recalculates the page size of a standard or wizard property sheet after pages have been added or removed. You can use this macro or send the PSM_RECALCPAGESIZES message explicitly.

BOOL PropSheet_RecalcPageSizes(
  HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet's dialog box.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a property sheet is created, it is sized to fit its initial collection of pages. To maintain compatibility with previous versions of the common controls, property sheets and wizards do not automatically resize themselves when pages are subsequently added or removed. With common controls version 5.80 and later, applications should use the PropSheet_RecalcPageSizes macro after adding or removing pages with PropSheet_AddPage, PropSheet_InsertPage, PropSheet_RemovePage, or their equivalent messages. It ensures that the property sheet is properly sized for its current collection of pages. If this macro or the equivalent message is not used, some property sheet pages may be truncated or too large.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.
Import Library: comctl32.lib.


PropSheet_RemovePage

Removes a page from a property sheet. You can use this macro or send the PSM_REMOVEPAGE message explicitly.

VOID PropSheet_RemovePage(
    HWND hPropSheetDlg,
    int index,
    HPROPSHEETPAGE hpage
);

Parameters

hPropSheetDlg
Handle to the property sheet.
index
Zero-based index of the page to be removed.
hpage
Handle to the page to be removed.

Return Values

No return value.

Remarks

An application can specify the page to be removed by assigning a value to either index or hpage. If values are assigned to both index and hpage, hpage takes precedence.

A number of messages and one function call occur while the property sheet is manipulating the list of pages. While this action is taking place, attempting to modify the list of pages will have unpredictable results. Accordingly, you should not use the PropSheet_RemovePage macro in your implementation of PropSheetPageProc or while handling the following notifications and Microsoft® Windows® messages:

  • PSN_APPLY
  • PSN_KILLACTIVE
  • PSN_RESET
  • PSN_SETACTIVE
  • WM_DESTROY
  • WM_INITDIALOG

If the need to modify a property sheet page arises while you are handling one of these messages or while PropSheetPageProc is in operation, post yourself a private Windows message. Your application will not receive that message until after the property sheet manager has finished its tasks. It will then be safe to modify the list of pages.

The following notifications are also affected by property sheet modification.

  • PSN_WIZBACK
  • PSN_WIZNEXT

You can add or remove pages in response to these notifications, provided that you return (via DWL_MSGRESULT) a nonzero value to specify the desired new page. Note, however, that if you remove a page that is located before the current page (that has a smaller index than the current page), PSN_KILLACTIVE might be sent to the wrong page.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_RestartWindows

Sends a PSM_RESTARTWINDOWS message indicating that Windows needs to be restarted for changes to take effect. You can use this macro or send the PSM_RESTARTWINDOWS message explicitly.

VOID PropSheet_RestartWindows(
    HWND hPropSheetDlg
);

Parameters

hPropSheetDlg
Handle to the property sheet.

Return Values

No return value.

Remarks

An application should send the PSM_RESTARTWINDOWS message only in response to the PSN_APPLY or PSN_KILLACTIVE notification message.

The PSM_RESTARTWINDOWS message causes the PropertySheet function to return the ID_PSRESTARTWINDOWS value, but only if the user clicks the OK button to close the property sheet. It is the application's responsibility to restart Windows, which can be done by using the ExitWindowsEx function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_SetCurSel

Activates the specified page in a property sheet. You can use this macro or send the PSM_SETCURSEL message explicitly.

BOOL PropSheet_SetCurSel(
    HWND hPropSheetDlg,
    HPROPSHEETPAGE hpage,
    int index
);

Parameters

hPropSheetDlg
Handle to the property sheet.
index and hpage
Zero-based index of the page and the handle to the page to activate, respectively. An application can specify the index or the handle, or both. If both are specified, hpage takes precedence.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_SetCurSelByID

Activates the specified page in a property sheet based on the resource identifier of the page. You can use this macro or send the PSM_SETCURSELID message explicitly.

BOOL PropSheet_SetCurSelByID(
    HWND hPropSheetDlg,
    int id
);

Parameters

hPropSheetDlg
Handle to the property sheet.
id
Resource identifier of the page to activate.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The window that is losing the activation receives the PSN_KILLACTIVE notification message, and the window that is gaining the activation receives the PSN_SETACTIVE notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_SetFinishText

Sets the text of the Finish button in a wizard, shows and enables the button, and hides the Next and Back buttons. You can use this macro or send the PSM_SETFINISHTEXT message explicitly.

VOID PropSheet_SetFinishText(
    HWND hPropSheetDlg,
    LPTSTR lpszText
);

Parameters

hPropSheetDlg
Window handle (HWND) of the wizard property sheet.
lpszText
Pointer to the new text for the Finish button.

Return Values

No return value.

Remarks

By default, the Finish button does not have a keyboard accelerator. You can create a keyboard accelerator with this macro by including an ampersand (&) in the text string that you assign to lpszText. For example, "&Finish" defines F as the accelerator key.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_SetHeaderSubTitle

Sets the subtitle text for the header of a wizard's interior page. You can use this macro or send the PSM_SETHEADERSUBTITLE message explicitly.

VOID PropSheet_SetHeaderSubTitle(
  HWND hWizardDlg,
  int iPageIndex,
  LPCSTR pszHeaderSubTitle
);

Parameters

hWizardDlg
Handle to the wizard's window.
iPageIndex
Zero-based index of the page.
pszHeaderSubTitle
New header subtitle.

Return Values

No return value.

Remarks

If you specify the current page, it will immediately be repainted to display the new subtitle.

See Also

PropSheet_HwndToIndex, PropSheet_IdToIndex, PropSheet_PageToIndex

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_SetHeaderTitle

Sets the title text for the header of a wizard's interior page. You can use this macro or send the PSM_SETHEADERTITLE message explicitly.

int PropSheet_SetHeaderTitle(
  HWND hWizardDlg,
  int iPageIndex,
  LPCSTR pszHeaderTitle
);

Parameters

hWizardDlg
Handle to the wizard's window.
iPageIndex
Zero-based index of the page.
pszHeaderTitle
New header title.

Return Values

No return value.

Remarks

If you specify the current page, it will immediately be repainted to display the new title.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in prsht.h.


PropSheet_SetTitle

Sets the title of a property sheet. You can use this macro or send the PSM_SETTITLE message explicitly.

VOID PropSheet_SetTitle(
    HWND hPropSheetDlg,
    DWORD dwStyle,
    LPTSTR lpszText
);

Parameters

hPropSheetDlg
Handle to the property sheet.
dwStyle
Flag that indicates whether to include the prefix "Properties for" with the specified title string. If dwStyle is the PSH_PROPTITLE value, the prefix is included. Otherwise, the prefix is not used.
lpszText
Address of a buffer that contains the title string. If the high-order word of this parameter is NULL, the property sheet loads the string resource specified in the low-order word.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PropSheet_SetWizButtons

Enables or disables the Back, Next, and Finish buttons in a wizard by posting a PSM_SETWIZBUTTONS message. You can use this macro or send the PSM_SETWIZBUTTONS message explicitly.

VOID PropSheet_SetWizButtons(
    HWND  hPropSheetDlg,
    DWORD dwFlags
);

Parameters

hPropSheetDlg
Handle to the property sheet.
dwFlags
A value that specifies which wizard buttons are enabled. You can combine one or more of the following flags.
PSWIZB_BACK | Enable the Back button. If this flag is not set, the Back button is displayed as disabled.
PSWIZB_DISABLEDFINISH | Display a disabled Finish button.
PSWIZB_FINISH | Display an enabled Finish button.
PSWIZB_NEXT | Enable the Next button. If this flag is not set, the Next button is displayed as disabled.

Return Values

No return value.

Remarks

This macro uses PostMessage to send the PSM_SETWIZBUTTONS message. If your notification handler calls PropSheet_SetWizButtons, do nothing that will affect window focus until after the handler returns. For example, if you call MessageBox immediately after calling PropSheet_SetWizButtons, the message box will receive focus. Since messages sent with PostMessage are not delivered until they reach the head of the message queue, the PSM_SETWIZBUTTONS message will not be delivered until after the wizard has lost focus to the message box. As a result, the property sheet will not be able to properly set the focus for the buttons.

Wizards display either three or four buttons below each page. This message is used to specify which buttons are enabled. Wizards normally display Back, Cancel, and either a Next or Finish button. You typically enable only the Next button for the welcome page, Next and Back for interior pages, and Back and Finish for the completion page. The Cancel button is always enabled. Normally, setting PSWIZB_FINISH or PSWIZB_DISABLEDFINISH replaces the Next button with a Finish button. To display Next and Finish buttons simultaneously, set the PSH_WIZARDHASFINISH FLAG in the dwFlags member of the wizard's PROPSHEETHEADER structure when you create the wizard. Every page will then display all four buttons.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PropSheet_UnChanged

Informs a property sheet that information in a page has reverted to the previously saved state. You can use this macro or send the PSM_UNCHANGED message explicitly.

VOID PropSheet_UnChanged(hPropSheetDlg, hwndPage)
    HWND hPropSheetDlg,
    HWND hwndPage
);

Parameters

hPropSheetDlg
Handle to the property sheet.
hwndPage
Handle to the page that has reverted to the previously saved state.

Return Values

No return value.

Remarks

The property sheet disables the Apply Now button if no other pages have registered changes with the property sheet.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSN_APPLY

Sent to every page in the property sheet to indicate that the user has clicked the OK, Close, or Apply button and wants all changes to take effect. This notification is sent in the form of a WM_NOTIFY message.

PSN_APPLY
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification, including the ID of the page.

Return Values

Set PSNRET_NOERROR to indicate that the changes made to this page are valid and have been applied. If all pages set PSNRET_NOERROR, the property sheet can be destroyed. To indicate that the changes made to this page are invalid and to prevent the property sheet from being destroyed, set one of the following return values:

  • PSNRET_INVALID. The property sheet will not be destroyed, and focus will be returned to this page.
  • PSNRET_INVALID_NOCHANGEPAGE. The property sheet will not be destroyed, and focus will be returned to the page that had focus when the button was pressed.

To set the return value, the dialog box procedure for the page must call the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

Remarks

When the user clicks the OK, Apply, or Close button, the property sheet sends a PSN_KILLACTIVE notification to the active page, giving it an opportunity to validate the user's changes. If the changes are valid, the property sheet sends a PSN_APPLY notification message to each page, directing it to apply the new properties to the corresponding item.

Note: The property sheet is in the process of manipulating the list of pages when the PSN_APPLY notification is sent. Do not attempt to add, remove, or insert pages while handling this notification. Doing so will have unpredictable results.

The lParam member of the PSHNOTIFY structure pointed to by lppsn is set to TRUE if the user clicks the OK button. It is also set to TRUE if the PSM_CANCELTOCLOSE message has been sent and the user clicks the Close button. It is set to FALSE if the user clicks the Apply button.

The PSHNOTIFY structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the handle to the property sheet.

Do not call the EndDialog function when processing this notification.

A modal property sheet is destroyed if the user clicks the OK button and every page returns the PSNRET_NOERROR value in response to PSN_APPLY. If any page returns PSNRET_INVALID or PSNRET_INVALID_NOCHANGEPAGE, the Apply process is cancelled immediately. Pages after the cancelling page will not receive a PSN_APPLY notification.

To receive this notification, a page must set the DWL_MSGRESULT value to FALSE in response to the PSN_KILLACTIVE notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSN_GETOBJECT

Sent by a property sheet to request a drop target object when the cursor passes over one of the tab control's buttons.

PSN_GETOBJECT
    lpnmon = (LPNMOBJECTNOTIFY) lParam;

Parameters

lpnmon
Address of an NMOBJECTNOTIFY structure that, on entry, contains information about the notification. If this notification is processed, you must insert object information into this structure.

Return Values

The application processing this notification must return zero.

Remarks

To provide an object, an application must set values in some members of the NMOBJECTNOTIFY structure at lpnmon. The pObject member must be set to a valid object pointer, and the hResult member must be set to a success flag. To comply with COM standards, always increment the object's reference count when providing an object pointer.

If an application does not provide an object, it must set pObject to NULL and hResult to a failure flag.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


PSN_HELP

Notifies a page that the user has clicked the Help button. This notification message is sent in the form of a WM_NOTIFY message.

PSN_HELP
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the handle to the property sheet. ThelParam member of the PSHNOTIFY structure does not contain any information.

Return Values

No return value.

Remarks

An application should display Help information for the page.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSN_KILLACTIVE

Notifies a page that it is about to lose activation either because another page is being activated or the user has clicked the OK button. This notification message is sent in the form of a WM_NOTIFY message.

PSN_KILLACTIVE
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the handle to the property sheet. The lParam member of the PSHNOTIFY structure does not contain any information.

Return Values

Returns TRUE to prevent the page from losing the activation, or FALSE to allow it.

Remarks

An application handles this notification to validate the information the user has entered.

Note: The property sheet is in the process of manipulating the list of pages when the PSN_KILLACTIVE notification is sent. Do not attempt to add, remove, or insert pages while handling this notification. Doing so will have unpredictable results.

To set a return value, the dialog box procedure for the page must call the SetWindowLong function with a DWL_MSGRESULT value set to the return value. The dialog box procedure must return TRUE.

If the dialog box procedure sets DWL_MSGRESULT to TRUE, it should display a message box to explain the problem to the user.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSN_QUERYCANCEL

Indicates that the user has canceled the property sheet. This notification message is sent in the form of a WM_NOTIFY message.

PSN_QUERYCANCEL
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the property sheet's window handle. The lParam member of the PSHNOTIFY structure does not contain any information.

Return Values

Returns TRUE to prevent the cancel operation, or FALSE to allow it.

Remarks

This message is typically sent when a user clicks the Cancel button. It is also sent when a user clicks the X button in the property sheet's upper right hand corner or presses the ESCAPE key. A property sheet page can handle this notification message to ask the user to verify the cancel operation.

To set a return value, the dialog box procedure for the page must call the SetWindowLong function with DWL_MSGRESULT set to the return value. The dialog box procedure must return TRUE.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSN_QUERYINITIALFOCUS

Sent by a property sheet to provide a property sheet page an opportunity to specify which dialog box control should receive the initial focus. This notification is sent in the form of a WM_NOTIFY message.

PSN_QUERYINITIALFOCUS
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Pointer to a PSHNOTIFY structure. Cast the lParam member of this structure to an HWND type, to retrieve the handle of the control that will be given focus by default. The structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the handle to the property sheet.

Return Values

To specify which control should receive focus, return the control's handle. Otherwise, return zero and focus will go to the default control. To set the return value, the dialog box procedure must call the SetWindowLong function with a DWL_MSGRESULT value and return TRUE.

Example

This code fragment implements a simple handler for PSN_QUERYINITIALFOCUS. It requests that initial focus be given to the Location control (IDC_LOCATION).

case PSN_QUERYINITIALFOCUS :
    SetWindowLong(hDlg,DWL_MSGRESULT, (LPARAM)GetDlgItem(hDlg, IDC_LOCATION));
    return TRUE;
...

Remarks

An application must not call the SetFocus function while handling this notification. Return the handle of the control that should receive focus, and the property sheet manager will handle the focus change.

The PSN_QUERYINITIALFOCUS notification is not sent if the property sheet manager determines that no control on the page should receive focus.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


PSN_RESET

Notifies a page that the property sheet is about to be destroyed. This notification message is sent in the form of a WM_NOTIFY message.

PSN_RESET
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification.

Return Values

No return value.

Remarks

All changes made since the last PSN_APPLY notification are canceled. The lParam member of the PSHNOTIFY structure pointed to by lppsn will be set to TRUE if the user clicked the "X" button in the upper-right corner of the property sheet. It will be FALSE if the user clicked the Cancel button. The PSHNOTIFY structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the handle to the property sheet.

An application can use this notification message as an opportunity to perform cleanup operations.

Note: The property sheet is in the process of manipulating the list of pages when the PSN_RESET notification is sent. Do not attempt to add, remove, or insert pages while handling this notification. Doing so will have unpredictable results.

Do not call the EndDialog function when processing this notification.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSN_SETACTIVE

Notifies a page that it is about to be activated. This notification message is sent in the form of a WM_NOTIFY message.

PSN_SETACTIVE
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of this NMHDR structure contains the handle to the property sheet. The lParam member of the PSHNOTIFY structure does not contain any information.

Return Values

Returns zero to accept the activation, or -1 to activate the next or the previous page (depending on whether the user clicked the Next or Back button). To set the activation to a particular page, return the resource identifier of the page.

Remarks

The PSN_SETACTIVE notification message is sent before the page is visible. An application can use this notification to initialize data in the page.

Note: The property sheet is in the process of manipulating the list of pages when the PSN_SETACTIVE notification is sent. Do not attempt to add, remove, or insert pages while handling this notification. Doing so will have unpredictable results.

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

See also

NMHDR

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSN_TRANSLATEACCELERATOR

Notifies a property sheet that a keyboard message has been received. It provides the page an opportunity to do private keyboard accelerator translation. This notification is sent in the form of a WM_NOTIFY message.

PSN_TRANSLATEACCELERATOR
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
A pointer to a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of the NMHDR structure contains the handle to the property sheet. The lParam member of the PSHNOTIFY structure is a pointer to the message's MSG structure. It can be cast to an LPMSG type, to get access to the parameters of the message to be translated.

Return Values

Return PSNRET_MESSAGEHANDLED to indicate that no further processing is necessary. Return PSNRET_NOERROR to request normal processing.

Remarks

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value. The dialog box procedure must return TRUE.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


PSN_WIZBACK

Notifies a page that the user has clicked the Back button in a wizard. This notification message is sent in the form of a WM_NOTIFY message.

PSN_WIZBACK
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of the NMHDR structure contains the handle to the property sheet. The lParam member of the PSHNOTIFY structure does not contain any information.

Return Values

Return 0 to allow the wizard to go to the previous page. Return -1 to prevent the wizard from changing pages. To display a particular page, return its dialog resource identifier.

Remarks

To set the return value, the dialog box procedure for the page must call the SetWindowLong function with the DWL_MSGRESULT value and return TRUE. For example:

case PSN_WIZBACK :
    SetWindowLong(hDlg, DWL_MSGRESULT, 0);
    break;
case PSN_WIZNEXT :
...

Note The property sheet is in the process of manipulating the list of pages when the PSN_WIZBACK notification is sent. You can add, insert, or remove pages in response to these notifications, but special care must be taken if you insert or remove pages before the current page.

If you insert or remove pages before the current page, you must return (via DWL_MSGRESULT) a nonzero value to specify the desired new page. Note, however, that if you insert or remove a page that is located before the current page (that has a smaller index than the current page), PSN_KILLACTIVE might be sent to the wrong page.

For this reason, it is recommended that wizards that add and remove pages dynamically in response to PSN_WIZNEXT and PSN_WIZBACK do so only to pages at the end of the list. If you want your wizard to safely remove pages dynamically, keep the dynamic pages at the end of the list and jump back to permanent pages before deleting them.

For example, suppose a wizard consists of an introductory page, a series of dynamic pages, and a completion page, and you want to delete the dynamic pages when the user reaches the completion page.

  1. The wizard would begin with two pages, "Introduction" and "Completion." The user begins on the "Introduction" page.
    1. Introduction (User is here)
    2. Completion
  2. When the user navigates away from "Introduction," the wizard adds the dynamic pages and places the user at the first dynamic page by returning (via DWL_MSGRESULT) the dialog identifier of the page "Dynamic 1." In this example, there are three dynamic pages.
    1. Introduction
    2. Completion
    3. Dynamic 1 (User is here)
    4. Dynamic 2
    5. Dynamic 3
  3. After the user navigates through the dynamic pages to "Dynamic 3" and then navigates to the next page, the application should place the user at the page "Completion." Again, this is done by returning (via DWL_MSGRESULT) the dialog identifier of the page "Completion."
    1. Introduction
    2. Completion (User is here)
    3. Dynamic 1
    4. Dynamic 2
    5. Dynamic 3
  4. The application can then remove the three dynamic pages (numbered three through five) safely.
    1. Introduction
    2. Completion (User is here)

Note that this technique is necesary only if your wizard removes pages dynamically. If your wizard only adds pages dynamically, this process is not necessary.

See Also

PSN_WIZNEXT

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSN_WIZFINISH

Notifies a page that the user has clicked the Finish button in a wizard. This notification message is sent in the form of a WM_NOTIFY message.

PSN_WIZFINISH
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. The first member of this structure, hdr, is an NMHDR structure. The hwndFrom member of this NMHDR structure contains the handle to the property sheet. The lParam member of the PSHNOTIFY structure does not contain any information.

Return Values

  • Return TRUE to prevent the wizard from finishing.
  • Version 5.80. Return a window handle to prevent the wizard from finishing. The wizard will set the focus to that window. The window must be owned by the wizard page.
  • Return FALSE to allow the wizard to finish.

Remarks

To set the return value, the dialog box procedure for the page must use the SetWindowLong function with the DWL_MSGRESULT value, and the dialog box procedure must return TRUE.

Version 5.80. If your application returns TRUE to prevent a wizard from finishing, it has no control over which window on the page receives focus. Applications that need to stop a wizard from finishing should normally do so by returning the handle of the window on the wizard page that is to receive focus.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PSN_WIZNEXT

Notifies a page that the user has clicked the Next button in a wizard. This notification message is sent in the form of a WM_NOTIFY message.

PSN_WIZNEXT
    lppsn = (LPPSHNOTIFY) lParam;

Parameters

lppsn
Address of a PSHNOTIFY structure that contains information about the notification. This structure contains an NMHDR structure as its first member, hdr. The hwndFrom member of the NMHDR structure contains the handle to the property sheet. The lParam member of the PSHNOTIFY structure does not contain any information.

Return Values

Return 0 to allow the wizard to go to the next page. Return -1 to prevent the wizard from changing pages. To display a particular page, return its dialog resource identifier.

Remarks

To set the return value, the dialog box procedure for the page must call the SetWindowLong function with the DWL_MSGRESULT value and return TRUE. For example:

case PSN_WIZNEXT :
    SetWindowLong(hDlg, DWL_MSGRESULT, 0);
    break;
case PSN_WIZBACK :
...

Note The property sheet is in the process of manipulating the list of pages when the PSN_WIZNEXT notification is sent. You can add, insert, or remove pages in response to these notifications, but special care must be taken if you insert or remove pages before the current page.

If you insert or remove pages before the current page, you must return (via DWL_MSGRESULT) a nonzero value to specify the desired new page. Note, however, that if you insert or remove a page that is located before the current page (that has a smaller index than the current page), PSN_KILLACTIVE might be sent to the wrong page.

For this reason, it is recommended that wizards that add and remove pages dynamically in response to PSN_WIZNEXT and PSN_WIZBACK do so only to pages at the end of the list. If you want your wizard to safely remove pages dynamically, keep the dynamic pages at the end of the list and jump back to permanent pages before deleting them.

For example, suppose a wizard consists of an introductory page, a series of dynamic pages, and a completion page, and you want to delete the dynamic pages when the user reaches the completion page.

  1. The wizard would begin with two pages, "Introduction" and "Completion." The user begins on the "Introduction" page.
    1. Introduction (User is here)
    2. Completion
  2. When the user navigates away from "Introduction," the wizard adds the dynamic pages and places the user at the first dynamic page by returning (via DWL_MSGRESULT) the dialog identifier of the page "Dynamic 1." In this example, there are three dynamic pages.
    1. Introduction
    2. Completion
    3. Dynamic 1 (User is here)
    4. Dynamic 2
    5. Dynamic 3
  3. After the user navigates through the dynamic pages to "Dynamic 3" and then navigates to the next page, the application should place the user at the page "Completion." Again, this is done by returning (via DWL_MSGRESULT) the dialog identifier of the page "Completion."
    1. Introduction
    2. Completion (User is here)
    3. Dynamic 1
    4. Dynamic 2
    5. Dynamic 3
  4. The application can then remove the three dynamic pages (numbered three through five) safely.
    1. Introduction
    2. Completion (User is here)

Note that this technique is necesary only if your wizard removes pages dynamically. If your wizard only adds pages dynamically, this process is not necessary.

See Also

PSN_WIZBACK

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PROPSHEETHEADER

Defines the frame and pages of a property sheet.

typedef struct _PROPSHEETHEADER {
    DWORD dwSize;
    DWORD dwFlags;
    HWND  hwndParent;
    HINSTANCE hInstance;
    union {
        HICON hIcon;
        LPCTSTR pszIcon;
        };
    LPCTSTR pszCaption;
    UINT nPages;
    union {
        UINT nStartPage;
        LPCTSTR pStartPage;
        };
    union {
        LPCPROPSHEETPAGE ppsp;
        HPROPSHEETPAGE FAR *phpage;
        };
    PFNPROPSHEETCALLBACK pfnCallback;

#if (_WIN32_IE >= 0x0500)
    union {
        HBITMAP hbmWatermark;
        LPCTSTR pszbmWatermark;
        };
    HPALETTE hplWatermark;
    union {
        HBITMAP hbmHeader;
        LPCSTR pszbmHeader;
        };
#endif
} PROPSHEETHEADER, FAR *LPPROPSHEETHEADER;

Members

dwSize
Size, in bytes, of this structure. The property sheet manager uses this member to determine which version of the PROPSHEETHEADER structure you are using. For more information, see the Remarks.
dwFlags
Flags that indicate which options to use when creating the property sheet page. This member can be a combination of the following values:
PSH_DEFAULT
Uses the default meaning for all structure members.
PSH_HASHELP
Permits property sheet pages to display a Help button. You must also set the PSP_HASHELP flag in the page's PROPSHEETPAGE structure when the page is created. If any of the initial property sheet pages enable a Help button, PSH_HASHELP will be set automatically. If none of the initial pages enable a Help button, you must explicitly set PSH_HASHELP if you want to have Help buttons on any pages that might be added later.
PSH_HEADER
Version 5.80. Indicates that a header bitmap will be used with a Wizard97 wizard. You must also set the PSH_WIZARD97 flag. The header bitmap is obtained from the pszbmHeader member, unless the PSH_USEHBMHEADER flag is also set. In that case, the header bitmap is obtained from the hbmHeader member.
PSH_MODELESS
Causes the PropertySheet function to create the property sheet as a modeless dialog box instead of as a modal dialog box. When this flag is set, PropertySheet returns immediately after the dialog box is created, and the return value from PropertySheet is the window handle to the property sheet dialog box.
PSH_NOAPPLYNOW
Removes the Apply button.
PSH_NOCONTEXTHELP
Version 5.80. Removes the context-sensitive Help button ("?"), which is usually present on the caption bar of property sheets. This flag is not valid for wizards. See Property Sheets for a discussion of how to remove the caption bar Help button for earlier versions of the common controls.
PSH_PROPSHEETPAGE
Uses the ppsp member and ignores the phpage member when creating the pages for the property sheet.
PSH_PROPTITLE
Displays the string "Properties for", followed by the string specified by the pszCaption member, in the title bar of the property sheet.
PSH_RTLREADING
Reverses the direction in which pszCaption is displayed. Normal windows display all text, including pszCaption, left-to-right (LTR). For languages such as Hebrew or Arabic that read right-to-left (RTL), a window can be mirrored and all text will be displayed RTL. If PSP_RTLREADING is set, pszCaption will instead read RTL in a normal parent window and LTR in a mirrored parent window.
PSH_STRETCHWATERMARK

Stretches the watermark in Microsoft® Internet Explorer 4.0-compatible Wizard97-style wizards.

Note: This style flag is only included to provide backward compatibility for certain applications. Its use is not recommended, and it is only supported by common controls versions 4.0 and 4.01. With common controls version 5.80 and later, this flag is ignored.

PSH_USECALLBACK
Calls the function specified by the pfnCallback member when initializing the property sheet defined by this structure.
PSH_USEHBMHEADER
Version 5.80. Obtains the header bitmap from the hbmHeader member instead of the pszbmHeader member. You must also set PSH_WIZARD97 and PSH_HEADER.
PSH_USEHBMWATERMARK
Version 5.80. Obtains the watermark bitmap from the hbmWatermark member instead of the pszbmWatermark member. You must also set PSH_WIZARD97 and PSH_WATERMARK.
PSH_USEHICON
Uses hIcon as the small icon in the title bar of the property sheet dialog box.
PSH_USEHPLWATERMARK
Version 5.80. Uses the HPALETTE structure pointed to by the hplWatermark member instead of the default palette to draw the watermark bitmap and/or header bitmap for a Wizard97 wizard. You must also set PSH_WIZARD97, and PSH_WATERMARK or PSH_HEADER.
PSH_USEICONID
Uses pszIcon as the name of the icon resource to load and use as the small icon in the title bar of the property sheet dialog box.
PSH_USEPAGELANG
Version 5.80. Specifies that the language for the property sheet will be taken from the first page's resource.
PSH_USEPSTARTPAGE
Uses the pStartPage member instead of the nStartPage member when displaying the initial page of the property sheet.
PSH_WATERMARK
Version 5.80. Specifies that a watermark bitmap will be used with a Wizard97 wizard. You must also set the PSH_WIZARD97 flag. The watermark bitmap is obtained from the pszbmWatermark member, unless PSH_USEHBMWATERMARK is set. In that case, the header bitmap is obtained from the hbmWatermark member.
PSH_WIZARD
Creates a wizard property sheet.
PSH_WIZARD97
Version 5.80. Creates a Wizard97-style property sheet that allows a header and/or watermark bitmap to be displayed in the background.
PSH_WIZARDCONTEXTHELP
Adds a context-sensitive Help button ("?"), which is usually absent from the caption bar of a wizard. This flag is not valid for regular property sheets.
PSH_WIZARDHASFINISH
Always displays the Finish button on the wizard. You must also set either PSH_WIZARD or PSH_WIZARD97.
PSH_WIZARD_LITE
Version 5.80. Uses the the Wizard-lite style. This style is similar in appearance to PSH_WIZARD97, but it is implemented much like PSH_WIZARD. There are few restrictions on how the pages are formatted. For instance, there are no enforced borders, and the PSH_WIZARD_LITE style does not paint the watermark and header bitmaps for you the way Wizard97 does.
hwndParent
Handle to the property sheet's owner window.
hInstance
Handle to the instance from which to load the icon or title string resource. If the pszIcon or pszCaption member identifies a resource to load, this member must be specified.
hIcon
Handle to the icon to use as the small icon in the title bar of the property sheet dialog box. If the dwFlags member does not include PSH_USEHICON, this member is ignored. This member is declared as a union with pszIcon.
pszIcon
Icon resource to use as the small icon in the title bar of the property sheet dialog box. This member can specify either the identifier of the icon resource or the address of the string that specifies the name of the icon resource. If the dwFlags member does not include PSH_USEICONID, this member is ignored. This member is declared as a union with hIcon.
pszCaption
Title of the property sheet dialog box. This member can specify either the identifier of a string resource or the address of a string that specifies the title. If the dwFlags member includes PSH_PROPTITLE, the string "Properties for" is inserted at the beginning of the title. This field is ignored for wizards.
nPages
Number of elements in the phpage array.
nStartPage
Zero-based index of the initial page that appears when the property sheet dialog box is created. This member is declared as a union with pStartPage.
pStartPage
Name of the initial page that appears when the property sheet dialog box is created. This member can specify either the identifier of a string resource or the address of a string that specifies the name. This member is declared as a union with nStartPage.
ppsp
Address of an array of PROPSHEETPAGE structures that define the pages in the property sheet. If the dwFlags member does not include PSH_PROPSHEETPAGE, this member is ignored. Note that the PROPSHEETPAGE structure is variable in size. Applications that parse the array pointed to by ppsp must take the size of each page into account. This member is declared as a union with phpage.
phpage
Address of an array of handles to the property sheet pages. Each handle must have been created by a previous call to the CreatePropertySheetPage function. If the dwFlags member includes PSH_PROPSHEETPAGE, phpage is ignored and should be set to NULL. When the PropertySheet function returns, any HPROPSHEETPAGE handles in the phpage array will have been destroyed. This member is declared as a union with ppsp.
pfnCallback
Address of an application-defined callback function that is called when the property sheet is initialized. For more information about the callback function, see the description of the PropSheetProc function. If the dwFlags member does not include PSH_USECALLBACK, this member is ignored.
hbmWatermark
Version 5.80. Handle to the watermark bitmap. If the dwFlags member does not include PSH_USEHBMWATERMARK, this member is ignored.
pszbmWatermark
Version 5.80. Bitmap resource to use as the watermark. This member can specify either the identifier of the bitmap resource or the address of the string that specifies the name of the bitmap resource. If the dwFlags member includes PSH_USEHBMWATERMARK, this member is ignored.
hplWatermark
Version 5.80. HPALETTE structure used for drawing the watermark bitmap and/or header bitmap. If the dwFlags member does not include PSH_USEHPLWATERMARK, this member is ignored.
hbmHeader
Version 5.80. Handle to the header bitmap. If the dwFlags member does not include PSH_USEHBMHEADER, this member is ignored.
pszbmHeader
Version 5.80. Bitmap resource to use as the header. This member can specify either the identifier of the bitmap resource or the address of the string that specifies the name of the bitmap resource. If the dwFlags member includes PSH_USEHBMHEADER, this member is ignored.

Remarks

If the user chooses a setting such as Large Fonts, which enlarges the dialog box, the watermark that is painted on the start and finish pages will be enlarged as well. The size and position of the original bitmap will remain the same. The additional area will be filled with the color of the pixel in the upper-left corner of the bitmap.

Note that several members of this structure are only supported for Comctl32.dll versions 4.71 and later. You can enable these members by including one of the following in your header:

#define _WIN32_IE 0x0400 // For version 4.71

or

#define _WIN32_IE 0x0500 // For version 5.80

However, you must initialize the structure with its size. If you use the size of the currently defined structure, the application may not run with the earlier versions of Comctl32.dll, which expect a smaller structure. This includes all systems with Microsoft® Windows® 95 or Microsoft® Windows NT® 4.0 that do not have Internet Explorer version 4.0 or later installed. You can run your application on pre-4.71 versions of Comctl32.dll by defining the appropriate version number. However, this may cause problems if your application also needs to run on systems with more recent versions.

You can remain compatible with all Comctl32.dll versions by using the current header files and setting the size of the PROPSHEETHEADER structure appropriately. Before you initialize the structure, use the DllGetVersion function to determine which Comctl32.dll version is installed on the system. If it is version 4.71 or greater, use:

psh.dwSize = sizeof(PROPSHEETHEADER);

to initialize the dwSize member. For earlier versions, the size of the pre-4.71 structure is given by the PROPSHEETHEADER_V1_SIZE constant. Use:

psh.dwSize = PROPSHEETHEADER_V1_SIZE;

The three wizard styles, PSH_WIZARD, PSH_WIZARD97, and PSH_WIZARD_LITE, are mutually incompatible. Only one of these style flags should be set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in prsht.h.


PROPSHEETPAGE

This structure defines a page in a property sheet.

typedef struct _PROPSHEETPAGE {
    DWORD dwSize;
    DWORD dwFlags;
    HINSTANCE hInstance;
    union {
        LPCSTR pszTemplate;
        LPCDLGTEMPLATE pResource;
        };
    union {
        HICON hIcon;
        LPCSTR pszIcon;
        };
    LPCSTR pszTitle;
    DLGPROC pfnDlgProc;
    LPARAM lParam;
    LPFNPSPCALLBACK pfnCallback;
    UINT FAR * pcRefParent;

#if (_WIN32_IE >= 0x0500)
    LPCTSTR pszHeaderTitle;
    LPCTSTR pszHeaderSubTitle;
#endif
#if (_WIN32_WINNT >= 0x0501)
    HANDLE           hActCtx;
#endif
} PROPSHEETPAGE, FAR *LPPROPSHEETPAGE;

Members

dwSize
Size, in bytes, of this structure. The property sheet manager uses this member to determine which version of the PROPSHEETHEADER structure you are using.
dwFlags
Flags that indicate which options to use when creating the property sheet page. This member can be a combination of the following values:
PSP_DEFAULT
Uses the default meaning for all structure members.
PSP_DLGINDIRECT
Creates the page from the dialog box template in memory pointed to by the pResource member. The PropertySheet function assumes that the template that is in memory is not write-protected. A read-only template will cause an exception in some versions of Microsoft® Windows®.
PSP_HASHELP
Enables the property sheet Help button when the page is active.
PSP_HIDEHEADER
Version 5.80. Causes the wizard property sheet to hide the header area when the page is selected. If a watermark has been provided, it will be painted on the left side of the page. This flag should be set for welcome and completion pages, and omitted for interior pages.
PSP_PREMATURE
Version 4.71. Causes the page to be created when the property sheet is created. If this flag is not specified, the page will not be created until it is selected the first time.
PSP_RTLREADING
Reverses the direction in which pszTitle is displayed. Normal windows display all text, including pszTitle, left-to-right (LTR). For languages such as Hebrew or Arabic, that read right-to-left (RTL), a window can be mirrored and all text will be displayed RTL. If PSP_RTLREADING is set, pszTitle will instead read RTL in a normal parent window, and LTR in a mirrored parent window.
PSP_USECALLBACK
Calls the function specified by the pfnCallback member when creating or destroying the property sheet page defined by this structure.
PSP_USEFUSIONCONTEXT
Version 6.0. Use an activation context. To use an activation context, you must set this flag and assign the activation context handle to hActCtx.
PSP_USEHEADERSUBTITLE
Version 5.80. Displays the string pointed to by the pszHeaderSubTitle member as the subtitle of the header area of a Wizard97 page. To use this flag, you must also set the PSH_WIZARD97 flag in the dwFlags member of the associated PROPSHEETHEADER structure. The PSP_USEHEADERSUBTITLE flag is ignored if PSP_HIDEHEADER is set.
PSP_USEHEADERTITLE
Version 5.80. Displays the string pointed to by the pszHeaderTitle member as the title in the header of a Wizard97 interior page. You must also set the PSH_WIZARD97 flag in the dwFlags member of the associated PROPSHEETHEADER structure. The PSP_USEHEADERTITLE flag is ignored if PSP_HIDEHEADER is set.
PSP_USEHICON
Uses hIcon as the small icon on the tab for the page.
PSP_USEICONID
Uses pszIcon as the name of the icon resource to load and use as the small icon on the tab for the page.
PSP_USEREFPARENT
Maintains the reference count specified by the pcRefParent member for the lifetime of the property sheet page created from this structure.
PSP_USETITLE
Uses the pszTitle member as the title of the property sheet dialog box instead of the title stored in the dialog box template.
hInstance
Handle to the instance from which to load an icon or string resource. If the pszIcon, pszTitle pszHeaderTitle, or pszHeaderSubTitle members identifies a resource to load, hInstance must be specified.
pszTemplate
Dialog box template to use to create the page. This member can specify either the resource identifier of the template or the address of a string that specifies the name of the template. If the PSP_DLGINDIRECT flag in the dwFlags member is set, pszTemplate is ignored. This member is declared as a union with pResource.
pResource
Address of a dialog box template in memory. The PropertySheet function assumes that the template is not write-protected. A read-only template will cause an exception in some versions of Windows. To use this member, you must set the PSP_DLGINDIRECT flag in the dwFlags member. This member is declared as a union with pszTemplate.
hIcon
Handle to the icon to use as the icon in the tab of the page. If the dwFlags member does not include PSP_USEHICON, this member is ignored. This member is declared as a union with pszIcon.
pszIcon
Icon resource to use as the icon in the tab of the page. This member can specify either the identifier of the icon resource or the address of the string that specifies the name of the icon resource. To use this member, you must set the PSP_USEICONID flag in the dwFlags member. This member is declared as a union with hIcon.
pszTitle
Title of the property sheet dialog box. This title overrides the title specified in the dialog box template. This member can specify either the identifier of a string resource or the address of a string that specifies the title. To use this member, you must set the PSP_USETITLE flag in the dwFlags member.
pfnDlgProc
Address of the dialog box procedure for the page. Because the pages are created as modeless dialog boxes, the dialog box procedure must not call the EndDialog function.
lParam
When the page is created, a copy of the page's PROPSHEETPAGE structure is passed to the dialog box procedure with a WM_INITDIALOG message. The lParam member is provided to allow you to pass application-specific information to the dialog box procedure. It has no effect on the page itself. For more information, see Property Sheet Creation.
pfnCallback
Address of an application-defined callback function that is called when the page is created and when it is about to be destroyed. For more information about the callback function, see PropSheetPageProc. To use this member, you must set the PSP_USECALLBACK flag in the dwFlags member.
pcRefParent
Address of the reference count value. To use this member, you must set the PSP_USEREFPARENT flag in the dwFlags member.

Note When a property sheet page is created, the value pointed to by pcRefParent is incremented. You create a property sheet page implicitly by setting the PSH_PROPSHEETPAGE flag in the dwFlags member of PROPSHEETHEADER and calling the PropertySheet function. You can do it explicitly by using the CreatePropertySheetPage function. When a property sheet page is destroyed, the value pointed to by the pcRefParent member is decremented. This takes place automatically when the property sheet is destroyed. You can explicitly destroy a property sheet page by using the DestroyPropertySheetPage function.

pszHeaderTitle
Version 5.80. Title of the header area. To use this member, you must:
  • Set the PSP_USEHEADERTITLE flag in the dwFlags member.
  • Set the PSH_WIZARD97 flag in the dwFlags member of the page's PROPSHEETHEADER structure.
  • Make sure that the PSP_HIDEHEADER flag in the dwFlags member is not set.
pszHeaderSubTitle
Version 5.80. Subtitle of the header area. To use this member, you must:
  • Set the PSP_USEHEADERSUBTITLE flag in the dwFlags member.
  • Set the PSH_WIZARD97 flag in the dwFlags member of the page's PROPSHEETHEADER structure.
  • Make sure that the PSP_HIDEHEADER flag in the dwFlags member is not set.
hActCtx
Version 6.0. An activation context handle. Set this member to the handle that is returned when you create the activation context with CreateActCtx. The system will activate this context before creating the dialog box. You do not need to use this member if you use a global manifest.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


PSHNOTIFY

Contains information for the property sheet notification messages.

typedef struct _PSHNOTIFY {
    NMHDR hdr;
    LPARAM lParam;
} PSHNOTIFY, FAR *LPPSHNOTIFY;

Members

hdr
Address of an NMHDR structure that contains additional information about the notification.
lParam
Additional information about this notification. To determine what, if any, information is contained in this member, see the description of the particular notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in prsht.h.


Rebar Controls

Rebar controls act as containers for child windows. An application assigns child windows, which are often other controls, to a rebar control band. Rebar controls contain one or more bands, and each band can have any combination of a gripper bar, a bitmap, a text label, and a child window. However, bands cannot contain more than one child window.

  • About Rebar Controls
  • Using Rebar Controls
  • Rebar Control Reference

    • About Rebar Controls

    A rebar control displays the child window over a specified background bitmap. As you dynamically reposition a rebar control band, the rebar control manages the size and position of the child window assigned to that band.

    The following illustration shows a rebar control that has two bands. One contains a combo box, and the other contains a transparent toolbar control.

    Rebar control with bands containing a combo box and a transparent toolbar control.

    Note The rebar control is implemented in version 4.70 and later of Comctl32.dll.

    Rebar Bands and Child Windows

    An application defines a rebar band's traits by using the RB_INSERTBAND and RB_SETBANDINFO messages. These messages accept the address of a REBARBANDINFO structure as the lParam parameter. The REBARBANDINFO structure members define the traits of a given band. To set a band's traits, set the cbSize member to indicate the size of the structure, in bytes. Then set the fMask member to indicate which structure members your application is filling.

    To assign a child window to a band, include the RBBIM_CHILD flag in the fMask member of the REBARBANDINFO structure, and then set the hwndChild member to the child window's handle. Applications can set the minimum allowable width and height of a child window in the cxMinChild and cyMinChild members.

    When a rebar control is destroyed, it destroys any child windows assigned to the bands within it. To prevent the control from destroying child windows assigned to its bands, remove the bands by sending the RB_DELETEBAND message, and then reset the parent to another window with the SetParent function before destroying the rebar control.

    The Rebar Control User Interface

    All rebar control bands can be resized, except those that use the RBBS_FIXEDSIZE style. To resize or change the order of bands within the control, click and drag a band's gripper bar. The rebar control automatically resizes and repositions child windows assigned to its bands. Additionally, you can toggle the size of a band by clicking the band text, if there is any.

    The Rebar Control's Image List

    If an application is using an image list with a rebar control, it must send the RB_SETBARINFO message before adding bands to the control. This message accepts the address of a REBARINFO structure as the lParam parameter. Before sending the message, prepare the REBARINFO structure by setting the cbSize member to the size of the structure, in bytes. Then, if the rebar control is going to display images on the bands, set the fMask member to the RBIM_IMAGELIST flag and assign an image list handle to the himl member. If the rebar will not use band images, set fMask to zero.

    Rebar Control Message Forwarding

    A rebar control forwards all WM_NOTIFY window messages to its parent window. Additionally, a rebar control forwards any messages sent to it from windows assigned to its bands, like WM_CHARTOITEM, WM_COMMAND, and others.

    Custom Draw Support

    Rebar controls support custom draw functionality. For more information, see About Custom Draw.

    Using Rebar Controls

    This section gives sample code that demonstrates how to implement a rebar control.

    Creating a Rebar Control

    An application creates a rebar control by calling the CreateWindowEx function, specifying REBARCLASSNAME as the window class. The application must first register the window class by calling the InitCommonControlsEx function, while specifying the ICC_COOL_CLASSES bit in the accompanying INITCOMMONCONTROLSEX structure.

    The following sample creates a rebar control with two bands—one that contains a combo box and another that contains a toolbar. The sample includes the RBS_VARHEIGHT style to allow the control to use variable band height. After creating the rebar control, CreateRebar creates the child windows with calls to two application-defined functions, CreateComboBox and CreateToolbar. Before adding each band, CreateRebar initializes the cbSize member of the REBARBANDINFO structure, as required by the RB_INSERTBAND message. Then it sets the value of the structure's fMask member to reflect which members contain valid data. CreateRebar sets the cyMinChild member for each band to allow for the height of the control within it. The cxMinChild member is zero to allow the user to completely hide the control within a given band.

    HWND WINAPI CreateRebar(HWND hwndOwner)
{
   REBARINFO     rbi;
   REBARBANDINFO rbBand;
   RECT          rc;
   HWND   hwndCB, hwndTB, hwndRB;
   DWORD  dwBtnSize;
   INITCOMMONCONTROLSEX icex;

   icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
   icex.dwICC   = ICC_COOL_CLASSES|ICC_BAR_CLASSES;
   InitCommonControlsEx(&icex);

   hwndRB = CreateWindowEx(WS_EX_TOOLWINDOW,
                           REBARCLASSNAME,
                           NULL,
                           WS_CHILD|WS_VISIBLE|WS_CLIPSIBLINGS|
                           WS_CLIPCHILDREN|RBS_VARHEIGHT|CCS_NODIVIDER,
                           0,0,0,0,
                           hwndOwner,
                           NULL,
                           g_hinst,
                           NULL);
   if(!hwndRB)
      return NULL;

   // Initialize and send the REBARINFO structure.
   rbi.cbSize = sizeof(REBARINFO);  // Required when using this struct.
   rbi.fMask  = 0;
   rbi.himl   = (HIMAGELIST)NULL;
   if(!SendMessage(hwndRB, RB_SETBARINFO, 0, (LPARAM)&rbi))
      return NULL;

   // Initialize structure members that both bands will share.
   rbBand.cbSize = sizeof(REBARBANDINFO);  // Required
   rbBand.fMask  = RBBIM_COLORS | RBBIM_TEXT | RBBIM_BACKGROUND |
                   RBBIM_STYLE | RBBIM_CHILD  | RBBIM_CHILDSIZE |
                   RBBIM_SIZE;
   rbBand.fStyle = RBBS_CHILDEDGE | RBBS_FIXEDBMP;
   rbBand.hbmBack= LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_BACKGRND));

   // Create the combo box control to be added.
   hwndCB = CreateComboBox(hwndRB);

   // Set values unique to the band with the combo box.
   GetWindowRect(hwndCB, &rc);
   rbBand.lpText     = "Combo Box";
   rbBand.hwndChild  = hwndCB;
   rbBand.cxMinChild = 0;
   rbBand.cyMinChild = rc.bottom - rc.top;
   rbBand.cx         = 200;

   // Add the band that has the combo box.
   SendMessage(hwndRB, RB_INSERTBAND, (WPARAM)-1, (LPARAM)&rbBand);

   // Create the toolbar control to be added.
   hwndTB = CreateToolbar(hwndOwner, dwStyle);

   // Get the height of the toolbar.
   dwBtnSize = SendMessage(hwndTB, TB_GETBUTTONSIZE, 0,0);

   // Set values unique to the band with the toolbar.
   rbBand.lpText     = "Tool Bar";
   rbBand.hwndChild  = hwndTB;
   rbBand.cxMinChild = 0;
   rbBand.cyMinChild = HIWORD(dwBtnSize);
   rbBand.cx         = 250;

   // Add the band that has the toolbar.
   SendMessage(hwndRB, RB_INSERTBAND, (WPARAM)-1, (LPARAM)&rbBand);

   return (hwndRB);
}


Rebar Control Styles

Rebar controls support a variety of control styles in addition to standard window styles.
RBS_AUTOSIZE | Version 4.71. The rebar control will automatically change the layout of the bands when the size or position of the control changes. An RBN_AUTOSIZE notification will be sent when this occurs.
RBS_BANDBORDERS | Version 4.70. The rebar control displays narrow lines to separate adjacent bands.
RBS_DBLCLKTOGGLE | Version 4.71. The rebar band will toggle its maximized or minimized state when the user double-clicks the band. Without this style, the maximized or minimized state is toggled when the user single-clicks on the band.
RBS_FIXEDORDER | Version 4.70. The rebar control always displays bands in the same order. You can move bands to different rows, but the band order is static.
RBS_REGISTERDROP | Version 4.71. The rebar control generates RBN_GETOBJECT notification messages when an object is dragged over a band in the control. To receive the RBN_GETOBJECT notifications, initialize OLE with a call to OleInitialize or CoInitialize.
RBS_TOOLTIPS | Version 4.70. Not yet supported.
RBS_VARHEIGHT | Version 4.70. The rebar control displays bands at the minimum required height, when possible. Without this style, the rebar control displays all bands at the same height, using the height of the tallest visible band to determine the height of other bands.
RBS_VERTICALGRIPPER | Version 4.71. The size grip will be displayed vertically instead of horizontally in a vertical rebar control. This style is ignored for rebar controls that do not have the CCS_VERT style.


RB_BEGINDRAG

Puts the rebar control in drag-and-drop mode. This message does not cause a RBN_BEGINDRAG notification to be sent.

RB_BEGINDRAG
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(DWORD)dwPos;

Parameters

uBand
Zero-based index of the band that the drag-and-drop operation will affect.
dwPos
DWORD value that contains the starting mouse coordinates. The horizontal coordinate is contained in the LOWORD and the vertical coordinate is contained in the HIWORD. If you pass (DWORD)-1, the rebar control will use the position of the mouse the last time the control's thread called GetMessage or PeekMessage.

Return Values

The return value for this message is not used.

Remarks

The RB_BEGINDRAG, RB_DRAGMOVE, and RB_ENDDRAG messages allow you to implement an IDropTarget interface for a rebar control. You send the RB_BEGINDRAG message in response to IDropTarget::DragEnter, send the RB_DRAGMOVE message in response to IDropTarget::DragOver, and the RB_ENDDRAG message in response to IDropTarget::Drop and IDropTarget::DragLeave.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_DELETEBAND

Deletes a band from a rebar control.

RB_DELETEBAND
    wParam = (WPARAM)(UINT) uBand;
    lParam = 0;

Parameters

uBand
Zero-based index of the band to be deleted.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_DRAGMOVE

Updates the drag position in the rebar control after a previous RB_BEGINDRAG message.

RB_DRAGMOVE
    wParam = 0;
    lParam = (LPARAM)(DWORD)dwPos;

Parameters

dwPos
DWORD value that contains the new mouse coordinates. The horizontal coordinate is contained in the LOWORD and the vertical coordinate is contained in the HIWORD. If you pass (DWORD)-1, the rebar control will use the position of the mouse the last time the control's thread called GetMessage or PeekMessage.

Return Values

The return value for this message is not used.

See Also

RB_ENDDRAG

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_ENDDRAG

Terminates the rebar control's drag-and-drop operation. This message does not cause an RBN_ENDDRAG notification to be sent.

RB_ENDDRAG
    wParam = 0;
    lParam = 0;

Return Values

The return value for this message is not used.

See Also

RB_BEGINDRAG, RB_DRAGMOVE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETBANDBORDERS

Retrieves the borders of a band. The result of this message can be used to calculate the usable area in a band.

RB_GETBANDBORDERS
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

uBand
Zero-based index of the band for which the borders will be retrieved.
lprc
Address of a RECT structure that will receive the band borders. If the rebar control has the RBS_BANDBORDERS style, each member of this structure will receive the number of pixels, on the corresponding side of the band, that constitute the border. If the rebar control does not have the RBS_BANDBORDERS style, only the left member of this structure receives valid information.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETBANDCOUNT

Retrieves the count of bands currently in the rebar control.

RB_GETBANDCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns a UINT value that represents the number of bands assigned to the control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_GETBANDINFO

Retrieves information about a specified band in a rebar control.

RB_GETBANDINFO
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;

Parameters

uBand
Zero-based index of the band for which the information will be retrieved.
lprbbi
Address of a REBARBANDINFO structure that will receive the requested band information. Before sending this message, you must set the cbSize member of this structure to the size of the REBARBANDINFO structure and set the fMask parameter to the items you want to retrieve. Additionally, you must set the cch member of the REBARBANDINFO structure to the size of the lpText buffer when RBBIM_TEXT is specified.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

RB_SETBANDINFO

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_GETBARHEIGHT

Retrieves the height of the rebar control.

RB_GETBARHEIGHT
    wParam = 0;
    lParam = 0;

Return Values

Returns a UINT value that represents the height, in pixels, of the control.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETBARINFO

Retrieves information about the rebar control and the image list it uses.

RB_GETBARINFO
    wParam = 0;
    lParam = (LPARAM)(LPREBARINFO) lprbi;

Parameters

lprbi
Address of a REBARINFO structure that will receive the rebar control information. You must set the cbSize member of this structure to sizeof(REBARINFO) before sending this message.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_GETBKCOLOR

Retrieves a rebar control's default background color.

RB_GETBKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that represent the current default background color.

See Also

RB_SETBKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETCOLORSCHEME

Retrieves the color scheme information from the rebar control.

RB_GETCOLORSCHEME
    wParam = 0;
    lParam = (LPARAM)(LPCOLORSCHEME) lpcs;

Parameters

lpcs
Address of a COLORSCHEME structure that will receive the color scheme information. You must set the dwSize member of this structure to sizeof(COLORSCHEME) before sending this message.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

RB_SETCOLORSCHEME

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETDROPTARGET

Retrieves a rebar control's IDropTarget interface pointer.

RB_GETDROPTARGET
    wParam = 0;
    lParam = (IDropTarget**)ppDropTarget;

Parameters

ppDropTarget
Address of an IDropTarget pointer that receives the interface pointer.
It is the caller's responsibility to call Release on this pointer when it is no longer needed.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETPALETTE

Retrieves the rebar control's current palette.

RB_GETPALETTE
    wParam = 0;
    lParam = 0;

Return Values

Returns an HPALETTE that specifies the rebar control's current palette.

See Also

RB_SETPALETTE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETRECT

Retrieves the bounding rectangle for a given band in a rebar control.

RB_GETRECT
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

uBand
Zero-based index of a band in the rebar control.
lprc
Address of a RECT structure that will receive the bounds of the rebar band.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETROWCOUNT

Retrieves the number of rows of bands in a rebar control.

RB_GETROWCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns a UINT value that represents the number of band rows in the control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_GETROWHEIGHT

Retrieves the height of a specified row in a rebar control.

RB_GETROWHEIGHT
    wParam = (WPARAM)(UINT) uBand;
    lParam = 0;

Parameters

uBand
Zero-based index of a band. The height of the row that contains the specified band will be retrieved.

Return Values

Returns a UINT value that represents the row height, in pixels.

Remarks

To retrieve the number of rows in a rebar control, use the RB_GETROWCOUNT message.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_GETTEXTCOLOR

Retrieves a rebar control's default text color.

RB_GETTEXTCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that represent the current default text color.

See Also

RB_SETTEXTCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETTOOLTIPS

Retrieves the handle to any ToolTip control associated with the rebar control.

RB_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Return Values

Returns an HWND value that is the handle to the ToolTip control associated with the rebar control, or zero if no ToolTip control is associated with the rebar control.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control.

RB_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

RB_SETUNICODEFORMAT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_HITTEST

Determines which portion of a rebar band is at a given point on the screen, if a rebar band exists at that point.

RB_HITTEST
    wParam = 0;
    lParam = (LPARAM)(LPRBHITTESTINFO) lprbht;

Parameters

lprbht
Address of an RBHITTESTINFO structure. Before sending the message, the pt member of this structure must be initialized to the point that will be hit tested, in client coordinates.

Return Values

Returns the zero-based index of the band at the given point, or -1 if no rebar band was at the point.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_IDTOINDEX

Converts a band identifier to a band index in a rebar control.

RB_IDTOINDEX
    wParam = (WPARAM)(UINT) uBandID;
    lParam = 0;

Parameters

uBandID
The application-defined identifier of the band in question. This is the value that was passed in the wID member of the REBARBANDINFO structure when the band was inserted.

Return Values

Returns the zero-based band index if successful, or -1 otherwise. If duplicate band identifiers exist, the first one is returned.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_INSERTBAND

Inserts a new band in a rebar control.

RB_INSERTBAND
    wParam = (WPARAM)(UINT) uIndex;
    lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;

Parameters

uIndex
Zero-based index of the location where the band will be inserted. If you set this parameter to -1, the control will add the new band at the last location.
lprbbi
Address of a REBARBANDINFO structure that defines the band to be inserted. You must set the cbSize member of this structure to sizeof(REBARBANDINFO) before sending this message.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_MAXIMIZEBAND

Resizes a band in a rebar control to either its ideal or largest size.

RB_MAXIMIZEBAND
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(BOOL) fIdeal;

Parameters

uBand
Zero-based index of the band to be maximized.
fIdeal
Indicates if the ideal width of the band should be used when the band is maximized. If this value is nonzero, the ideal width will be used. If this value is zero, the band will be made as large as possible.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_MINIMIZEBAND

Resizes a band in a rebar control to its smallest size.

RB_MINIMIZEBAND
    wParam = (WPARAM)(UINT) uBand;
    lParam = 0;

Parameters

uBand
Zero-based index of the band to be minimized.

Return Values

The return value is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_MOVEBAND

Moves a band from one index to another.

RB_MOVEBAND
    wParam = (WPARAM)(UINT) iFrom;
    lParam = (LPARAM)(UINT) iTo;

Parameters

iFrom
Zero-based index of the band to be moved.
iTo
Zero-based index of the new band position.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

This message will most likely change the index of other bands in the rebar control. If a band is moved from index 6 to index 0, all of the bands in between will have their index incremented by one.

iTo must never be greater than the number of bands minus one. The number of bands can be obtained with the RB_GETBANDCOUNT message.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_PUSHCHEVRON

Sent to a rebar control to programmatically push a chevron.

RB_PUSHCHEVRON
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM) lAppValue;

Parameters

uBand
Zero-based index of the band whose chevron is to be pushed.
lAppValue
An application defined 32-bit value. It will be passed back to the application as the lParamNM member of the NMREBARCHEVRON structure that is passed with the RBN_CHEVRONPUSHED notification.

Return Values

The return value for this notification is not used.

Remarks

When this message is sent, the rebar control will send the application an RBN_CHEVRONPUSHED notification, prompting it to display the chevron menu.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 or Windows NT 4 with Internet Explorer 5 or later.
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


RB_SETBANDINFO

Sets characteristics of an existing band in a rebar control.

RB_SETBANDINFO
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(LPREBARBANDINFO) lprbbi;

Parameters

uBand
Zero-based index of the band to receive the new settings.
lprbbi
Address of a REBARBANDINFO structure that defines the band to be modified and the new settings. Before sending this message, you must set the cbSize member of this structure to the sizeof(REBARBANDINFO) structure. Additionally, you must set the cch member of the REBARBANDINFO structure to the size of the lpText buffer when RBBIM_TEXT is specified.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_SETBARINFO

Sets the characteristics of a rebar control.

RB_SETBARINFO
    wParam = 0;
    lParam = (LPARAM)(LPREBARINFO) lprbi;

Parameters

lprbi
Address of a REBARINFO structure that contains the information to be set. You must set the cbSize member of this structure to sizeof(REBARINFO) before sending this message.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_SETBKCOLOR

Sets a rebar control's default background color.

RB_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBk;

Parameters

clrBk
COLORREF value that represents the new default background color.

Return Values

Returns a COLORREF value that represents the previous default background color.

Remarks

The rebar control's default background color is used to draw the background in a rebar control and all bands that are added after this message has been sent. The default background color for a particular band can be overridden when a band is added or modified by setting the RBBIM_COLORS flag in fMask and setting clrBack in the REBARBANDINFO structure.

See Also

RB_GETBKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SETCOLORSCHEME

Sets the color scheme information for the rebar control.

RB_SETCOLORSCHEME
    wParam = 0;
    lParam = (LPARAM)(LPCOLORSCHEME) lpcs;

Parameters

lpcs
Address of a COLORSCHEME structure that contains the color scheme information.

Return Values

The return value for this message is not used.

Remarks

The rebar control uses the color scheme information when drawing the 3-D elements in the control and bands.

See Also

RB_GETCOLORSCHEME

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SETPALETTE

Sets the rebar control's current palette.

RB_SETPALETTE
    wParam = 0;
    lParam = (LPARAM)(HPALETTE) hpal;

Parameters

hpal
An HPALETTE that specifies the new palette that the rebar control will use.

Return Values

Returns an HPALETTE that specifies the rebar control's previous palette.

Remarks

It is the responsibility of the application sending this message to delete the HPALETTE passed in this message (see DeleteObject). The rebar control will not delete an HPALETTE set with this message.

See Also

RB_GETPALETTE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SETPARENT

Sets a rebar control's parent window.

RB_SETPARENT
    wParam = (WPARAM)(HWND) hwndParent;
    lParam = 0;

Parameters

hwndParent
Handle to the parent window to be set.

Return Values

Returns the handle to the previous parent window, or NULL if there is no previous parent.

Remarks

The rebar control sends notification messages to the window you specify with this message. This message does not actually change the parent of the rebar control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RB_SETTEXTCOLOR

Sets a rebar control's default text color.

RB_SETTEXTCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrText;

Parameters

clrText
COLORREF value that represents the new default text color.

Return Values

Returns a COLORREF value that represents the previous default text color.

Remarks

The rebar control's default text color is used to draw the text in a rebar control and all bands that are added after this message has been sent. The default text color for a particular band can be overridden when a band is added or modified by setting the RBBIM_COLORS flag in fMask and setting clrBack in the REBARBANDINFO structure.

See Also

RB_GETTEXTCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SETTOOLTIPS

Associates a ToolTip control with the rebar control.

RB_SETTOOLTIPS
    wParam = (WPARAM)(HWND) hwndToolTip;
    lParam = 0;

Parameters

hwndToolTip
Handle to the ToolTip control to be set.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

RB_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

RB_GETUNICODEFORMAT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SHOWBAND

Shows or hides a given band in a rebar control.

RB_SHOWBAND
    wParam = (WPARAM)(UINT) uBand;
    lParam = (LPARAM)(BOOL) fShow;

Parameters

uBand
Zero-based index of a band in the rebar control.
fShow
Boolean value that indicates if the band should be shown or hidden. If this value is nonzero, the band will be shown. Otherwise, the band will be hidden.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RB_SIZETORECT

Attempts to find the best layout of the bands for the given rectangle.

RB_SIZETORECT
    wParam = 0;
    lParam = (LPARAM)(LPRECT) prc;

Parameters

prc
Address of a RECT structure that specifies the rectangle to which the rebar control should be sized.

Return Values

Returns nonzero if a layout change occurred, or zero otherwise.

Remarks

The rebar bands will be arranged and wrapped as necessary to fit the rectangle.
Bands that have the RBBS_VARIABLEHEIGHT style will be resized as evenly as possible to fit the rectangle.
The height of a horizontal rebar or the width of a vertical rebar may change, depending on the new layout.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (rebar)

Sent by the rebar control to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Address of an NMCUSTOMDRAW structure that contains information about the drawing operation. The dwItemSpec member of this structure contains the identifier of the band being drawn. The lItemlParam member of this structure contains the lParam of the band being drawn.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:
CDRF_DODEFAULT
The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW
The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE
The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE
The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT
The control will notify the parent after painting an item.
CDRF_NOTIFYSUBITEMDRAW
Version 4.71. The control will notify the parent when a list-view subitem is being drawn.

When dwDrawStage equals CDDS_ITEMPREPAINT:
CDRF_NEWFONT
Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing fonts and colors.
CDRF_SKIPDEFAULT
Your application drew the item manually. The control will not draw the item.

See Also

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_NCHITTEST (rebar)

Sent by a rebar control when the control receives a WM_NCHITTEST message. This notification message is sent in the form of a WM_NOTIFY message.

NM_NCHITTEST
    lpnmmouse = (LPNMMOUSE) lParam;

Parameters

lpnmmouse
Address of an NMMOUSE structure that contains information about the notification. The dwItemSpec member contains the band index over which the hit test message occurred, and the pt member contains the mouse coordinates of the hit test message.

Return Values

Return zero to allow the rebar to perform default processing of the hit test message, or return one of the HT* values documented under WM_NCHITTEST to override the default hit test processing.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (rebar)

Notifies a rebar control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_AUTOSIZE

Sent by a rebar control created with the RBS_AUTOSIZE style when the rebar automatically resizes itself. This notification message is sent in the form of a WM_NOTIFY message.

RBN_AUTOSIZE
    lpnmas = (LPNMRBAUTOSIZE) lParam;

Parameters

lpnmas
Address of an NMRBAUTOSIZE structure that contains information about the resize operation.

Return Values

The return value for this notification is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_BEGINDRAG

Sent by a rebar control when the user begins dragging a band. This notification message is sent in the form of a WM_NOTIFY message.

RBN_BEGINDRAG
    lpnmrb = (LPNMREBAR)lParam;

Parameters

lpnmrb
Address of an NMREBAR structure that contains information about the notification.

Return Values

Return zero to allow the rebar to continue the drag operation, or nonzero to abort the drag operation.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_CHEVRONPUSHED

Sent by a rebar control when a chevron is pushed. This notification message is sent in the form of a WM_NOTIFY message.

RBN_CHEVRONPUSHED
    lpnm = (NMREBARCHEVRON) lParam;

Parameters

lpnm
Pointer to the the band's NMREBARCHEVRON structure.

Return Values

The return value for this notification is not used.

Remarks

When an application receives this notification, it is responsible for displaying a popup menu with items for each hidden tool. Use the rc member of the NMREBARCHEVRON

structure to position the menu.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in commctrl.h.


RBN_CHILDSIZE

Sent by a rebar control when a band's child window is resized. This notification message is sent in the form of a WM_NOTIFY message.

RBN_CHILDSIZE
    lprbcs = (LPNMREBARCHILDSIZE)lParam;

Parameters

lprbcs
Address of an NMREBARCHILDSIZE structure that contains information about the notification.

Return Values

The return value for this notification is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_DELETEDBAND

Sent by a rebar control after a band has been deleted. This notification message is sent in the form of a WM_NOTIFY message.

RBN_DELETEDBAND
    lpnmrb = (LPNMREBAR)lParam;

Parameters

lpnmrb
Address of an NMREBAR structure that contains information about the notification.

Return Values

The return value for this notification is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_DELETINGBAND

Sent by a rebar control when a band is about to be deleted. This notification message is sent in the form of a WM_NOTIFY message.

RBN_DELETINGBAND
    lpnmrb = (LPNMREBAR)lParam;

Parameters

lpnmrb
Address of an NMREBAR structure that contains information about the notification.

Return Values

The return value for this notification is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_ENDDRAG

Sent by a rebar control when the user stops dragging a band. This notification message is sent in the form of a WM_NOTIFY message.

RBN_ENDDRAG
    lpnmrb = (LPNMREBAR)lParam;

Parameters

lpnmrb
Address of an NMREBAR structure that contains information about the notification.

Return Values

The return value for this notification is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_GETOBJECT

Sent by a rebar control created with the RBS_REGISTERDROP style when an object is dragged over a band in the control. This notification message is sent in the form of a WM_NOTIFY message.

RBN_GETOBJECT
    lpnmon = (LPNMOBJECTNOTIFY) lParam;

Parameters

lpnmon
Address of an NMOBJECTNOTIFY structure that contains information about the band that the object is dragged over and also receives the data provided by the receiving application in response to this message.

Return Values

The return value for this notification must be zero.

Remarks

To receive the RBN_GETOBJECT notification, initialize OLE with a call to OleInitialize or CoInitialize.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_HEIGHTCHANGE

Sent by a rebar control when its height has changed. This notification message is sent in the form of a WM_NOTIFY message.

RBN_HEIGHTCHANGE
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.

Remarks

Rebar controls that use the CCS_VERT style send this notification message when their width changes.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


RBN_LAYOUTCHANGED

Sent by a rebar control when the user changes the layout of the control's bands. This notification message is sent in the form of a WM_NOTIFY message.

RBN_LAYOUTCHANGED
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value for this notification is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBN_MINMAX

Sent by a rebar control prior to maximizing or minimizing a band. This notification message is sent in the form of a WM_NOTIFY message.

RBN_MINMAX

Parameters

None

Return Values

Return a non-zero value to prevent the operation from taking place, zero to allow it to continue.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


NMRBAUTOSIZE

Contains information used in handling the RBN_AUTOSIZE notification messages.

typedef struct tagNMRBAUTOSIZE {
    NMHDR hdr;
    BOOL fChanged;
    RECT rcTarget;
    RECT rcActual;
} NMRBAUTOSIZE, *LPNMRBAUTOSIZE;

Members

hdr
NMHDR structure that contains additional information about the notification message.
fChanged
Member that indicates if the size or layout of the rebar control has changed (nonzero if a change occurred or zero otherwise).
rcTarget
RECT structure that contains the rectangle to which the rebar control tried to size itself.
rcActual
RECT structure that contains the rectangle to which the rebar control actually sized itself.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMREBAR

Contains information used in handling various rebar notification messages.

typedef struct tagNMREBAR {
    NMHDR hdr;
    DWORD dwMask;
    UINT uBand;
    UINT fStyle;
    UINT wID;
    LPARAM lParam;
} NMREBAR, *LPNMREBAR;

Members

hdr
NMHDR structure that contains additional information about the notification message.
dwMask
Set of flags that define which members of this structure contain valid information. This can be one or more of the following values:
RBNM_ID | The wID member contains valid information.
RBNM_LPARAM | The lParam member contains valid information.
RBNM_STYLE | The fStyle member contains valid information.
uBand
Zero-based index of the band affected by the notification. This will be -1 if no band is affected.
fStyle
The style of the band. This is one or more of the RBBS_ styles detailed in the fStyle member of the REBARBANDINFO structure. This member is only valid if dwMask contains RBNM_STYLE.
wID
Application-defined identifier of the band. This member is only valid if dwMask contains RBNM_ID.
lParam
Application-defined value associated with the band. This member is only valid if dwMask contains RBNM_LPARAM.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMREBARCHEVRON

Contains information used in handling the RBN_CHEVRONPUSHED notification message.

typedef struct tagNMREBARCHEVRON{
    NMHDR hdr;
    UINT uBand;
    UINT wID;
    LPARAM lParam;
    RECT rc;
    LPARAM lParamNM;
} NMREBARCHEVRON, *LPNMREBARCHEVRON;

Members

hdr
NMHDR structure that contains additional information about the notification message.
uBand
Index of the band sending the notification.
wID
Application-defined identifier for the band.
lParam
Application-defined value associated with the band.
rc
RECT structure that defines the area covered by the chevron.
lParamNM
An application-defined value. If the RBN_CHEVRONPUSHED notification was sent as a result of an RB_PUSHCHEVRON message, this member will contain the message's lAppValue value. Otherwise, it will be set to zero.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in commctrl.h.


NMREBARCHILDSIZE

Contains information used in handling the RBN_CHILDSIZE notification message.

typedef struct tagNMREBARCHILDSIZE{
    NMHDR hdr;
    UINT uBand;
    UINT wID;
    RECT rcChild;
    RECT rcBand;
} NMREBARCHILDSIZE, *LPNMREBARCHILDSIZE;

Members

hdr
NMHDR structure that contains additional information about the notification message.
uBand
Zero-based index of the band affected by the notification. This will be -1 if no band is affected.
wID
Application-defined identifier of the band.
rcChild
RECT structure that contains the new size of the child window. This member can be changed during the notification to modify the child window's position and size.
rcBand
RECT structure that contains the new size of the band.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


RBHITTESTINFO

Contains information specific to a hit test operation. This structure is used with the RB_HITTEST message.

typedef struct _RB_HITTESTINFO {
    POINT pt;
    UINT  flags;
    int   iBand;
} RBHITTESTINFO, FAR *LPRBHITTESTINFO;

Members

pt
POINT structure that describes the point to be hit tested, in client coordinates.
flags
Member that receives a flag value indicating the rebar band's component located at the point described by pt. This member will be one of the following:
RBHT_CAPTION | The point was in the rebar band's caption.
RBHT_CHEVRON | The point was in the rebar band's chevron (version 5.80 and greater).
RBHT_CLIENT | The point was in the rebar band's client area.
RBHT_GRABBER | The point was in the rebar band's gripper.
RBHT_NOWHERE | The point was not in a rebar band.
iBand
Member that receives the rebar band's index at the point described by pt. This value will be the zero-based index of the band, or -1 if no band was at the hit-tested point.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


REBARBANDINFO

Contains information that defines a band in a rebar control.

typedef struct tagREBARBANDINFO{
    UINT        cbSize;
    UINT        fMask;
    UINT        fStyle;
    COLORREF    clrFore;
    COLORREF    clrBack;
    LPTSTR      lpText;
    UINT        cch;
    int         iImage;
    HWND        hwndChild;
    UINT        cxMinChild;
    UINT        cyMinChild;
    UINT        cx;
    HBITMAP     hbmBack;
    UINT        wID;
#if (_WIN32_IE >= 0x0400)
    UINT        cyChild;
    UINT        cyMaxChild;
    UINT        cyIntegral;
    UINT        cxIdeal;
    LPARAM      lParam;
    UINT        cxHeader;
#endif
 } REBARBANDINFO, FAR *LPREBARBANDINFO;

Members

cbSize
Size of this structure, in bytes. Your application must fill this member before sending any messages that use the address of this structure as a parameter.
fMask
Flags that indicate which members of this structure are valid or must be filled. This value can be a combination of the following:
Flag | Description
RBBIM_BACKGROUND | The hbmBack member is valid or must be filled.
RBBIM_CHILD | The hwndChild member is valid or must be filled.
RBBIM_CHILDSIZE | The cxMinChild, cyMinChild, cyChild, cyMaxChild, and cyIntegral members are valid or must be filled.
RBBIM_COLORS | The clrFore and clrBack members are valid or must be filled.
RBBIM_HEADERSIZE | Version 4.71. The cxHeader member is valid or must be filled.
RBBIM_IDEALSIZE | Version 4.71. The cxIdeal member is valid or must be filled.
RBBIM_ID | The wID member is valid or must be filled.
RBBIM_IMAGE | The iImage member is valid or must be filled.
RBBIM_LPARAM | Version 4.71. The lParam member is valid or must be filled.
RBBIM_SIZE | The cx member is valid or must be filled.
RBBIM_STYLE | The fStyle member is valid or must be filled.
RBBIM_TEXT | The lpText member is valid or must be filled.
fStyle
Flags that specify the band style. This value can be a combination of the following:
Flag | Description
RBBS_BREAK | The band is on a new line.
RBBS_CHILDEDGE | The band has an edge at the top and bottom of the child window.
RBBS_FIXEDBMP | The background bitmap does not move when the band is resized.
RBBS_FIXEDSIZE | The band can't be sized. With this style, the sizing grip is not displayed on the band.
RBBS_GRIPPERALWAYS | Version 4.71. The band will always have a sizing grip, even if it is the only band in the rebar.
RBBS_HIDDEN | The band will not be visible.
RBBS_NOGRIPPER | Version 4.71. The band will never have a sizing grip, even if there is more than one band in the rebar.
RBBS_USECHEVRON | Version 5.80. Show a chevron button if the band is smaller than cxIdeal.
RBBS_VARIABLEHEIGHT | Version 4.71. The band can be resized by the rebar control; cyIntegral and cyMaxChild affect how the rebar will resize the band.
clrFore and clrBack
Band foreground and background colors. If hbmBack specifies a background bitmap, these members are ignored. By default, the band will use the background color of the rebar control set with the RB_SETBKCOLOR message. If a background color is specified here, then this background color will be used instead.
lpText
Address of a buffer that contains the display text for the band. If band information is being requested from the control and RBBIM_TEXT is specified in fMask, this member must be initialized to the address of the buffer that will receive the text.
cch
Size of the buffer at lpText, in bytes. If information is not being requested from the control, this member is ignored.
iImage
Zero-based index of any image that should be displayed in the band. The image list is set using the RB_SETBARINFO message.
hwndChild
Handle to the child window contained in the band, if any.
cxMinChild
Minimum width of the child window, in pixels. The band can't be sized smaller than this value.
cyMinChild
Minimum height of the child window, in pixels. The band can't be sized smaller than this value.
cx
Length of the band, in pixels.
hbmBack
Handle to a bitmap that is used as the background for this band.
wID
UINT value that the control uses to identify this band for custom draw notification messages. This value may be used for additional purposes in the future.
cyChild
Version 4.71. Initial height of the band, in pixels. This member is ignored unless the RBBS_VARIABLEHEIGHT style is specified.
cyMaxChild
Version 4.71. Maximum height of the band, in pixels. This member is ignored unless the RBBS_VARIABLEHEIGHT style is specified.
cyIntegral
Version 4.71. Step value by which the band can grow or shrink, in pixels. If the band is resized, it will be resized in steps specified by this value. This member is ignored unless the RBBS_VARIABLEHEIGHT style is specified.
cxIdeal
Version 4.71. Ideal width of the band, in pixels. If the band is maximized to the ideal width (see RB_MAXIMIZEBAND), the rebar control will attempt to make the band this width.
lParam
Version 4.71. Application-defined value.
cxHeader
Version 4.71. Size of the band's header, in pixels. The band header is the area between the edge of the band and the edge of the child window. This is the area where band text and images are displayed, if they are specified. If this value is specified, it will override the normal header dimensions that the control calculates for the band.

Remarks

The cxMinChild, cyMinChild, and cx members provide information on dimensions relative to the orientation of the control. That is, for a horizontal rebar control, cxMinChild and cx are horizontal measurements and cyMinChild is a vertical measurement. However, if the control uses the CCS_VERT style, cxMinChild and cx are vertical measurements and cyMinChild is a horizontal measurement.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


REBARINFO

Contains information that describes rebar control characteristics.

typedef struct tagREBARINFO{
    UINT        cbSize;
    UINT        fMask;
    HIMAGELIST  himl;
} REBARINFO, FAR *LPREBARINFO;

Members

cbSize
Size of this structure, in bytes. Your application must fill this member before sending any messages that use the address of this structure as a parameter.
fMask
Flag values that describe characteristics of the rebar control. Currently, rebar controls support only one value:
RBIM_IMAGELIST The himl member is valid or must be filled.
himl
Handle to an image list. The rebar control will use the specified image list to obtain images.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


Status Bars

A status bar is a horizontal window at the bottom of a parent window in which an application can display various kinds of status information. The status bar can be divided into parts to display more than one type of information. The following illustration shows the status bar in the Microsoft® Windows® Paint application. The status bar is the bar at the bottom of the window that contains Help text and coordinate information.

Status bar in the Microsoft® Windows® Paint application.

  • Using Status Bars
  • Status Bar Updates in Internet Explorer
  • Status Bar Reference

Using Status Bars

You can create a status bar by using the CreateStatusWindow function or by using the CreateWindowEx function and specifying the STATUSCLASSNAME window class. To ensure that the common control dynamic-link library (DLL) is loaded, use the InitCommonControls function first. After you create the status bar, you can divide it into parts, set the text for each part, and control the appearance of the window by using status bar messages.

Types and Styles

The default position of a status bar is along the bottom of the parent window, but you can specify the CCS_TOP style to have it appear at the top of the parent window's client area.

You can specify the SBARS_SIZEGRIP style to include a sizing grip at the right end of the status bar.

Note Combining the CCS_TOP and SBARS_SIZEGRIP styles is not recommended because the resulting sizing grip is not functional.

Size and Height

The window procedure for the status bar automatically sets the initial size and position of the window, ignoring the values specified in the CreateWindowEx function. The width is the same as that of the parent window's client area. The height is based on the metrics of the font that is currently selected into the status bar's device context and on the width of the window's borders.

The window procedure automatically adjusts the size of the status bar whenever it receives a WM_SIZE message. Typically, when the size of the parent window changes, the parent sends a WM_SIZE message to the status bar.

An application can set the minimum height of a status bar's drawing area by sending the window an SB_SETMINHEIGHT message, specifying the minimum height, in pixels. The drawing area does not include the window's borders. A minimum height is useful for drawing in an owner-drawn status bar. For more information, see Owner-Drawn Status Bars later in this chapter.

You retrieve the widths of the borders of a status bar by sending the window an SB_GETBORDERS message. The message includes the address of a three-element array that receives the widths.

Multiple-Part Status Bars

A status bar can have many different parts, each displaying a different line of text. You divide a status bar into parts by sending the window an SB_SETPARTS message, specifying the number of parts to create and the address of an integer array. The array contains one element for each part, and each element specifies the client coordinate of the right edge of a part.

A status bar can have a maximum of 256 parts, although applications typically use far fewer than that. You retrieve a count of the parts in a status bar, as well as the coordinate of the right edge of each part, by sending the window an SB_GETPARTS message.

Status Bar Text Operations

You set the text of any part of a status bar by sending the SB_SETTEXT message, specifying the zero-based index of a part, an address of the string to draw in the part, and the technique for drawing the string. The drawing technique determines whether the text has a border and, if it does, the style of the border. It also determines whether the parent window is responsible for drawing the text. For more information, see the Owner-Drawn Status Bars section below.

By default, text is left-aligned within the specified part of a status bar. You can embed tab characters (\ t) in the text to center or right-align it. Text to the right of a single tab character is centered, and text to the right of a second tab character is right-aligned.

To retrieve text from a status bar, use the SB_GETTEXTLENGTH and SB_GETTEXT messages.

If your application uses a status bar that has only one part, you can use the WM_SETTEXT, WM_GETTEXT, and WM_GETTEXTLENGTH messages to perform text operations. These messages deal only with the part that has an index of zero, allowing you to treat the status bar much like a static text control.

To display a line of status without creating a status bar, use the DrawStatusText function. The function uses the same techniques to draw the status as the window procedure for the status bar, but it does not automatically set the size and position of the status information. When calling the function, you must specify the size and position of the status information as well as the device context of the window in which to draw it.

Owner-Drawn Status Bars

You can define individual parts of a status bar to be owner-drawn parts. Using this technique gives you more control than you would otherwise have over the appearance of the window part. For example, you can display a bitmap rather than text or draw text using a different font.

To define a window part as owner-drawn, send the SB_SETTEXT message to the status bar, specifying the part and the SBT_OWNERDRAW drawing technique. When SBT_OWNERDRAW is specified, the lParam parameter is a 32-bit application-defined value that the application can use when drawing the part. For example, you can specify a font handle, a bitmap handle, an address of a string, and so on.

When a status bar needs to draw an owner-drawn part, it sends the WM_DRAWITEM message to the parent window. The wParam parameter of the message is the child window identifier of the status bar, and the lParam parameter is the address of a DRAWITEMSTRUCT structure. The parent window uses the information in the structure to draw the part. For an owner-drawn part of a status bar, DRAWITEMSTRUCT contains the following information.
Member | Description
CtlType | Undefined; do not use.
CtlID | Child window identifier of the status bar.
itemID | Zero-based index of the part to be drawn.
itemAction | Undefined; do not use.
itemState | Undefined; do not use.
hwndItem | Handle to the status bar.
hDC | Handle to the device context of the status bar.
rcItem | Coordinates of the window part to be drawn. The coordinates are relative to the upper left corner of the status bar.
itemData | Application-defined 32-bit value specified in the lParam parameter of the SB_SETTEXT message.

Simple Mode Status Bars

You put a status bar in "simple mode" by sending it an SB_SIMPLE message. A simple mode status bar displays only one part. When the text of the window is set, the window is invalidated, but it is not redrawn until the next WM_PAINT message. Waiting for the message reduces screen flicker by minimizing the number of times the window is redrawn. A simple mode status bar is useful for displaying Help text for menu items while the user is scrolling through the menu.

The string that a status bar displays while in simple mode is maintained separately from the strings that it displays while in nonsimple mode. This means you can put the window in simple mode, set its text, and switch back to nonsimple mode without the nonsimple mode text being changed.

When setting the text of a simple mode status bar, you can specify any drawing technique except SBT_OWNERDRAW. A simple mode status bar does not support owner drawing.

Default Status Bar Message Processing

This section describes the messages handled by the window procedure for the predefined STATUSCLASSNAME class.
Message | Default processing
WM_CREATE | Initializes the status bar.
WM_DESTROY | Frees resources allocated for the status bar.
WM_GETFONT | Returns the handle to the current font with which the status bar draws its text.
WM_GETTEXT | Copies the text from the first part of a status bar to a buffer. It returns a 32-bit value that specifies the length, in characters, of the text and the technique used to draw the text.
WM_GETTEXTLENGTH | Returns a 32-bit value that specifies the length, in characters, of the text in the first part of a status bar and the technique used to draw the text.
WM_NCHITTEST | Returns the HTBOTTOMRIGHT value if the mouse cursor is in the sizing grip, causing the system to display the sizing cursor. If the mouse cursor is not in the sizing grip, the status bar passes this message to the DefWindowProc function.
WM_PAINT | Paints the invalid region of the status bar. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETFONT | Selects the font handle into the device context for the status bar.
WM_SETTEXT | Copies the specified text into the first part of a status bar, using the default drawing operation (specified as zero). It returns TRUE if successful, or FALSE otherwise.
WM_SIZE | Resizes the status bar based on the current width of the parent window's client area and the height of the current font of the status bar.

Status Bar Example

The following example demonstrates how to create a status bar that has a sizing grip and divide the window into four equal parts based on the width of the parent window's client area.

// DoCreateStatusBar - creates a status bar and divides it into
//     the specified number of parts.
// Returns the handle to the status bar.
// hwndParent - parent window for the status bar.
// nStatusID - child window identifier.
// hinst - handle to the application instance.
// nParts - number of parts into which to divide the status bar.
HWND DoCreateStatusBar(HWND hwndParent, int nStatusID,
    HINSTANCE hinst, int nParts)
{
    HWND hwndStatus;
    RECT rcClient;
    HLOCAL hloc;
    LPINT lpParts;
    int i, nWidth;

    // Ensure that the common control DLL is loaded.
    InitCommonControls();

    // Create the status bar.
    hwndStatus = CreateWindowEx(
        0,                       // no extended styles
        STATUSCLASSNAME,         // name of status bar class
        (LPCTSTR) NULL,          // no text when first created
        SBARS_SIZEGRIP |         // includes a sizing grip
        WS_CHILD,                // creates a child window
        0, 0, 0, 0,              // ignores size and position
        hwndParent,              // handle to parent window
        (HMENU) nStatusID,       // child window identifier
        hinst,                   // handle to application instance
        NULL);                   // no window creation data

    // Get the coordinates of the parent window's client area.
    GetClientRect(hwndParent, &rcClient);

    // Allocate an array for holding the right edge coordinates.
    hloc = LocalAlloc(LHND, sizeof(int) * nParts);
    lpParts = LocalLock(hloc);

    // Calculate the right edge coordinate for each part, and
    // copy the coordinates to the array.
    nWidth = rcClient.right / nParts;
    for (i = 0; i < nParts; i++) {
        lpParts[i] = nWidth;
        nWidth += nWidth;
    }

    // Tell the status bar to create the window parts.
    SendMessage(hwndStatus, SB_SETPARTS, (WPARAM) nParts,
        (LPARAM) lpParts);

    // Free the array, and return.
    LocalUnlock(hloc);
    LocalFree(hloc);
    return hwndStatus;
}

Status Bar Updates in Internet Explorer

Status bar controls in Microsoft® Internet Explorer support the following new features.

Icon Support
Icons can now be displayed in a status bar. The SB_SETICON message is used to set the icon.
ToolTip Support
The status bar now supports ToolTips. To enable ToolTips, the SBT_TOOLTIPS style must be set when the status bar is created. The SB_SETTIPTEXT and SB_GETTIPTEXT messages are used to set and retrieve the ToolTip text, respectively. The ToolTip for a part will only be displayed if the part has an icon and no text or if all of the text cannot be displayed inside the part. ToolTips are not supported in simple mode.
Enhanced Simple Mode Support
The SB_ISSIMPLE message has been added to determine if a status bar is in simple mode. The SBN_SIMPLEMODECHANGE notification has been added to inform the owner that the simple mode has changed.
Background Color Support
The SB_SETBKCOLOR message has been added to allow the background color of a status bar to be modified.


Status Bar Styles

Status bar controls support the following styles in addition to standard window styles.
SBARS_SIZEGRIP | The status bar control will include a sizing grip at the right end of the status bar. A sizing grip is similar to a sizing border; it is a rectangular area that the user can click and drag to resize the parent window.
SBT_TOOLTIPS | Version 4.71. Use this style to enable ToolTips.
SBARS_TOOLTIPS | Version 5.80. Identical to SBT_TOOLTIPS. Use this flag for versions 5.00 and later.


CreateStatusWindow

Creates a status window, which is typically used to display the status of an application. The window generally appears at the bottom of the parent window, and it contains the specified text.

HWND CreateStatusWindow(
    LONG style,
    LPCTSTR lpszText,
    HWND hwndParent,
    UINT wID
);

Parameters

style
Window styles for the status window. This parameter must include the WS_CHILD style and should also include the WS_VISIBLE style.
lpszText
Address of a null-terminated string that specifies the status text for the first part.
hwndParent
Handle to the parent window.
wID
Control identifier for the status window. The window procedure uses this value to identify messages it sends to the parent window.

Return Values

Returns the handle for the status window if successful, or NULL otherwise. To retrieve extended error information, call GetLastError.

Remarks

The CreateStatusWindow function calls the CreateWindow function to create the window. It passes the parameters to CreateWindow without modification and sets the position, width, and height parameters to default values.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


DrawStatusText

The DrawStatusText function draws the specified text in the style of a status window with borders.

void DrawStatusText(
    HDC hdc,
    LPRECT lprc,
    LPCTSTR pszText,
    UINT uFlags
);

Parameters

hdc
Handle to the display context for the window.
lprc
Pointer to a RECT structure that contains the position, in client coordinates, of the rectangle in which the text is drawn. The function draws the borders just inside the edges of the specified rectangle.
pszText
Pointer to a null-terminated string that specifies the text to display. Tab characters in the string determine whether the string is left-aligned, right-aligned, or centered.
uFlags
Text drawing flags. This parameter can be a combination of these values:
SBT_NOBORDERS | Prevents borders from being drawn around the specified text.
SBT_POPOUT | Draws highlighted borders that make the text stand out.
SBT_RTLREADING | Indicates that the string pointed to by pszText will be displayed in the opposite direction to the text in the parent window.

Return Values

This function does not return a value.

Remarks

Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Normally, the pszText string will be displayed in the same direction as the text in its parent window. If SBT_RTLREADING is set, the pszText string will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


MenuHelp

Processes WM_MENUSELECT and WM_COMMAND messages and displays Help text about the current menu in the specified status window.

void MenuHelp(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam,
    HMENU hMainMenu,
    HINSTANCE hInst,
    HWND hwndStatus,
    LPUINT lpwIDs
);

Parameters

uMsg
Message being processed. This can be either WM_MENUSELECT or WM_COMMAND.
wParam
wParam of the message specified in uMsg.
lParam
lParam of the message specified in uMsg.
hMainMenu
Handle to the application's main menu.
hInst
Handle to the module that contains the string resources.
hwndStatus
Handle to the status window.
lpwIDs
Pointer to an array of values that contains pairs of string resource identifiers and menu handles. The function searches the array for the handle to the selected menu and, if found, uses the corresponding resource identifier to load the appropriate Help string.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


SB_GETBORDERS

Retrieves the current widths of the horizontal and vertical borders of a status window.

SB_GETBORDERS
    wParam = 0;
    lParam = (LPARAM) (LPINT) aBorders;

Parameters

aBorders
Address of an integer array that has three elements. The first element receives the width of the horizontal border, the second receives the width of the vertical border, and the third receives the width of the border between rectangles.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The borders determine the spacing between the outside edge of the window and the rectangles within the window that contain text. The borders also determine the spacing between rectangles.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_GETICON

Retrieves the icon for a part in a status bar.

SB_GETICON
    wParam = (WPARAM)(INT)iPart;
    lParam = 0;

Parameters

iPart
Zero-based index of the part that contains the icon to be retrieved. If this parameter is -1, the status bar is assumed to be a Simple Mode status bar.

Return Values

Returns the handle to the icon if successful, or NULL otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SB_GETPARTS

Retrieves a count of the parts in a status window. The message also retrieves the coordinate of the right edge of the specified number of parts.

SB_GETPARTS
    wParam = (WPARAM) nParts;
    lParam = (LPARAM) (LPINT) aRightCoord;

Parameters

nParts
Number of parts for which to retrieve coordinates. If this parameter is greater than the number of parts in the window, the message retrieves coordinates for existing parts only.
aRightCoord
Address of an integer array that has the same number of elements as parts specified by nParts. Each element in the array receives the client coordinate of the right edge of the corresponding part. If an element is set to -1, the position of the right edge for that part extends to the right edge of the window. To retrieve the current number of parts, set this parameter to zero.

Return Values

Returns the number of parts in the window if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_GETRECT

Retrieves the bounding rectangle of a part in a status window.

SB_GETRECT
    wParam = (WPARAM) iPart;
    lParam = (LPARAM) (LPRECT) lprc;

Parameters

iPart
Zero-based index of the part whose bounding rectangle is to be retrieved.
lprc
Address of a RECT structure that receives the bounding rectangle.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_GETTEXT

The SB_GETTEXT message retrieves the text from the specified part of a status window.

SB_GETTEXT
    wParam = (WPARAM) iPart;
    lParam = (LPARAM) (LPSTR) szText;

Parameters

iPart
Zero-based index of the part from which to retrieve text.
szText
Pointer to the buffer that receives the text. This parameter is a null-terminated string.

Return Values

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of the following values:
0 | The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS | The text is drawn without borders.
SBT_POPOUT | The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING | The text will be displayed in the opposite direction to the text in the parent window.

If the text has the SBT_OWNERDRAW drawing type, this message returns the 32-bit value associated with the text instead of the length and operation type.

Remarks

Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). If SBT_RTLREADING is set, the szText string will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.

See Also

SB_SETTEXT


SB_GETTEXTLENGTH

The SB_GETTEXTLENGTH message retrieves the length, in characters, of the text from the specified part of a status window.

SB_GETTEXTLENGTH
    wParam = (WPARAM) iPart;
    lParam = 0;

Parameters

iPart
Zero-based index of the part from which to retrieve text.

Return Values

Returns a 32-bit value that consists of two 16-bit values. The low word specifies the length, in characters, of the text. The high word specifies the type of operation used to draw the text. The type can be one of the following values:
0 | The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS | The text is drawn without borders.
SBT_OWNERDRAW | The text is drawn by the parent window.
SBT_POPOUT | The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING | The text will be displayed in the opposite direction to the text in the parent window.

Remarks

Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). If SBT_RTLREADING is set, the specified status window text will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_GETTIPTEXT

Retrieves the ToolTip text for a part in a status bar. The status bar must have been created with the SBT_TOOLTIPS style to enable ToolTips.

SB_GETTIPTEXT
    wParam = MAKEWPARAM(iPart, nSize);
    lParam = (LPARAM)(LPCTSTR)lpszTooltip;

Parameters

iPart
Zero-based index of the part that will receive the ToolTip text.
nSize
Size of the buffer at lpszTooltip, in characters.
lpszTooltip
Address of a character buffer that receives the ToolTip text.

Return Values

The return value is not used.

See Also

Status Bar Updates in Internet Explorer

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SB_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control.

SB_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

SB_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_ISSIMPLE

Checks a status bar control to determine if it is in simple mode.

SB_ISSIMPLE
    wParam = 0;
    lParam = 0;

Return Values

Returns nonzero if the status bar control is in simple mode, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


SB_SETBKCOLOR

Sets the background color in a status bar.

SB_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrBk;

Parameters

clrBk
COLORREF value that specifies the new background color. Specify the CLR_DEFAULT value to cause the status bar to use its default background color.

Return Values

Returns the previous background color, or CLR_DEFAULT if the background color is the default color.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SB_SETICON

Sets the icon for a part in a status bar.

SB_SETICON
    wParam = (WPARAM)(INT)iPart;
    lParam = (LPARAM)(HICON)hIcon;

Parameters

iPart
Zero-based index of the part that will receive the icon. If this parameter is -1, the status bar is assumed to be a simple status bar.
hIcon
Handle to the icon to be set. If this value is NULL, the icon is removed from the part.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

The status bar will not destroy the icon. It is the calling application's responsibility to keep track of and destroy any icons.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SB_SETMINHEIGHT

Sets the minimum height of a status window's drawing area.

SB_SETMINHEIGHT
    wParam = (WPARAM) minHeight;
    lParam = 0;

Parameters

minHeight
Minimum height, in pixels, of the window.

Return Values

No return value.

Remarks

The minimum height is the sum of wParam and twice the width, in pixels, of the vertical border of the status window. An application must send the WM_SIZE message to the status window to redraw the window. The wParam and lParam parameters of the WM_SIZE message should be set to zero.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_SETPARTS

Sets the number of parts in a status window and the coordinate of the right edge of each part.

SB_SETPARTS
    wParam = (WPARAM) nParts;
    lParam = (LPARAM) (LPINT) aWidths;

Parameters

nParts
Number of parts to set (cannot be greater than 256).
aWidths
Pointer to an integer array. The number of elements is specified in nParts. Each element specifies the position, in client coordinates, of the right edge of the corresponding part. If an element is -1, the right edge of the corresponding part extends to the border of the window.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_SETTEXT

The SB_SETTEXT message sets the text in the specified part of a status window.

SB_SETTEXT
    wParam = (WPARAM) iPart | uType;
    lParam = (LPARAM) (LPSTR) szText;

Parameters

iPart
Zero-based index of the part to set. If this parameter is set to SB_SIMPLEID, the status window is assumed to be a simple window with only one part.
uType
Type of drawing operation. This parameter can be one of the following values:
0 | The text is drawn with a border to appear lower than the plane of the window.
SBT_NOBORDERS | The text is drawn without borders.
SBT_OWNERDRAW | The text is drawn by the parent window.
SBT_POPOUT | The text is drawn with a border to appear higher than the plane of the window.
SBT_RTLREADING | The text will be displayed in the opposite direction to the text in the parent window.
szText
Pointer to a null-terminated string that specifies the text to set. If uType is SBT_OWNERDRAW, this parameter represents 32 bits of data. The parent window must interpret the data and draw the text when it receives the WM_DRAWITEM message. The text for each part is limited to 127 characters.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The message invalidates the portion of the window that has changed, causing it to display the new text when the window next receives the WM_PAINT message.

Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). If SBT_RTLREADING is set, the szText string will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.

See Also

SB_GETTEXT


SB_SETTIPTEXT

Sets the ToolTip text for a part in a status bar. The status bar must have been created with the SBT_TOOLTIPS style to enable ToolTips.

SB_SETTIPTEXT
    wParam = (WPARAM)(INT)iPart;
    lParam = (LPARAM)(LPCTSTR)lpszTooltip;

Parameters

iPart
Zero-based index of the part that will receive the ToolTip text.
lpszTooltip
Address of a character buffer that contains the new ToolTip text.

Return Values

The return value is not used.

Remarks

See Status Bar Updates in Internet Explorer for further information.

This ToolTip text is displayed in two situations:

  • When the corresponding pane in the status bar contains only an icon.
  • When the corresponding pane in the status bar contains text that is truncated due to the size of the pane.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SB_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

SB_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

SB_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SB_SIMPLE

Specifies whether a status window displays simple text or displays all window parts set by a previous SB_SETPARTS message.

SB_SIMPLE
    wParam = (WPARAM) (BOOL) fSimple;
    lParam = 0;

Parameters

fSimple
Display type flag. If this parameter is TRUE, the window displays simple text. If it is FALSE, it displays multiple parts.

Return Values

The return value is not used.

Remarks

If the status window is being changed from nonsimple to simple, or vice versa, the window is immediately redrawn.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CLICK (status bar)

Notifies a status bar control's parent window that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.

NM_CLICK
    lpnm = (LPNMMOUSE) lParam;

Parameters

lpnm
Address of an NMMOUSE structure that contains additional information about this notification message. The dwItemSpec member contains the index of the section that was clicked.

Return Values

Return TRUE to indicate that the mouse click was handled and suppress default processing by the system. Return FALSE to allow default processing of the click.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_DBLCLK (status bar)

Notifies a status bar control's parent window that the user has double-clicked the left mouse button within the control. NM_DBLCLK is sent in the form of a WM_NOTIFY message.

NM_DBLCLK
    lpnm = (LPNMMOUSE) lParam;

Parameters

lpnm
Address of an NMMOUSE structure that contains additional information about this notification message. The dwItemSpec member contains the index of the section that was clicked.

Return Values

Return TRUE to indicate that the mouse click was handled and suppress default processing by the system. Return FALSE to allow default processing of the click.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RCLICK (status bar)

Notifies a status bar control's parent window that the user has clicked the right mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnm = (LPNMMOUSE) lParam;

Parameters

lpnm
Address of an NMMOUSE structure that contains additional information about this notification message. The dwItemSpec member contains the index of the section that was clicked.

Return Value

Return TRUE to indicate that the mouse click was handled and suppress default processing by the system. Return FALSE to allow default processing of the click.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RDBLCLK (status bar)

Notifies a status bar control's parent window that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.

NM_RDBLCLK
    lpnm = (LPNMMOUSE) lParam;

Parameters

lpnm
Address of an NMMOUSE structure that contains additional information about this notification message. The dwItemSpec member contains the index of the section that was clicked.

Return Values

Return TRUE to indicate that the mouse click was handled and suppress default processing by the system. Return FALSE to allow default processing of the click.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


SBN_SIMPLEMODECHANGE

Sent by a status bar control when the simple mode changes due to a SB_SIMPLE message. This notification is sent in the form of a WM_NOTIFY message.

SBN_SIMPLEMODECHANGE
    lpnmh = (NMHDR*) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains information about the notification.

Return Values

The return value is ignored by the status bar.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


SysLink Control

This is preliminary documentation and is subject to change.

This section describes the SysLink control.

  • Overview of SysLink Controls
  • SysLink Reference


Overview of SysLink Controls

This is preliminary documentation and is subject to change.

The SysLink control provides a convenient way to embed hypertext links in a window. A SysLink control is a window that renders marked-up text and launches appropriate applications when the user clicks an embedded link. The control enables you to specify link attributes, such as the URL, through markup in the initialization string or by sending LM_SETITEM messages. Multiple links are supported within one control. These links can be accessed by name or by a zero-based index.

This article contains the following sections.

  • SysLink Creation
  • Markup and Link Access
  • Link Attributes
  • Link States

SysLink Creation

To create a SysLink control, call CreateWindow Online link or CreateWindowEx Online link and specify the WC_LINK window class. The lpWindowName parameter common to these functions specifies a pointer to a zero-terminated string containing the marked up text to display. The SysLink control requires side-by-side component support. For more information on manifests and side-by-side component support, see Manifest Files in the Microsoft® Platform Software Development Kit (SDK).

Markup and Link Access

The SysLink control currently supports the anchor tag(<a>) along with the attributes HREF and ID. An HREF may be of any protocol, such as HTTP, FTP, mailto, and so on. An ID is an optional name unique within a SysLink control and associated with an individual link. This ID can be used to access any one of multiple links within a SysLink control. While no checks are performed by the control to guarantee that ID names are unique, having multiple links with the same ID name results in unpredictable behavior. Links are also assigned a zero-based index according to their position within the string. This index can also be used to access a link. Further, you may mix access methods within your application.

Link Attributes

Each link's attributes can be set either within the anchor tag for each link or by sending the LM_SETITEM message. Setting an attribute by specifying it within the initialization string merely initializes the value. You can change the value of an attribute through subsequent use of the LM_SETITEM message.

Link States

Link items can be in any one of three states, represented by the flags in the following table.

State flag | Appearance and meaning
LIS_FOCUSED | The link is surrounded by a dashed box. Pressing ENTER launches the link.
LIS_ENABLED | The link is displayed in blue or purple text, depending on LIS_VISITED. Clicking the link launches it.
LIS_VISITED | The link is displayed in purple text. The user has already visited the URL represented by the link.


SysLink Reference

This is preliminary documentation and is subject to change.

This section describes the SysLink control messages and structures.

Messages:

  • LM_GETIDEALHEIGHT
  • LM_GETITEM
  • LM_HITTEST
  • LM_SETITEM

Structures:

  • LHITTESTINFO
  • LITEM


Tab Controls

A tab control is analogous to the dividers in a notebook or the labels in a file cabinet. By using a tab control, an application can define multiple pages for the same area of a window or dialog box. Each page consists of a certain type of information or a group of controls that the application displays when the user selects the corresponding tab.

  • About Tab Controls
  • Using Tab Controls
  • Tab Control Updates in Internet Explorer
  • Tab Control Reference

    • About Tab Controls

    You can create a tab control by calling the CreateWindowEx function, specifying the WC_TABCONTROL window class. This window class is registered when the common controls dynamic-link library (DLL) is loaded. To ensure that the DLL is loaded, use the InitCommonControls function.

    You send messages to a tab control to add tabs and otherwise affect the control's appearance and behavior. Each message has a corresponding macro that you can use instead of sending the message explicitly. You cannot disable an individual tab in a tab control. However, you can disable a tab control in a property sheet by disabling the corresponding page.

    About Tab Control Styles

    You can apply certain characteristics to tab controls by specifying tab control styles when the control is created. For example, you can specify the alignment and general appearance of the tabs in a tab control.

    You can cause the tabs to look like buttons by specifying the TCS_BUTTONS style. Tabs in this type of tab control should serve the same function as button controls; that is, clicking a tab should carry out a command instead of displaying a page. Because the display area in a button tab control is typically not used, no border is drawn around it.

    You can cause a tab to receive the input focus when clicked by specifying the TCS_FOCUSONBUTTONDOWN style. This style is typically used only with the TCS_BUTTONS style. You can specify that a tab does not receive input focus when clicked by using the TCS_FOCUSNEVER style.

    By default, a tab control displays only one row of tabs. If not all tabs can be shown at once, the tab control displays an up-down control so that the user can scroll additional tabs into view. You can cause a tab control to display multiple rows of tabs, if necessary, by specifying the TCS_MULTILINE style. With this style, all tabs can be displayed at once. The tabs are left-aligned within each row unless you specify the TCS_RIGHTJUSTIFY style. In this case, the width of each tab is increased so that each row of tabs fills the entire width of the tab control.

    A tab control automatically sizes each tab to fit its icon, if any, and its label. To give all tabs the same width, you can specify the TCS_FIXEDWIDTH style. The control sizes all the tabs to fit the widest label, or you can assign a specific width and height by using the TCM_SETITEMSIZE message. Within each tab, the control centers the icon and label, placing the icon to the left of the label. You can force the icon to the left, leaving the label centered, by specifying the TCS_FORCEICONLEFT style. You can left-align both the icon and label by using the TCS_FORCELABELLEFT style. You cannot use the TCS_FIXEDWIDTH style with the TCS_RIGHTJUSTIFY style.

    You can specify that the parent window draws the tabs in the control by using the TCS_OWNERDRAWFIXED style. For more information, see Owner-Drawn Tabs.

    You can specify that a tab control will create a ToolTip control by using the TCS_TOOLTIPS style. For more information about this, see Tab Control ToolTips.

    Tabs and Tab Attributes

    Each tab in a tab control consists of an icon, a label, and application-defined data. This information is specified by a TCITEM structure. You can add tabs to a tab control, retrieve the number of tabs, retrieve and set the contents of a tab, and delete tabs. Tabs are identified by their zero-based index.

    To add tabs to a tab control, use the TCM_INSERTITEM message, specifying the position of the item and the address of a TCITEM structure. You can retrieve and set the contents of an existing tab by using the TCM_GETITEM and TCM_SETITEM messages. For each tab, you can specify an icon, a label, or both. You can also specify application-defined data to associate with the tab.

    You can retrieve the current number of tabs by using the TCM_GETITEMCOUNT message, delete a tab by using the TCM_DELETEITEM message, and delete all tabs in a tab control by using the TCM_DELETEALLITEMS message.

    You can associate application-defined data with each tab. For example, you might save information about each page with its corresponding tab. By default, a tab control allocates four extra bytes per tab for application-defined data. You can change the number of extra bytes per tab by using the TCM_SETITEMEXTRA message. You can only use this message when the tab control is empty.

    The application-defined data is specified by the lParam member of the TCITEM structure. If you use more than 4 bytes of application-defined data, you need to define your own structure and use it instead of TCITEM. You can retrieve and set application-defined data the same way you retrieve and set other information about a tab—by using the TCM_GETITEM and TCM_SETITEM messages.

    The first member of your structure must be a TCITEMHEADER structure, and the remaining members must specify application-defined data. TCITEMHEADER is identical to TCITEM, except it does not have the lParam member. The difference between the size of your structure and the size of TCITEMHEADER should equal the number of extra bytes per tab.

    Display Area

    The display area of a tab control is the area in which an application displays the current page. Typically, an application creates a child window or dialog box, setting the window size and position to fit the display area. Given the window rectangle for a tab control, you can calculate the bounding rectangle of the display area by using the TCM_ADJUSTRECT message.

    Sometimes the display area must be a particular size—for example, the size of a modeless child dialog box. Given the bounding rectangle for the display area, you can use TCM_ADJUSTRECT to calculate the corresponding window rectangle for the tab control.

    Tab Selection

    When the user selects a tab, a tab control sends its parent window notification messages in the form of WM_NOTIFY messages. The TCN_SELCHANGING notification message is sent before the selection changes, and the TCN_SELCHANGE notification message is sent after the selection changes.

    You can process TCN_SELCHANGING to save the state of the outgoing page. You can return TRUE to prevent the selection from changing. For example, you might not want to switch away from a child dialog box in which a control has an invalid setting.

    You must process TCN_SELCHANGE to display the incoming page in the display area. This might simply entail changing the information displayed in a child window. More often, each page consists of a child window or dialog box. In this case, an application might process this notification by destroying or hiding the outgoing child window or dialog box and by creating or showing the incoming child window or dialog box.

    You can retrieve and set the current selection by using the TCM_GETCURSEL and TCM_SETCURSEL messages.

    Tab Control Image Lists

    Each tab can have an icon associated with it, which is specified by an index in the image list for the tab control. When a tab control is created, it has no image list associated with it. An application can create an image list by using the ImageList_Create function and then assign it to a tab control by using the TCM_SETIMAGELIST message.

    You can add images to a tab control's image list just as you would to any other image list. However, an application should remove images by using the TCM_REMOVEIMAGE message instead of the ImageList_Remove function. This message ensures that each tab remains associated with the same image as before.

    Destroying a tab control does not destroy an image list that is associated with it. You must destroy the image list separately. This is useful if you want to assign the same image list to multiple tab controls.

    To retrieve the handle to the image list currently associated with a tab control, you can use the TCM_GETIMAGELIST message.

    Tab Size and Position

    Each tab in a tab control has a size and position. You can set the size of tabs, retrieve the bounding rectangle of a tab, or determine which tab is at a specified position.

    For fixed-width and owner-drawn tab controls, you can set the exact width and height of tabs by using the TCM_SETITEMSIZE message. In other tab controls, each tab's size is calculated based on the icon and label for the tab. The tab control includes space for a border and an additional margin. You can set the thickness of the margin by using the TCM_SETPADDING message.

    You can determine the current bounding rectangle for a tab by using the TCM_GETITEMRECT message. You can determine which tab, if any, is at a specified location by using the TCM_HITTEST message.

    In a tab control with the TCS_MULTILINE style, you can determine the current number of rows of tabs by using the TCM_GETROWCOUNT message.

    Owner-Drawn Tabs

    If a tab control has the TCS_OWNERDRAWFIXED style, the parent window must paint tabs by processing the WM_DRAWITEM message. The tab control sends this message whenever a tab needs to be painted. The lParam parameter specifies the address of a DRAWITEMSTRUCT structure, which contains the index of the tab, its bounding rectangle, and the device context (DC) in which to draw.

    By default, the itemData member of DRAWITEMSTRUCT contains the value of the lParam member of the TCITEM structure. However, if you change the amount of application-defined data per tab, itemData contains the address of the data instead. You can change the amount of application-defined data per tab by using the TCM_SETITEMEXTRA message.

    To specify the size of items in a tab control, the parent window must process the WM_MEASUREITEM message. Because all tabs in an owner-drawn tab control are the same size, this message is sent only once. There is no tab control style for owner-drawn tabs of varying size. You can also set the width and height of tabs by using the TCM_SETITEMSIZE message.

    Tab Control ToolTips

    You can use a ToolTip control to provide a brief description of each tab in a tab control. A tab control that has the TCS_TOOLTIPS style creates a ToolTip control when it is created and destroys the ToolTip control when it is destroyed. You can also create a ToolTip control and assign it to a tab control.

    If you use a ToolTip control with a tab control, the parent window must process the TTN_NEEDTEXT notification message to provide a description of each tab on request.

    To use the same ToolTip control with more than one tab control, create the ToolTip control yourself and assign it to the tab control by using the TCM_SETTOOLTIPS message. You can retrieve the handle to a tab control's current ToolTip control by using the TCM_GETTOOLTIPS message. If you create your own ToolTip control, you should not use the TCS_TOOLTIPS style. For more information about ToolTip controls, see ToolTip Controls.

    Default Tab Control Message Processing

    This section describes the message processing performed by a tab control. Messages specific to tab controls are discussed in other sections of this documentation.
    Message | Processing performed
WM_CAPTURECHANGED | Does nothing if the tab control released the mouse capture itself. If another window captured the mouse and a button is held down, the command releases the button.
WM_CREATE | Allocates and initializes an internal data structure. The control creates a ToolTip control if the TCS_TOOLTIPS style is specified.
WM_DESTROY | Frees resources allocated during WM_CREATE processing.
WM_GETDLGCODE | Returns a combination of the DLGC_WANTARROWS and DLGC_WANTCHARS values.
WM_GETFONT | Returns the handle to the font used for labels.
WM_KEYDOWN | Processes direction keys and changes the selection, if appropriate.
WM_KILLFOCUS | Invalidates the tab that has the focus so it will be repainted to reflect an unfocused state.
WM_LBUTTONDOWN | Forwards the message to the ToolTip control, if any, and changes the selection if the user is clicking a tab. If the user is clicking a button, the control redraws the button to give a sunken appearance and captures the mouse. If the user is clicking either a tab or button and the TCS_FOCUSONBUTTONDOWN style is specified, the control sets the focus to itself.
WM_LBUTTONUP | Releases the mouse if a button was pressed. If the cursor is over the button and is being held down, the control changes the selection accordingly and redraws the button.
WM_MOUSEMOVE | Forwards the message to the ToolTip control, if any. If the TCS_BUTTONS style is specified and the mouse button is being held down after clicking, the control may also redraw the affected button to give it a raised or sunken appearance.
WM_NOTIFY | Forwards notification messages sent by the ToolTip control.
WM_PAINT | Draws a border around the display area (unless the TCS_BUTTONS style is specified) and paints any tabs that intersect the invalid rectangle. For each tab, it draws the body of the tab (or sends a WM_DRAWITEM message to the parent window) and then draws a border around the tab. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_RBUTTONDOWN | Sends an NM_RCLICK notification message to the parent window.
WM_SETFOCUS | Invalidates the tab that has the focus so that it will be repainted to reflect a focused state.
WM_SETFONT | Sets the font used for labels.
WM_SETREDRAW | Sets the state of an internal flag that determines whether the control is repainted when items are inserted and deleted, when the font is changed, and so on.
WM_SIZE | Recalculates the positions of tabs and may invalidate part of the tab control to force repainting of some or all tabs.

    Using Tab Controls

    This section provides two examples that use tab controls. The first example demonstrates how to use a tab control to switch between multiple pages of text in an application's main window. The second example demonstrates how to use a tab control to switch between multiple pages of controls in a dialog box.

    Creating a Tab Control

    The example in this section demonstrates how to create a tab control and display it in the client area of the application's main window. The application displays a third window (a static control) in the display area of the tab control. The parent window positions and sizes the tab control and static control when it processes the WM_SIZE message.

    There are seven tabs, one for each day of the week. When the user selects a tab, the application displays the name of the corresponding day in the static control. The following global variables are used in this example.

    // Global variables

HINSTANCE g_hinst;    // handle to application instance
char g_achTemp[256];  // temporary buffer for strings
HWND g_hwndMain;      // main application window
HWND g_hwndTab;       // tab control
HWND g_hwndDisplay;   // handle to static control in
                      //   tab control's display area

    The following function creates the tab control and adds a tab for each day of the week. The names of the days are defined as string resources, consecutively numbered starting with IDS_FIRSTDAY (defined in the application's header file). Both the parent window and the tab control must have the WS_CLIPSIBLINGS window style. The application's initialization function calls this function after creating the main window.

    // DoCreateTabControl - creates a tab control, sized to fit the
//     specified parent window's client area, and adds some tabs.
// Returns the handle to the tab control.
// hwndParent - parent window (the application's main window).

HWND WINAPI DoCreateTabControl(HWND hwndParent)
{
    RECT rcClient;
    HWND hwndTab;
    TCITEM tie;
    int i;

    // Get the dimensions of the parent window's client area, and
    // create a tab control child window of that size.
    GetClientRect(hwndParent, &rcClient);
    InitCommonControls();
    hwndTab = CreateWindow(
        WC_TABCONTROL, "",
        WS_CHILD | WS_CLIPSIBLINGS | WS_VISIBLE,
        0, 0, rcClient.right, rcClient.bottom,
        hwndParent, NULL, g_hinst, NULL
        );
    if (hwndTab == NULL)
        return NULL;

    // Add tabs for each day of the week.
    tie.mask = TCIF_TEXT | TCIF_IMAGE;
    tie.iImage = -1;
    tie.pszText = g_achTemp;

    for (i = 0; i < 7; i++) {
        LoadString(g_hinst, IDS_FIRSTDAY + i,
                g_achTemp, sizeof(g_achTemp));
        if (TabCtrl_InsertItem(hwndTab, i, &tie) == -1) {
            DestroyWindow(hwndTab);
            return NULL;
        }
    }
    return hwndTab;
}

    The following function creates the static control that occupies the tab control's display area. The application's initialization function calls this function after creating the main window and the tab control.

    // DoCreateDisplayWindow - creates a child window (a static
//     control) to occupy the tab control's display area.
// Returns the handle to the static control.
// hwndParent - parent window (the application's main window).

HWND WINAPI DoCreateDisplayWindow(HWND hwndParent)
{
    HWND hwndStatic = CreateWindow("STATIC", "",
        WS_CHILD | WS_VISIBLE | WS_BORDER,
        0, 0, CW_USEDEFAULT, CW_USEDEFAULT,
        hwndParent, NULL, g_hinst, NULL);

    return hwndStatic;
}

    Following are the relevant portions of the application's window procedure. The application processes the WM_SIZE message to position and size the tab control and the static control. To determine the appropriate position and size for the static control, this example sends the tab control a TCM_ADJUSTRECT message (by using the TabCtrl_AdjustRect macro).

    When a tab is selected, the tab control sends a WM_NOTIFY message, specifying the TCN_SELCHANGE notification message. The application processes this notification message by setting the text of the static control.

    // MainWindowProc - processes the message for the main window class.
// The return value depends on the message.
// hwnd - handle to the window.
// uMsg - identifier for the message.
// wParam - message-specific parameter.
// lParam - message-specific parameter.

LRESULT CALLBACK MainWindowProc(
        HWND hwnd,
        UINT uMsg,
        WPARAM wParam,
        LPARAM lParam
        )
{
    switch (uMsg) {
        case WM_SIZE: {
                HDWP hdwp;
                RECT rc;

                // Calculate the display rectangle, assuming the
                // tab control is the size of the client area.
                SetRect(&rc, 0, 0,
                        GET_X_LPARAM(lParam), GET_Y_LPARAM(lParam));
                TabCtrl_AdjustRect(g_hwndTab, FALSE, &rc);

                // Size the tab control to fit the client area.
                hdwp = BeginDeferWindowPos(2);
                DeferWindowPos(hdwp, g_hwndTab, NULL, 0, 0,
                    GET_X_LPARAM(lParam), GET_Y_LPARAM(lParam),
                    SWP_NOMOVE | SWP_NOZORDER
                    );

                // Position and size the static control to fit the
                // tab control's display area, and make sure the
                // static control is in front of the tab control.
                DeferWindowPos(hdwp,
                    g_hwndDisplay, HWND_TOP, rc.left, rc.top,
                    rc.right - rc.left, rc.bottom - rc.top, 0
                    );
                EndDeferWindowPos(hdwp);
            }
            break;

        case WM_NOTIFY:
            switch (HIWORD(wParam)) {
                case 0:
                    .
                    .    // menu command processing
                    .

                case TCN_SELCHANGE: {
                        int iPage = TabCtrl_GetCurSel(g_hwndTab);
                        LoadString(g_hinst, IDS_FIRSTDAY + iPage,
                            g_achTemp, sizeof(g_achTemp));
                        SendMessage(g_hwndDisplay, WM_SETTEXT, 0,
                            (LPARAM) g_achTemp);
                    }
                    break;
            }
            break;

            .
            .       // additional message processing
            .

        default:
            return DefWindowProc(hwnd, uMsg, wParam, lParam);
    }
    return 0;
}

    Creating a Tabbed Dialog Box

    The example in this section demonstrates how to create a dialog box that uses tabs to provide multiple pages of controls. The main dialog box is a modal dialog box. Each page of controls is defined by a dialog box template that has the WS_CHILD style. When a tab is selected, a modeless dialog box is created for the incoming page and the dialog box for the outgoing page is destroyed.

    Note In many cases, you can implement multiple-page dialog boxes more easily by using property sheets. For more information about property sheets, see Property Sheets

    The template for the main dialog box simply defines two button controls. When processing the WM_INITDIALOG message, the dialog box procedure creates a tab control and loads the dialog box template resources for each of the child dialog boxes.

    The information is saved in an application-defined structure called DLGHDR. A pointer to this structure is associated with the dialog box window by using the SetWindowLong function. The structure is defined in the application's header file, as follows:

    #define C_PAGES 3

typedef struct tag_dlghdr {
    HWND hwndTab;       // tab control
    HWND hwndDisplay;   // current child dialog box
    RECT rcDisplay;     // display rectangle for the tab control
    DLGTEMPLATE *apRes[C_PAGES];
} DLGHDR;

    The following function processes the WM_INITDIALOG message for the main dialog box. The function allocates the DLGHDR structure, loads the dialog box template resources for the child dialog boxes, and creates the tab control.

    The size of each child dialog box is specified by the DLGTEMPLATE structure. The function examines the size of each dialog box and uses the macro for the TCM_ADJUSTRECT message to calculate an appropriate size for the tab control. Then it sizes the dialog box and positions the two buttons accordingly. This example sends TCM_ADJUSTRECT by using the TabCtrl_AdjustRect macro.

    VOID WINAPI OnTabbedDialogInit(HWND hwndDlg)
{
    DLGHDR *pHdr = (DLGHDR *) LocalAlloc(LPTR, sizeof(DLGHDR));
    DWORD dwDlgBase = GetDialogBaseUnits();
    int cxMargin = LOWORD(dwDlgBase) / 4;
    int cyMargin = HIWORD(dwDlgBase) / 8;
    TCITEM tie;
    RECT rcTab;
    HWND hwndButton;
    RECT rcButton;
    int i;

    // Save a pointer to the DLGHDR structure.
    SetWindowLong(hwndDlg, GWL_USERDATA, (LONG) pHdr);

    // Create the tab control.
    InitCommonControls();
    pHdr->hwndTab = CreateWindow(
        WC_TABCONTROL, "",
        WS_CHILD | WS_CLIPSIBLINGS | WS_VISIBLE,
        0, 0, 100, 100,
        hwndDlg, NULL, g_hinst, NULL
        );
    if (pHdr->hwndTab == NULL) {
        // handle error
    }

    // Add a tab for each of the three child dialog boxes.
    tie.mask = TCIF_TEXT | TCIF_IMAGE;
    tie.iImage = -1;
    tie.pszText = "First";
    TabCtrl_InsertItem(pHdr->hwndTab, 0, &tie);
    tie.pszText = "Second";
    TabCtrl_InsertItem(pHdr->hwndTab, 1, &tie);
    tie.pszText = "Third";
    TabCtrl_InsertItem(pHdr->hwndTab, 2, &tie);

    // Lock the resources for the three child dialog boxes.
    pHdr->apRes[0] = DoLockDlgRes(MAKEINTRESOURCE(DLG_FIRST));
    pHdr->apRes[1] = DoLockDlgRes(MAKEINTRESOURCE(DLG_SECOND));
    pHdr->apRes[2] = DoLockDlgRes(MAKEINTRESOURCE(DLG_THIRD));

    // Determine the bounding rectangle for all child dialog boxes.
    SetRectEmpty(&rcTab);
    for (i = 0; i < C_PAGES; i++) {
        if (pHdr->apRes[i]->cx > rcTab.right)
            rcTab.right = pHdr->apRes[i]->cx;
        if (pHdr->apRes[i]->cy > rcTab.bottom)
            rcTab.bottom = pHdr->apRes[i]->cy;
    }
    rcTab.right = rcTab.right * LOWORD(dwDlgBase) / 4;
    rcTab.bottom = rcTab.bottom * HIWORD(dwDlgBase) / 8;

    // Calculate how large to make the tab control, so
    // the display area can accommodate all the child dialog boxes.
    TabCtrl_AdjustRect(pHdr->hwndTab, TRUE, &rcTab);
    OffsetRect(&rcTab, cxMargin - rcTab.left,
            cyMargin - rcTab.top);

    // Calculate the display rectangle.
    CopyRect(&pHdr->rcDisplay, &rcTab);
    TabCtrl_AdjustRect(pHdr->hwndTab, FALSE, &pHdr->rcDisplay);

    // Set the size and position of the tab control, buttons,
    // and dialog box.
    SetWindowPos(pHdr->hwndTab, NULL, rcTab.left, rcTab.top,
            rcTab.right - rcTab.left, rcTab.bottom - rcTab.top,
            SWP_NOZORDER);

    // Move the first button below the tab control.
    hwndButton = GetDlgItem(hwndDlg, BTN_CLOSE);
    SetWindowPos(hwndButton, NULL,
            rcTab.left, rcTab.bottom + cyMargin, 0, 0,
            SWP_NOSIZE | SWP_NOZORDER);

    // Determine the size of the button.
    GetWindowRect(hwndButton, &rcButton);
    rcButton.right -= rcButton.left;
    rcButton.bottom -= rcButton.top;

    // Move the second button to the right of the first.
    hwndButton = GetDlgItem(hwndDlg, BTN_TEST);
    SetWindowPos(hwndButton, NULL,
        rcTab.left + rcButton.right + cxMargin,
        rcTab.bottom + cyMargin, 0, 0,
        SWP_NOSIZE | SWP_NOZORDER);

    // Size the dialog box.
    SetWindowPos(hwndDlg, NULL, 0, 0,
        rcTab.right + cyMargin +
        2 * GetSystemMetrics(SM_CXDLGFRAME),
        rcTab.bottom + rcButton.bottom + 2 * cyMargin +
        2 * GetSystemMetrics(SM_CYDLGFRAME) +
        GetSystemMetrics(SM_CYCAPTION),
        SWP_NOMOVE | SWP_NOZORDER);

    // Simulate selection of the first item.
    OnSelChanged(hwndDlg);
}

// DoLockDlgRes - loads and locks a dialog box template resource.
// Returns the address of the locked resource.
// lpszResName - name of the resource

DLGTEMPLATE * WINAPI DoLockDlgRes(LPCSTR lpszResName)
{
    HRSRC hrsrc = FindResource(NULL, lpszResName, RT_DIALOG);
    HGLOBAL hglb = LoadResource(g_hinst, hrsrc);
    return (DLGTEMPLATE *) LockResource(hglb);
}

    The following function processes the TCN_SELCHANGE notification message for the main dialog box. The function destroys the dialog box for the outgoing page, if any. Then it uses the CreateDialogIndirect function to create a modeless dialog box for the incoming page.

    // OnSelChanged - processes the TCN_SELCHANGE notification.
// hwndDlg - handle to the parent dialog box.

VOID WINAPI OnSelChanged(HWND hwndDlg)
{
    DLGHDR *pHdr = (DLGHDR *) GetWindowLong(
        hwndDlg, GWL_USERDATA);
    int iSel = TabCtrl_GetCurSel(pHdr->hwndTab);

    // Destroy the current child dialog box, if any.
    if (pHdr->hwndDisplay != NULL)
        DestroyWindow(pHdr->hwndDisplay);

    // Create the new child dialog box.
    pHdr->hwndDisplay = CreateDialogIndirect(g_hinst,
        pHdr->apRes[iSel], hwndDlg, ChildDialogProc);
}

    The following function processes the WM_INITDIALOG message for each of the child dialog boxes. You cannot specify the position of a dialog box created using the CreateDialogIndirect function. This function uses the SetWindowPos function to position the child dialog within the tab control's display area.

    // OnChildDialogInit - Positions the child dialog box to fall
//     within the display area of the tab control.

VOID WINAPI OnChildDialogInit(HWND hwndDlg)
{
    HWND hwndParent = GetParent(hwndDlg);
    DLGHDR *pHdr = (DLGHDR *) GetWindowLong(
        hwndParent, GWL_USERDATA);
    SetWindowPos(hwndDlg, HWND_TOP,
        pHdr->rcDisplay.left, pHdr->rcDisplay.top,
        0, 0, SWP_NOSIZE);
}

    Tab Control Updates in Internet Explorer

    Tab controls in Microsoft® Internet Explorer support the following new features.

    Item States
    Tab control items now support an item state to support the TCM_DESELECTALL message. Additionally, the TCITEM structure supports item state values. See Tab Control Item States for more information.
    Extended Styles
    Tab controls now support extended styles that allow the controls to have enhanced capabilities. See Tab Control Extended Styles for more information.
    Structures Renamed
    All structures used with tab controls have been renamed to conform to current naming conventions, while maintaining backward compatibility. For example, the TC_ITEM structure is now named TCITEM.


Tab Control Styles

Current tab control styles are supported, and the following styles have been added.

TCS_BOTTOM | Version 4.70. Tabs appear at the bottom of the control. This value equals TCS_RIGHT.
TCS_BUTTONS | Tabs appear as buttons, and no border is drawn around the display area.
TCS_FIXEDWIDTH | All tabs are the same width. This style cannot be combined with the TCS_RIGHTJUSTIFY style.
TCS_FLATBUTTONS | Version 4.71. Selected tabs appear as being indented into the background while other tabs appear as being on the same plane as the background. This style only affects tab controls with the TCS_BUTTONS style.
TCS_FOCUSNEVER | The tab control does not receive the input focus when clicked.
TCS_FOCUSONBUTTONDOWN | The tab control receives the input focus when clicked.
TCS_FORCEICONLEFT | Icons are aligned with the left edge of each fixed-width tab. This style can only be used with the TCS_FIXEDWIDTH style.
TCS_FORCELABELLEFT | Labels are aligned with the left edge of each fixed-width tab; that is, the label is displayed immediately to the right of the icon instead of being centered. This style can only be used with the TCS_FIXEDWIDTH style, and it implies the TCS_FORCEICONLEFT style.
TCS_HOTTRACK | Version 4.70. Items under the pointer are automatically highlighted. You can check whether or not hot tracking is enabled by calling SystemParametersInfo.
TCS_MULTILINE | Multiple rows of tabs are displayed, if necessary, so all tabs are visible at once.
TCS_MULTISELECT | Version 4.70. Multiple tabs can be selected by holding down CTRL when clicking. This style must be used with the TCS_BUTTONS style.
TCS_OWNERDRAWFIXED | The parent window is responsible for drawing tabs.
TCS_RAGGEDRIGHT | Rows of tabs will not be stretched to fill the entire width of the control. This style is the default.
TCS_RIGHT | Version 4.70. Tabs appear vertically on the right side of controls that use the TCS_VERTICAL style. This value equals TCS_BOTTOM.
TCS_RIGHTJUSTIFY | The width of each tab is increased, if necessary, so that each row of tabs fills the entire width of the tab control. This window style is ignored unless the TCS_MULTILINE style is also specified.
TCS_SCROLLOPPOSITE | Version 4.70. Unneeded tabs scroll to the opposite side of the control when a tab is selected.
TCS_SINGLELINE | Only one row of tabs is displayed. The user can scroll to see more tabs, if necessary. This style is the default.
TCS_TABS | Tabs appear as tabs, and a border is drawn around the display area. This style is the default.
TCS_TOOLTIPS | The tab control has a ToolTip control associated with it.
TCS_VERTICAL | Version 4.70. Tabs appear at the left side of the control, with tab text displayed vertically. This style is valid only when used with the TCS_MULTILINE style. To make tabs appear on the right side of the control, also use the TCS_RIGHT style.

Remarks

The following styles can be modified after the control is created:

  • TCS_BOTTOM
  • TCS_BUTTONS
  • TCS_FIXEDWIDTH
  • TCS_FLATBUTTONS
  • TCS_FORCEICONLEFT
  • TCS_FORCELABELLEFT
  • TCS_MULTILINE
  • TCS_OWNERDRAWFIXED
  • TCS_RAGGEDRIGHT
  • TCS_RIGHT
  • TCS_VERTICAL


Tab Control Extended Styles

The tab control now supports extended styles. These styles are manipulated using the TCM_GETEXTENDEDSTYLE and TCM_SETEXTENDEDSTYLE messages and should not be confused with extended window styles which are passed to CreateWindowEx.
Value | Description
TCS_EX_FLATSEPARATORS | Version 4.71. The tab control will draw separators between the tab items. This extended style only affects tab controls that have the TCS_BUTTONS and TCS_FLATBUTTONS styles. By default, creating the tab control with the TCS_FLATBUTTONS style sets this extended style. If you do not require separators, you should remove this extended style after creating the control.
TCS_EX_REGISTERDROP | Version 4.71. The tab control generates TCN_GETOBJECT notification messages to request a drop target object when an object is dragged over the tab items in the control. The application must call CoInitialize or OleInitialize before setting this style.


Tab Control Item States

Tab control items now support an item state to support the TCM_DESELECTALL message. Additionally, the TCITEM structure supports item state values.
Value | Description
TCIS_BUTTONPRESSED | Version 4.70. The tab control item is selected. This state is only meaningful if the TCS_BUTTONS style flag has been set.
TCIS_HIGHLIGHTED | Version 4.71. The tab control item is highlighted, and the tab and text are drawn using the current highlight color. When using high-color, this will be a true interpolation, not a dithered color.


TCM_ADJUSTRECT

Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a specified display area. You can send this message explicitly or by using the TabCtrl_AdjustRect macro.

TCM_ADJUSTRECT
    wParam = (WPARAM) (BOOL) fLarger;
    lParam = (LPARAM) (LPRECT) prc;

Parameters

fLarger
Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc
Address of a RECT structure that specifies the given rectangle and receives the calculated rectangle.

Return Values

No return value.

Remarks

This message applies only to tab controls that are at the top. It does not apply to tab controls that are on the sides or bottom.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TCM_DELETEALLITEMS

Removes all items from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteAllItems macro.

TCM_DELETEALLITEMS
    wParam = 0;
    lParam = 0;

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_DELETEITEM

Removes an item from a tab control. You can send this message explicitly or by using the TabCtrl_DeleteItem macro.

TCM_DELETEITEM
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Parameters

iItem
Index of the item to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_DESELECTALL

Resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state. You can send this message explicitly or by using the TabCtrl_DeselectAll macro.

TCM_DESELECTALL
    wParam = (WPARAM) (DWORD) fExcludeFocus;
    lParam = 0;

Parameters

fExcludeFocus
Flag that specifies the scope of the item deselection. If this parameter is set to FALSE, all tab items will be reset. If it is set to TRUE, then all tab items except for the one currently selected will be reset.

Return Values

The return value for this message is not used.

Remarks

This message is only meaningful if the TCS_BUTTONS style flag has been set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TCM_GETCURFOCUS

Returns the index of the item that has the focus in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurFocus macro.

TCM_GETCURFOCUS
    wParam = 0;
    lParam = 0;

Return Values

Returns the index of the tab item that has the focus.

Remarks

The item that has the focus may be different than the selected item.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETCURSEL

Determines the currently selected tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetCurSel macro.

TCM_GETCURSEL
    wParam = 0;
    lParam = 0;

Return Values

Returns the index of the selected tab if successful, or -1 if no tab is selected.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETEXTENDEDSTYLE

Retrieves the extended styles that are currently in use for the tab control. You can send this message explicitly or by using the TabCtrl_GetExtendedStyle macro.

TCM_GETEXTENDEDSTYLE
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that represents the extended styles currently in use for the tab control. This value is a combination of tab control extended styles.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TCM_GETIMAGELIST

Retrieves the image list associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetImageList macro.

TCM_GETIMAGELIST
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETITEM

Retrieves information about a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItem macro.

TCM_GETITEM
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (LPTCITEM) pitem;

Parameters

iItem
Index of the tab.
pitem
Address of a TCITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the TCIF_TEXT flag is set in the mask member of the TCITEM structure, the control may change the pszText member of the the structure to point to the new text instead of filling the buffer with the requested text. The control may set the pszText member to NULL to indicate that no text is associated with the item.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETITEMCOUNT

Retrieves the number of tabs in the tab control. You can send this message explicitly or by using the TabCtrl_GetItemCount macro.

TCM_GETITEMCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of items if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETITEMRECT

Retrieves the bounding rectangle for a tab in a tab control. You can send this message explicitly or by using the TabCtrl_GetItemRect macro.

TCM_GETITEMRECT
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (RECT FAR *) prc;

Parameters

iItem
Index of the tab.
prc
Address of a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETROWCOUNT

Retrieves the current number of rows of tabs in a tab control. You can send this message explicitly or by using the TabCtrl_GetRowCount macro.

TCM_GETROWCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETTOOLTIPS

Retrieves the handle to the ToolTip control associated with a tab control. You can send this message explicitly or by using the TabCtrl_GetToolTips macro.

TCM_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the ToolTip control if successful, or NULL otherwise.

Remarks

A tab control creates a ToolTip control if it has the TCS_TOOLTIPS style. You can also assign a ToolTip control to a tab control by using the TCM_SETTOOLTIPS message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the TabCtrl_GetUnicodeFormat macro.

TCM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

TCM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_HIGHLIGHTITEM

Sets the highlight state of a tab item. You can send this message explicitly or by using the TabCtrl_HighlightItem macro.

TCM_HIGHLIGHTITEM
    wParam = (WPARAM) idItem;
    lParam = (LPARAM) MAKELONG(fHighlight,0);

Parameters

idItem
Zero-based index of a tab control item.
fHighlight
Value specifying the highlight state to be set. If this value is TRUE, the tab is highlighted; if FALSE, the tab is set to its default state.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TCM_HITTEST

Determines which tab, if any, is at a specified screen position. You can send this message explicitly or by using the TabCtrl_HitTest macro.

TCM_HITTEST
    wParam = 0;
    lParam = (LPARAM) (LPTCHITTESTINFO) pinfo;

Parameters

pinfo
Address of a TCHITTESTINFO structure that specifies the screen position to test.

Return Values

Returns the index of the tab, or -1 if no tab is at the specified position.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_INSERTITEM

Inserts a new tab in a tab control. You can send this message explicitly or by using the TabCtrl_InsertItem macro.

TCM_INSERTITEM
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (const LPTCITEM) pitem;

Parameters

iItem
Index of the new tab.
pitem
Address of a TCITEM structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

Return Values

Returns the index of the new tab if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_REMOVEIMAGE

Removes an image from a tab control's image list. You can send this message explicitly or by using the TabCtrl_RemoveImage macro.

TCM_REMOVEIMAGE
    wParam = (WPARAM) (int) iImage;
    lParam = 0;

Parameters

iImage
Index of the image to remove.

Return Values

No return value.

Remarks

The tab control updates each tab's image index, so each tab remains associated with the same image as before. If a tab is using the image being removed, the tab will be set to have no image.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETCURFOCUS

Sets the focus to a specified tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurFocus macro.

TCM_SETCURFOCUS
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Parameters

iItem
Index of the tab that gets the focus.

Return Values

No return value.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, TCM_SETCURFOCUS sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See Also

TCM_GETCURFOCUS

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETCURSEL

Selects a tab in a tab control. You can send this message explicitly or by using the TabCtrl_SetCurSel macro.

TCM_SETCURSEL
    wParam = (WPARAM) (int) iItem;
    lParam = 0;

Parameters

iItem
Index of the tab to select.

Return Values

Returns the index of the previously selected tab if successful, or -1 otherwise.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using this message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETEXTENDEDSTYLE

Sets the extended styles that the tab control will use. You can send this message explicitly or by using the TabCtrl_SetExtendedStyle macro.

TCM_SETEXTENDEDSTYLE
    wParam = (WPARAM)dwExMask;
    lParam = (LPARAM)dwExStyle;

Parameters

dwExMask
A DWORD value that indicates which styles in dwExStyle are to be affected. Only the extended styles in dwExMask will be changed. All other styles will be maintained as they are. If this parameter is zero, then all of the styles in dwExStyle will be affected.
dwExStyle
Value specifying the extended tab control styles. This value is a combination of tab control extended styles.

Return Values

Returns a DWORD value that contains the previous tab control extended styles.

Remarks

The dwExMask parameter allows you to modify one or more extended styles without having to retrieve the existing styles first. For example, if you pass TCS_EX_FLATSEPARATORS for dwExMask and 0 for dwExStyle, the TCS_EX_FLATSEPARATORS style will be cleared, but all other styles will remain the same.

For backward compatibility reasons, the TabCtrl_SetExtendedStyle macro has not been updated to use dwExMask.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TCM_SETIMAGELIST

Assigns an image list to a tab control. You can send this message explicitly or by using the TabCtrl_SetImageList macro.

TCM_SETIMAGELIST
    wParam = 0;
    lParam = (LPARAM) (HIMAGELIST) himl;

Parameters

himl
Handle to the image list to assign to the tab control.

Return Values

Returns the handle to the previous image list, or NULL if there is no previous image list.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETITEM

Sets some or all of a tab's attributes. You can send this message explicitly or by using the TabCtrl_SetItem macro.

TCM_SETITEM
    wParam = (WPARAM) (int) iItem;
    lParam = (LPARAM) (LPTCITEM) pitem;

Parameters

iItem
Index of the item.
pitem
Address of a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETITEMEXTRA

Sets the number of bytes per tab reserved for application-defined data in a tab control. You can send this message explicitly or by using the TabCtrl_SetItemExtra macro.

TCM_SETITEMEXTRA
    wParam = (WPARAM) (int) cb;
    lParam = 0;

Parameters

cb
Number of extra bytes.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETITEMSIZE

Sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can send this message explicitly or by using the TabCtrl_SetItemSize macro.

TCM_SETITEMSIZE
    wParam = 0;
    lParam = MAKELPARAM(cx, cy);

Parameters

cx and cy
New width and height, in pixels.

Return Values

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETMINTABWIDTH

Sets the minimum width of items in a tab control. You can send this message explicitly or by using the TabCtrl_SetMinTabWidth macro.

TCM_SETMINTABWIDTH
    wParam = 0;
    lParam = (LPARAM) (INT) cx;

Parameters

cx
Minimum width to be set for a tab control item. If this parameter is set to -1, the control will use the default tab width.

Return Values

Returns an INT value that represents the previous minimum tab width.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TCM_SETPADDING

Sets the amount of space (padding) around each tab's icon and label in a tab control. You can send this message explicitly or by using the TabCtrl_SetPadding macro.

TCM_SETPADDING
    wParam = 0;
    lParam = MAKELPARAM(cx, cy);

Parameters

cx and cy
Amount of horizontal and vertical padding, in pixels.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETTOOLTIPS

Assigns a ToolTip control to a tab control. You can send this message explicitly or by using the TabCtrl_SetToolTips macro.

TCM_SETTOOLTIPS
    wParam = (WPARAM) (HWND) hwndTT;
    lParam = 0;

Parameters

hwndTT
Handle to the ToolTip control.

Return Values

No return value.

Remarks

You can retrieve the ToolTip control associated with a tab control by using the TCM_GETTOOLTIPS message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the TabCtrl_SetUnicodeFormat macro.

TCM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

TCM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_AdjustRect

Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a specified display area. You can use this macro or send the TCM_ADJUSTRECT message explicitly.

VOID TabCtrl_AdjustRect(
    HWND hwnd,
    BOOL fLarger,
    RECT FAR *prc
);

Parameters

hwnd
Handle to the tab control.
fLarger
Operation to perform. If this parameter is TRUE, prc specifies a display rectangle and receives the corresponding window rectangle. If this parameter is FALSE, prc specifies a window rectangle and receives the corresponding display area.
prc
Address of a RECT structure that specifies the given rectangle and receives the calculated rectangle.

Return Values

No return value.

Remarks

This message applies only to tab controls that are at the top. It does not apply to tab controls that are on the sides or bottom.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TabCtrl_DeleteAllItems

Removes all items from a tab control. You can use this macro or send the TCM_DELETEALLITEMS message explicitly.

BOOL TabCtrl_DeleteAllItems(
    HWND hwnd
);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_DeleteItem

Removes an item from a tab control. You can use this macro or send the TCM_DELETEITEM message explicitly.

BOOL TabCtrl_DeleteItem(
    HWND hwnd,
    int iItem
);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the item to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_DeselectAll

Resets items in a tab control, clearing any that were set to the TCIS_BUTTONPRESSED state. You can use this macro or send the TCM_DESELECTALL message explicitly.

void TabCtrl_DeselectAll(
    HWND hwndTab,
    UINT fExcludeFocus
);

Parameters

hwndTab
Handle to the tab control.
fExcludeFocus
Flag value that specifies the scope of the item deselection. If this parameter is set to FALSE, all tab items will be reset. If it is set to TRUE, all but the currently selected tab item will be reset.

Return Values

The return value is not used.

Remarks

This message is only meaningful if the TCS_BUTTONS style flag has been set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TabCtrl_GetCurFocus

Returns the index of the item that has the focus in a tab control. You can use this macro or send the TCM_GETCURFOCUS message explicitly.

int TabCtrl_GetCurFocus(
    HWND hwnd
);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns the index of the tab item that has the focus.

Remarks

The item that has the focus may be different than the selected item.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetCurSel

Determines the currently selected tab in a tab control. You can use this macro or send the TCM_GETCURSEL message explicitly.

int TabCtrl_GetCurSel(
    HWND hwnd
);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns the index of the selected tab if successful, or -1 if no tab is selected.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetExtendedStyle

Retrieves the extended styles that are currently in use for the tab control. You can use this macro or send the TCM_GETEXTENDEDSTYLE message explicitly.

DWORD TabCtrl_GetExtendedStyle(
    HWND hwndTab
);

Parameters

hwndTab
Handle to the tab control.

Return Values

Returns a DWORD value that represents the extended styles currently in use for the tab control. This value is a combination of tab control extended styles.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TabCtrl_GetImageList

Retrieves the image list associated with a tab control. You can use this macro or send the TCM_GETIMAGELIST message explicitly.

HIMAGELIST TabCtrl_GetImageList(
    HWND hwnd
);

Return Values

Returns the handle to the image list if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetItem

Retrieves information about a tab in a tab control. You can use this macro or send the TCM_GETITEM message explicitly.

BOOL TabCtrl_GetItem(
    HWND hwnd,
    int iItem ,
    LPTCITEM pitem
);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the tab.
pitem
Address of a TCITEM structure that specifies the information to retrieve and receives information about the tab. When the message is sent, the mask member specifies which attributes to return.

If the mask member specifies the TCIF_TEXT value, the pszText member must contain the address of the buffer that receives the item text, and the cchTextMax member must specify the size of the buffer.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the TCIF_TEXT flag is set in the mask member of the TCITEM structure, the control may change the pszText member of the the structure to point to the new text instead of filling the buffer with the requested text. The control may set the pszText member to NULL to indicate that no text is associated with the item.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetItemCount

Retrieves the number of tabs in the tab control. You can use this macro or send the TCM_GETITEMCOUNT message explicitly.

int TabCtrl_GetItemCount(
    HWND hwnd
);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns the number of items if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetItemRect

Retrieves the bounding rectangle for a tab in a tab control. You can use this macro or send the TCM_GETITEMRECT message explicitly.

BOOL TabCtrl_GetItemRect(
    HWND hwnd,
    int iItem,
    RECT FAR *prc
);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the tab.
prc
Address of a RECT structure that receives the bounding rectangle of the tab, in viewport coordinates.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetRowCount

Retrieves the current number of rows of tabs in a tab control. You can use this macro or send the TCM_GETROWCOUNT message explicitly.

int TabCtrl_GetRowCount(
    HWND hwnd
);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns the number of rows of tabs.

Remarks

Only tab controls that have the TCS_MULTILINE style can have multiple rows of tabs.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetToolTips

Retrieves the handle to the ToolTip control associated with a tab control. You can use this macro or send the TCM_GETTOOLTIPS message explicitly.

int TabCtrl_GetToolTips(
    HWND hwnd
);

Parameters

hwnd
Handle to the tab control.

Return Values

Returns the handle to the ToolTip control if successful, or NULL otherwise.

Remarks

A tab control creates a ToolTip control if it has the TCS_TOOLTIPS style. You can also assign a ToolTip control to a tab control by using the TCM_SETTOOLTIPS message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_GetUnicodeFormat

Retrieves the UNICODE character format flag for the control. You can use this macro or send the TCM_GETUNICODEFORMAT message explicitly.

BOOL TabCtrl_GetUnicodeFormat(
    HWND hwnd
);

Parameters

hwnd
Handle to the control.

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

See Also

TabCtrl_SetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_HighlightItem

Sets the highlight state of a tab item. You can use this macro or send the TCM_HIGHLIGHTITEM message explicitly.

BOOL TabCtrl_HighlightItem(
    HWND hwndTab,
    INT idItem,
    WORD fHighlight
);

Parameters

hwndTab
Handle to the tab control.
idItem
Zero-based index of a tab control item.
fHighlight
Value specifying the highlight state to be set. If this value is nonzero, the tab is highlighted. If this value is zero, the tab is set to its default state.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TabCtrl_HitTest

Determines which tab, if any, is at a specified screen position. You can use this macro or send the TCM_HITTEST message explicitly.

int TabCtrl_HitTest(
    HWND hwnd,
    LPTCHITTESTINFO pinfo
);

Parameters

hwnd
Handle to the tab control.
pinfo
Address of a TCHITTESTINFO structure that specifies the screen position to test.

Return Values

Returns the index of the tab, or -1 if no tab is at the specified position.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_InsertItem

Inserts a new tab in a tab control. You can use this macro or send the TCM_INSERTITEM message explicitly.

int TabCtrl_InsertItem(
    HWND hwnd,
    int iItem,
    const LPTCITEM pitem
);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the new tab.
pitem
Address of a TCITEM structure that specifies the attributes of the tab. The dwState and dwStateMask members of this structure are ignored by this message.

Return Values

Returns the index of the new tab if successful, or -1 otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_RemoveImage

Removes an image from a tab control's image list. You can use this macro or send the TCM_REMOVEIMAGE message explicitly.

void TabCtrl_RemoveImage(
    HWND hwnd,
    int iImage
);

Parameters

hwnd
Handle to the tab control.
iImage
Index of the image to remove.

Return Values

No return value.

Remarks

The tab control updates each tab's image index, so each tab remains associated with the same image as before. If a tab is using the image being removed, the tab will be set to have no image.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetCurFocus

Sets the focus to a specified tab in a tab control. You can use this macro or send the TCM_SETCURFOCUS message explicitly.

VOID TabCtrl_SetCurFocus(
    HWND hwnd,
    int  iItem
);

Parameters

hwnd
Handle to the tab control.
iItem
Zero-based index of the tab that gets the focus.

Return Values

No return value.

Remarks

If the tab control has the TCS_BUTTONS style (button mode), the tab with the focus may be different from the selected tab. For example, when a tab is selected, the user can press the arrow keys to set the focus to a different tab without changing the selected tab. In button mode, the TabCtrl_SetCurFocus macro sets the input focus to the button associated with the specified tab, but it does not change the selected tab.

If the tab control does not have the TCS_BUTTONS style, changing the focus also changes the selected tab. In this case, the tab control sends the TCN_SELCHANGING and TCN_SELCHANGE notification messages to its parent window.

See Also

TabCtrl_GetCurFocus, TCM_GETCURFOCUS

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetCurSel

Selects a tab in a tab control. You can use this macro or send the TCM_SETCURSEL message explicitly.

int TabCtrl_SetCurSel(
    HWND hwnd,
    int iItem
);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the tab to select.

Return Values

Returns the index of the previously selected tab if successful, or -1 otherwise.

Remarks

A tab control does not send a TCN_SELCHANGING or TCN_SELCHANGE notification message when a tab is selected using the TCM_SETCURSEL message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetExtendedStyle

Sets the extended styles that the tab control will use. You can use this macro or send the TCM_SETEXTENDEDSTYLE message explicitly.

DWORD TabCtrl_SetExtendedStyle(
    HWND hwndTab,
    DWORD dwExStyle
);

Parameters

hwndTab
Handle to the tab control.
dwExStyle
Value that contains the new tab control extended styles. This value is a combination of tab control extended styles.

Return Values

Returns a DWORD value that contains the previous tab control extended styles.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TabCtrl_SetImageList

Assigns an image list to a tab control. You can use this macro or send the TCM_SETIMAGELIST message explicitly.

BOOL TabCtrl_SetImageList(
    HWND hwnd,
    HIMAGELIST himl
);

Parameters

hwnd
Handle to the tab control.
himl
Handle to the image list to assign to the tab control.

Return Values

Returns the handle to the previous image list, or NULL if there is no previous image list.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetItem

Sets some or all of a tab's attributes. You can use this macro or send the TCM_SETITEM message explicitly.

BOOL TabCtrl_SetItem(
    HWND hwnd,
    int iItem,
    LPTCITEM pitem
);

Parameters

hwnd
Handle to the tab control.
iItem
Index of the item.
pitem
Address of a TCITEM structure that contains the new item attributes. The mask member specifies which attributes to set.
If the mask member specifies the LVIF_TEXT value, the pszText member is the address of a null-terminated string and the cchTextMax member is ignored.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetItemExtra

Sets the number of bytes per tab reserved for application-defined data in a tab control. You can use this macro or send the TCM_SETITEMEXTRA message explicitly.

BOOL TabCtrl_SetItemExtra(
    HWND hwnd,
    int cb
);

Parameters

hwnd
Handle to the tab control.
cb
Number of extra bytes.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

By default, the number of extra bytes is four. An application that changes the number of extra bytes cannot use the TCITEM structure to retrieve and set the application-defined data for a tab. Instead, you must define a new structure that consists of the TCITEMHEADER structure followed by application-defined members.

An application should only change the number of extra bytes when a tab control does not contain any tabs.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetItemSize

Sets the width and height of tabs in a fixed-width or owner-drawn tab control. You can use this macro or send the TCM_SETITEMSIZE message explicitly.

DWORD TabCtrl_SetItemSize(
    HWND hwnd,
    int cx,
    int cy
);

Parameters

hwnd
Handle to the tab control.
cx and cy
New width and height, in pixels.

Return Values

Returns the old width and height. The width is in the low-order word of the return value, and the height is in the high-order word.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetMinTabWidth

Sets the minimum width of items in a tab control. You can use this macro or send the TCM_SETMINTABWIDTH message explicitly.

int TabCtrl_SetMinTabWidth(
    HWND hwndTab,
    INT cx
);

Parameters

hwndTab
Handle to the tab control.
cx
Minimum width to be set for a tab control item. If this parameter is set to -1, the control will use the default tab width.

Return Values

Returns an INT value that represents the previous minimum tab width.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TabCtrl_SetPadding

Sets the amount of space (padding) around each tab's icon and label in a tab control. You can use this macro or send the TCM_SETPADDING message explicitly.

void TabCtrl_SetPadding(
    HWND hwnd,
    int cx,
    int cy
);

Parameters

hwnd
Handle to the tab control.
cx and cy
Amount of horizontal and vertical padding, in pixels.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetToolTips

Assigns a ToolTip control to a tab control. You can use this macro or send the TCM_SETTOOLTIPS message explicitly.

void TabCtrl_SetToolTips(
    HWND hwndTab,
    HWND hwndTT
);

Parameters

hwndTab
Handle to the tab control.
hwndTT
Handle to the ToolTip control.

Return Values

No return value.

Remarks

You can retrieve the ToolTip control associated with a tab control by using the TCM_GETTOOLTIPS message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TabCtrl_SetUnicodeFormat

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the TCM_SETUNICODEFORMAT message explicitly.

BOOL TabCtrl_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Parameters

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

See Also

TabCtrl_GetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CLICK (tab)

Notifies a tab control's parent window that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.

NM_CLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored by the tab control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RCLICK (tab)

Notifies a tab control's parent window that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to not allow the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (tab)

Notifies a tab control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TCN_FOCUSCHANGE

Notifies a tab control's parent window that the button focus has changed.

TCN_FOCUSCHANGE

Parameters

None

Return Values

No return value.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


TCN_GETOBJECT

Sent by a tab control when it has the TCS_EX_REGISTERDROP extended style and an object is dragged over a tab item in the control. This notification message is sent in the form of a WM_NOTIFY message.

TCN_GETOBJECT
    lpnmon = (LPNMOBJECTNOTIFY) lParam;

Parameters

lpnmon
Address of an NMOBJECTNOTIFY structure that contains information about the tab item the object is dragged over and receives data the application returns in response to this message.

Return Values

The application processing this notification must return zero.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TCN_KEYDOWN

Notifies a tab control's parent window that a key has been pressed. This message is sent in the form of a WM_NOTIFY message.

TCN_KEYDOWN
    pnm = (NMTCKEYDOWN FAR *) lParam;

Parameters

pnm
Address of an NMTCKEYDOWN structure.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCN_SELCHANGE

Notifies a tab control's parent window that the currently selected tab has changed. This message is sent in the form of a WM_NOTIFY message.

TCN_SELCHANGE
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGE.

Return Values

No return value.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

TCN_SELCHANGING

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCN_SELCHANGING

Notifies a tab control's parent window that the currently selected tab is about to change. This message is sent in the form of a WM_NOTIFY message.

TCN_SELCHANGING
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure. The hwndFrom member is the handle to the tab control. The idFrom member is the child window identifier of the tab control. The code member is TCN_SELCHANGING.

Return Values

Returns TRUE to prevent the selection from changing, or FALSE to allow the selection to change.

Remarks

To determine the currently selected tab, use the TabCtrl_GetCurSel macro.

See Also

TCN_SELCHANGE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMTCKEYDOWN

Contains information about a key press in a tab control. It is used with the TCN_KEYDOWN notification message. This structure supersedes the TC_KEYDOWN structure.

typedef struct tagNMTCKEYDOWN {
    NMHDR hdr;
    WORD wVKey;
    UINT flags;
} NMTCKEYDOWN;

Members

hdr
NMHDR structure that contains information about the notification message.
wVKey
Virtual key code.
flags
Value that is identical to the lParam parameter of the WM_KEYDOWN message.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TCHITTESTINFO

Contains information about a hit test. This structure supersedes the TC_HITTESTINFO structure.

typedef struct tagTCHITTESTINFO {
    POINT pt;
    UINT  flags;
} TCHITTESTINFO, FAR * LPTCHITTESTINFO;

Members

pt
Position to hit test, in client coordinates.
flags
Variable that receives the results of a hit test. The tab control sets this member to one of the following values:
TCHT_NOWHERE | The position is not over a tab.
TCHT_ONITEM | The position is over a tab but not over its icon or its text. For owner-drawn tab controls, this value is specified if the position is anywhere over a tab.
TCHT_ONITEMICON | The position is over a tab's icon.
TCHT_ONITEMLABEL | The position is over a tab's text.
TCHT_ONITEM is a bitwise-OR operation on TCHT_ONITEMICON and TCHT_ONITEMLABEL.

See Also

TCM_HITTEST

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TCITEM

Specifies or receives the attributes of a tab item. It is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages. This structure supersedes the TC_ITEM structure.

typedef struct tagTCITEM {
    UINT mask;
#if (_WIN32_IE >= 0x0300)
    DWORD dwState;
    DWORD dwStateMask;
#else
    UINT lpReserved1;
    UINT lpReserved2;
#endif
    LPTSTR pszText;
    int cchTextMax;
    int iImage;
    LPARAM lParam;
} TCITEM, FAR *LPTCITEM;

Members

mask
Value that specifies which members to retrieve or set. This member can be a combination of the following values:
Flag | Description
TCIF_IMAGE | The iImage member is valid.
TCIF_PARAM | The lParam member is valid.
TCIF_RTLREADING | The string pointed to by pszText will be displayed in the direction opposite to the text in the parent window.
TCIF_STATE | Version 4.70. The dwState member is valid.
TCIF_TEXT | The pszText member is valid.
dwState
Version 4.70. Specifies the item's current state if information is being retrieved. If item information is being set, this member contains the state value to be set for the item. For a list of valid tab control item states, see Tab Control Item States. This member is ignored in the TCM_INSERTITEM message.
dwStateMask
Version 4.70. Specifies which bits of the dwState member contain valid information. This member is ignored in the TCM_INSERTITEM message.
lpReserved1
Version 4.00. Not used.
lpReserved2
Version 4.00. Not used.
pszText
Address of a null-terminated string that contains the tab text when item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index in the tab control's image list, or -1 if there is no image for the tab.
lParam
Application-defined data associated with the tab control item. If more or less than 4 bytes of application-defined data exist per tab, an application must define a structure and use it instead of the TCITEM structure. The first member of the application-defined structure must be a TCITEMHEADER structure.

Remarks

Typically, windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Ordinarily, pszText will be displayed in the same direction as the the text in its parent window. If TCIF_RTLREADING is set, pszText will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TCITEMHEADER

Specifies or receives the attributes of a tab. It is used with the TCM_INSERTITEM, TCM_GETITEM, and TCM_SETITEM messages. This structure supersedes the TC_ITEMHEADER structure.

typedef struct tagTCITEMHEADER{
    UINT   mask;
    UINT   lpReserved1;
    UINT   lpReserved2;
    LPTSTR pszText;
    int    cchTextMax;
    int    iImage;
} TCITEMHEADER, FAR *LPTCITEMHEADER;

Members

mask
Value that specifies which members to retrieve or set. This member can be a combination of the following values:
TCIF_IMAGE | The iImage member is valid.
TCIF_RTLREADING | The string pointed to by pszText will be displayed in the direction opposite to the text in the parent window.
TCIF_TEXT | The pszText member is valid.
lpReserved1
Reserved member. Do not use.
lpReserved2
Reserved member. Do not use.
pszText
Address of a null-terminated string that contains the tab text if item information is being set. If item information is being retrieved, this member specifies the address of the buffer that receives the tab text.
cchTextMax
Size of the buffer pointed to by the pszText member. If the structure is not receiving information, this member is ignored.
iImage
Index into the tab control's image list, or -1 if there is no image for the tab.

Remarks

Typically, windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Ordinarily, pszText will be displayed in the same direction as the the text in its parent window. If TCIF_RTLREADING is set, pszText will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Toolbar Controls

A toolbar is a control window that contains one or more buttons. Each button, when clicked by a user, sends a command message to the parent window. Typically, the buttons in a toolbar correspond to items in the application's menu, providing an additional and more direct way for the user to access an application's commands. The following illustration shows a window with a flat toolbar.

This section discusses the following topics:

  • Toolbar Controls
  • Using Toolbar Controls
  • New Toolbar Items
  • Toolbar Control Reference


What's New in Toolbar Controls

With the release of version 5.80 of the common controls, a number of new toolbar features are available.

  • Notifications
    • TBN_RESTORE
    • TBN_SAVE
  • Button Styles
    • BTNS_AUTOSIZE
    • BTNS_BUTTON
    • BTNS_CHECK
    • BTNS_CHECKGROUP
    • BTNS_DROPDOWN
    • BTNS_GROUP
    • BTNS_NOPREFIX
    • BTNS_SEP
    • BTNS_SHOWTEXT
    • BTNS_WHOLEDROPDOWN

Note Not all of the button styles listed are new; some are old styles that have been renamed.


Toolbar Controls

Toolbars provide a means for users to activate commands and tools contained in an application. To make your application user-friendly, design your toolbar to expose the key functionality of the application. The following topics discuss features to consider when planning a toolbar.

  • Creating a Toolbar

  • Specifying Toolbar Size and Position

  • Displaying ToolTips for Buttons

  • Defining Button Bitmaps

  • Defining Text for Buttons

  • Adding Toolbar Buttons

  • Customizing a Toolbar

  • Using Hot-tracking

  • Using Toolbar Frames

Creating a Toolbar

You can use two functions to create a toolbar—CreateToolbarEx or CreateWindowEx. The CreateToolbarEx function creates a toolbar and adds an initial set of buttons to it. You can also use CreateWindowEx, specifying the TOOLBARCLASSNAME window class to create a toolbar that initially contains no buttons. The TOOLBARCLASSNAME window class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, use the InitCommonControlsEx function first. If you create an empty toolbar, you add buttons to it by using the TB_ADDBUTTONS or TB_INSERTBUTTON message. If you retrieve the size of the toolbar, you must send the TB_AUTOSIZE message after all the items and strings have been inserted into the control to cause the toolbar to recalculate its size based on its content.

Specifying Toolbar Size and Position

If you create a toolbar using CreateToolbarEx, the function enables you to specify in pixels the height and width of the toolbar. However, the CreateWindowEx function does not have parameters for specifying toolbar size. The toolbar window procedure automatically sets the size and position of the toolbar window. The height is based on the height of the buttons in the toolbar. The width is the same as the width of the parent window's client area. To change the automatic size settings, send a TB_SETBUTTONSIZE message. The CCS_TOP and CCS_BOTTOM common control styles determine whether the toolbar is positioned along the top or bottom of the client area. By default, a toolbar has the CCS_TOP style.

Also, the toolbar window procedure automatically adjusts the size of the toolbar whenever it receives a WM_SIZE or TB_AUTOSIZE message. An application should send either of these messages whenever the size of the parent window changes or after sending a message that requires adjusting the size of the toolbar—for example, a TB_SETBUTTONSIZE message.

The toolbar default sizing and positioning behaviors can be turned off by setting the CCS_NORESIZE and CCS_NOPARENTALIGN common control styles. Toolbar controls that are hosted by rebar controls must set these styles because the rebar control sizes and positions the toolbar.

Displaying ToolTips for Buttons

When you specify the TBSTYLE_TOOLTIPS style, the toolbar creates and manages a ToolTip control. A ToolTip control is a small pop-up window that contains a line of text describing a toolbar button. The ToolTip control is hidden and appears only when the user moves the pointer over a toolbar button and leaves it there for approximately one second. The ToolTip control is displayed near the pointer.

When the toolbar receives a WM_MOUSEMOVE message, it sends a notification message to the ToolTip control. The ToolTip control sets a timer and, after approximately one second, checks to see if the pointer is still at the same location and is on a toolbar button. If it is, the ToolTip control sends a TTN_GETDISPINFO notification message to the parent window to retrieve the descriptive text for the button. Then the ToolTip control creates a pop-up window and displays the text in the window. The ToolTip control destroys the pop-up window when the user clicks a mouse button or moves the pointer out of the toolbar.

An application that needs to send messages directly to the ToolTip control can retrieve the handle to the control by using the TB_GETTOOLTIPS message. An application can replace the ToolTip control of a toolbar with another ToolTip control by using the TB_SETTOOLTIPS message.

Defining Button Images

There are two ways to specify the images for buttons—by bitmaps or by image lists. An application must choose which method to use. It cannot use both methods with the same toolbar control. Note that the CreateToolbarEx function uses the bitmap method. Applications that want to use the image list method must use the CreateWindowEx function to create the toolbar control.

Defining Button Images by Using Bitmaps

Each button in a toolbar can include a bitmapped image. A toolbar uses an internal list to store the information that it needs to draw the images. When you call the CreateToolbarEx function, you specify a monochrome or color bitmap that contains the initial images, and the toolbar adds the information to the internal list of images. You can add additional images later by using the TB_ADDBITMAP message.

Each image has a zero-based index. The first image added to the internal list has an index of 0, the second image has an index of 1, and so on. TB_ADDBITMAP adds images to the end of the list and returns the index of the first new image that it added. To associate the image with a button, you must send a TB_ADDBUTTONS message and specify the image's index after you add bitmaps to the internal image list.

Microsoft® Windows® assumes that all of a toolbar's bitmapped images are the same size. You specify the size when you create the toolbar by using CreateToolbarEx. If you use the CreateWindowEx function to create a toolbar, the size of the images is set to the default dimensions of 16 by 15 pixels. You can use the TB_SETBITMAPSIZE message to change the dimensions of the bitmapped images, but you must do so before adding any images to the internal list.

Defining Button Images by Using Image Lists

You can also store button images in a set of image lists. An image list is a collection of images of the same size, each of which can be referred to by its index. Image lists are used to manage large sets of icons or bitmaps. You can use up to three different image lists to display buttons in various states, as shown in the following table.

Normal | Buttons in their default state.
Hot | Buttons that are under the pointer or pressed. Hot items are supported only in toolbar controls that have the TBSTYLE_FLAT style.
Disabled | Buttons that are disabled.

After the toolbar is destroyed, applications must free any image lists they have created.

Defining Text for Buttons

Each button can display a string in addition to, or instead of, an image. A toolbar maintains an internal list that contains all the strings available to toolbar buttons. You add strings to the internal list by using the TB_ADDSTRING message, specifying the address of the buffer containing the strings to add. Each string must be null-terminated, and the last string must be terminated with two null characters.

Each string has a zero-based index. The first string added to the internal list of strings has an index of 0, the second string has an index of 1, and so on. TB_ADDSTRING adds strings to the end of the list and returns the index of the first new string. You use a string's index to associate the string with a button.

Using TB_ADDSTRING is not the only way to add strings to a toolbar. You can display a string in a button by passing a string pointer in the iString field of the TBBUTTON structure that is passed to TB_ADDBUTTONS. Additionally, you can use TB_SETBUTTONINFO to assign text to a toolbar button. For more information, see Assigning Text to a Toolbar Button.

Adding Toolbar Buttons

If you use the CreateToolbarEx function to create a toolbar, you can add buttons to the toolbar by filling an array of TBBUTTON structures and specifying the address of the array in the function call. However, the CreateWindowEx function does not have a parameter for passing a TBBUTTON structure. CreateWindowEx creates an empty toolbar that you fill by sending a TB_ADDBUTTONS message, specifying the address of a TBBUTTON structure.

After a toolbar is created, you can insert buttons by sending a TB_INSERTBUTTON message, which passes the address of a TBBUTTON structure to the toolbar. Each TBBUTTON structure defines the attributes of a button, including the indexes of its string and bitmap as well as its style, state, command identifier, and application-defined 32-bit value.

Note If you use the CreateWindowEx function to create a toolbar, you must send the TB_BUTTONSTRUCTSIZE message before adding any buttons. The message passes the size of the TBBUTTON structure to the toolbar.

Toolbar Button Styles

A button's style determines how the button appears and how it responds to user input. For instance, the BTNS_BUTTON style creates a toolbar button that behaves like a standard push button. A button that has the BTNS_CHECK style is similar to a standard push button, except it toggles between the pressed and nonpressed states each time the user clicks it.

You can create groups of toolbar buttons that act like radio buttons by using the BTNS_GROUP or BTNS_CHECKGROUP style. This causes a button to stay pressed until the user chooses another button in the group. A group is defined as a contiguous collection of buttons, all with the BTNS_GROUP or BTNS_CHECKGROUP style.

The BTNS_SEP style creates a small gap between buttons or draws an etch between buttons on flat toolbars. A button with the BTNS_SEP style does not receive user input.

Version 5.80 of the common controls introduced some new toolbar button styles and renamed some of the older styles. All button style flags now begin with BTNS_XXX instead of TBSTYLE_XXX. For a listing and discussion of the button styles, see Toolbar Control and Button Styles.

Toolbar Button States

Each button in a toolbar has a state. The toolbar updates a button's state to reflect user actions, such as clicking the button. The state indicates whether the button is currently pressed or not pressed, enabled or disabled, hidden or visible. Although an application sets a button's initial state when adding the button to the toolbar, it can change and retrieve the state by sending TB_GETSTATE and TB_SETSTATE messages to the toolbar. For a list of toolbar button states, see Toolbar States.

Command Identifier

Each button has an application-defined command identifier associated with it. Button identifiers are usually defined in an application header file. For example, a Paste button can be defined as:

#define ID_PASTE 100

When the user selects a button, the toolbar sends the parent window a WM_COMMAND or WM_NOTIFY message that includes the command identifier of the button. The parent window examines the command identifier and carries out the command associated with the button. For information about when controls send WM_COMMAND messages and when they send WM_NOTIFY, see the Remarks section of the WM_NOTIFY documentation.

Button Size and Position

A toolbar keeps track of its buttons by assigning each button a position index. The index is zero-based; that is, the leftmost button has an index of 0, the next button to the right has an index of 1, and so on. An application must specify the index of a button when sending messages to retrieve information about the button or to set the button's attributes.

A toolbar updates the position indexes as buttons are inserted and removed. An application can retrieve the current position index of a button by using the TB_COMMANDTOINDEX message. The message specifies the command identifier of a button, and the toolbar window uses the identifier to locate the button and return its position index.

All buttons in a toolbar are the same size. The CreateToolbarEx function requires you to set the initial size of the buttons when you create the toolbar. When you use the CreateWindowEx function, the initial size is set to the default dimensions of 24 by 22 pixels. You can use the TB_SETBUTTONSIZE message to change the button size, but you must do so before adding any buttons to the toolbar. The TB_GETITEMRECT message retrieves the current dimensions of the buttons.

When you add a string that is longer than any string currently in the toolbar, the toolbar automatically resets the width of its buttons. The width is set to accommodate the longest string in the toolbar.

Customizing a Toolbar

A toolbar has built-in customization features that you can make available to the user by giving the toolbar the CCS_ADJUSTABLE common control style. The customization features allow the user to drag a button to a new position or to remove a button by dragging it off the toolbar. In addition, the user can double-click the toolbar to display the Customize Toolbar dialog box, which allows the user to add, delete, and rearrange toolbar buttons. To display the dialog box, use the TB_CUSTOMIZE message. An application determines whether the customization features are available to the user and controls the extent to which the user can customize the toolbar.

As part of the customization process, applications often need to save and restore a toolbar's state. For instance, many applications store the toolbar state before the user begins customizing the toolbar in case the user later wants to restore the toolbar to its original state. The toolbar control does not automatically keep a record of its precustomization state. Your application must save the toolbar state in order to restore it. For more information, see Customizing Toolbars and Creating a Customizable Toolbar.

Using Hot-tracking

Toolbar controls created with the TBSTYLE_FLAT style support hot-tracking by default. Hot-tracking means that when the pointer moves over an item, it is highlighted but not selected. When the user moves the pointer over a toolbar button, the button's appearance changes. You can use other window styles in combination with TBSTYLE_FLAT to produce toolbars that enable hot-tracking but have a different appearance from a flat toolbar. For more information, see Using Hot-tracking with Toolbars.

Using Toolbar Frames

Toolbar frames serve as containers for toolbars and other child windows. You implement toolbar frames by creating a rebar control and adding one or more controls to it. A rebar control hosts one or more bands. Each band contains only one child window.

Rebar controls are separate controls but they are often used to host toolbar controls. Using toolbar and rebar controls together enables you to write applications that are more flexible. For example, toolbars can be moved, repositioned, minimized, and maximized within the rebar control. For more information about programming rebar controls, see Rebar Controls.


Toolbar Controls

Using Toolbar Controls

This section contains examples that demonstrate how to create and use toolbar controls in your applications.

  • Creating Toolbars

  • Creating Transparent Toolbars

  • Creating List-style Toolbars

  • Handling ToolTips

  • Handling Drop-down Buttons

  • Customizing Toolbars

  • Embedding Nonbutton Controls in Toolbars

  • Using Hot-tracking with Toolbars

  • Related Topics

Creating Toolbars

You can use two functions to create a toolbar—CreateWindowEx or CreateToolbarEx. This topic provides code samples using the two functions and also discusses several ways to add text to toolbar buttons.

Creating a Toolbar with CreateWindowEx

The following CreateAToolBar sample function uses CreateWindowEx and specifies the TOOLBARCLASSNAME window class to create an empty toolbar. To add buttons and button strings to the toolbar, the function uses TB_ADDSTRING and TB_ADDBUTTONS messages.

// CreateAToolBar creates a toolbar and adds a set of buttons to it.
// The function returns the handle to the toolbar if successful,
// or NULL otherwise.
// hwndParent is the handle to the toolbar's parent window.
HWND CreateAToolBar(HWND hwndParent)
{
   HWND hwndTB;
   TBADDBITMAP tbab;
   TBBUTTON tbb[3];
   char szBuf[16];
   int iCut, iCopy, iPaste;
   INITCOMMONCONTROLSEX icex;

// Ensure that the common control DLL is loaded.
   icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
   icex.dwICC  = ICC_BAR_CLASSES;
   InitCommonControlsEx(&icex);

// Create a toolbar.
   hwndTB = CreateWindowEx(0, TOOLBARCLASSNAME, (LPSTR) NULL,
        WS_CHILD | CCS_ADJUSTABLE, 0, 0, 0, 0, hwndParent,
        (HMENU) ID_TOOLBAR, g_hinst, NULL);

// Send the TB_BUTTONSTRUCTSIZE message, which is required for
// backward compatibility.
   SendMessage(hwndTB, TB_BUTTONSTRUCTSIZE, (WPARAM) sizeof(TBBUTTON), 0);

// Add the button strings to the toolbar's internal string list.
   LoadString(g_hinst, IDS_CUT, szBuf, MAX_LEN-1);
//Save room for second null terminator.
   szBuf[lstrlen(szBuf) + 1] = 0;  //Double-null terminate.
   iCut = SendMessage(hwndTB, TB_ADDSTRING, 0, (LPARAM) (LPSTR) szBuf);
   LoadString(g_hinst, IDS_COPY, szBuf, MAX_LEN-1);
//Save room for second null terminator.
   szBuf[lstrlen(szBuf) + 1] = 0;  //Double-null terminate.
   iCopy = SendMessage(hwndTB, TB_ADDSTRING, (WPARAM) 0,
       (LPARAM) (LPSTR) szBuf);
   LoadString(g_hinst, IDS_PASTE, szBuf, MAX_LEN-1);
//Save room for second null terminator.
   szBuf[lstrlen(szBuf) + 1] = 0;  //Double-null terminate.
   iPaste = SendMessage(hwndTB, TB_ADDSTRING, (WPARAM) 0,
        (LPARAM) (LPSTR) szBuf);

// Fill the TBBUTTON array with button information, and add the
// buttons to the toolbar. The buttons on this toolbar have text
// but do not have bitmap images.
   tbb[0].iBitmap = -1;
   tbb[0].idCommand = IDS_CUT;
   tbb[0].fsState = TBSTATE_ENABLED;
   tbb[0].fsStyle = BTNS_BUTTON;
   tbb[0].dwData = 0;
   tbb[0].iString = iCut;

   tbb[1].iBitmap = -1;
   tbb[1].idCommand = IDS_COPY;
   tbb[1].fsState = TBSTATE_ENABLED;
   tbb[1].fsStyle = BTNS_BUTTON;
   tbb[1].dwData = 0;
   tbb[1].iString = iCopy;

   tbb[2].iBitmap = -1;
   tbb[2].idCommand = IDS_PASTE;
   tbb[2].fsState = TBSTATE_ENABLED;
   tbb[2].fsStyle = BTNS_BUTTON;
   tbb[2].dwData = 0;
   tbb[2].iString = iPaste;

   SendMessage(hwndTB, TB_ADDBUTTONS, (WPARAM) NUM_BUTTONS,
        (LPARAM) (LPTBBUTTON) &tbb);

   SendMessage(hwndTB, TB_AUTOSIZE, 0, 0);

   ShowWindow(hwndTB, SW_SHOW);
   return hwndTB;
}

Assigning text to a toolbar button

You are not required to make an internal list of strings to add text to a button. There are alternative methods. One alternative is to pass a string pointer to the iString member of a TBBUTTON structure. For example, you can place text in a buffer, retrieve a pointer to the buffer, enter the pointer in a TBBUTTON structure, and send a TB_ADDBUTTONS message, specifying the filled TBBUTTON structure.

tbb[0].iBitmap = -1;
tbb[0].idCommand = IDS_CUT;
tbb[0].fsState = TBSTATE_ENABLED;
tbb[0].fsStyle = TBSTYLE_BUTTON;
tbb[0].dwData = 0;
tbb[0].iString = (int) pszBuf;  // Text is in a buffer.

Another way to assign text to a button is with the TB_SETBUTTONINFO message. You enter the data you want to change in a TBBUTTONINFO structure. Then send a TB_SETBUTTONINFO message. The following example demonstrates how to modify the previous CreateAToolBar code to change the text of the third button from Paste to Change.

char szBuf[8] = "CHANGE";
LPSTR pszBuf;
TBBUTTONINFO tbi;
LPTBBUTTONINFO lptbbi;

// Other code here.
// Initialize pszBuf and lptbbi.

// These are the only fields of the TBBUTTONINFO structure that
// need to be changed to modify text.
    tbi.dwMask = TBIF_TEXT;
    tbi.cbSize = sizeof (TBBUTTONINFO);
    tbi.pszText = pszBuf;
    tbi.cchText = sizeof (szBuf);
SendMessage(hwndTB, TB_SETBUTTONINFO, IDS_PASTE, (LPARAM)
    (LPTBBUTTONINFO)lptbbi);

Note If you change a button's text by using TB_SETBUTTONINFO, this does not affect the string assigned to that button in the internal string list. Also, if you add a toolbar button string to the internal text list, you cannot retrieve the index of that string by calling TB_GETBUTTONINFO; you must use TB_GETBUTTON instead.

Creating a Toolbar with CreateToolbarEx

This example uses CreateToolbarEx to create a toolbar and adds standard bitmaps to the toolbar. The standard toolbar bitmaps are built into Comctl32.dll. You do not have to use the standard bitmaps; you can use your own custom bitmaps. To add a bitmap to an application, use the TB_ADDBITMAP message. The sample function, CreateAToolBar2, adds three standard file bitmaps and four standard view bitmaps. Because CreateAToolBar2 requires a TBBUTTON structure containing the predefined indexes to the bitmaps, you must include the following TBBUTTON structures in your application.

// Toolbar buttons used to create the first 4 buttons.
TBBUTTON tbButtonsCreate [ ] =
{
{STD_FILENEW, IDM_NEW, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{STD_FILEOPEN, IDM_OPEN, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{STD_FILESAVE, IDM_SAVE, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{0, 0, TBSTATE_ENABLED, BTNS_SEP, 0L, 0},
};

// Toolbar buttons to add.
TBBUTTON tbButtonsAdd [ ] =
{
{VIEW_LARGEICONS, IDM_LARGEICON, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{VIEW_SMALLICONS, IDM_SMALLICON, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{VIEW_LIST, IDM_LISTVIEW, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{VIEW_DETAILS, IDM_REPORTVIEW, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
};

// Also the code example uses a MACRO defined in the header file as
// follows: #define ARRAYSIZE(a) (sizeof(a)/sizeof(a[0]))

// CreateAToolBar2 creates a toolbar and adds bitmaps to it.
// The function returns the handle to the toolbar if successful,
// or NULL otherwise.
// The function uses HINST_COMMCTRL as the HINSTANCE and
// IDB_STD_SMALL_COLOR as the bitmap identifier.
// hwndParent is the handle to the toolbar's parent window.
HWND CreateAToolBar2(HWND hWndParent)
{
HWND hWndToolbar;
TBADDBITMAP tb;
int index, stdidx;

// Create a toolbar with three standard file bitmaps and one
// separator.
// In the CreateToolbarEx call the number 15 is used because there
// are 15 items in IDB_STD_SMALL_COLOR.
hWndToolbar = CreateToolbarEx (hWndParent,
    WS_CHILD | WS_BORDER | WS_VISIBLE | TBSTYLE_TOOLTIPS,
    ID_TOOLBAR, 15, HINST_COMMCTRL, IDB_STD_SMALL_COLOR,
    tbButtonsCreate, ARRAYSIZE(tbButtonsCreate), 0, 0, 100, 30, sizeof (TBBUTTON));

// Add four view bitmaps. The view bitmaps are not in the same
// file as the standard bitmaps; therefore, you must change the
// resource identifier from IDB_STD_SMALL_COLOR to
// IDB_VIEW_SMALL_COLOR.
tb.hInst = HINST_COMMCTRL;
tb.nID = IDB_VIEW_SMALL_COLOR;
// In the SendMessage call the number 12 is used because there
// are 12 items in IDB_VIEW_SMALL_COLOR.
stdidx = SendMessage (hWndToolbar, TB_ADDBITMAP, 12, (LPARAM)&tb);

// Update the indexes to the view bitmaps.
for (index = 0; index < 4; index++)
tbButtonsAdd[index].iBitmap += stdidx;

// Add the view buttons.
SendMessage (hWndToolbar, TB_ADDBUTTONS, ARRAYSIZE(tbButtonsAdd), (LPARAM) &tbButtonsAdd[0]);

return hWndToolbar;
}

Creating Transparent Toolbars

Toolbar controls support a transparent look that allows the client area under the toolbar to show through. There are two kinds of transparent toolbars, ones with flat buttons and ones with three-dimensional buttons. If you want your application to match the Microsoft® Windows® interface, use the flat transparent style toolbar. You create a flat transparent toolbar by including the TBSTYLE_FLAT style. To create a nonflat transparent toolbar, use TBSTYLE_TRANSPARENT. The following illustration shows the two kinds of transparent toolbars. The toolbar for the Toolbar Program was created with the TBSTYLE_FLAT style; the toolbar for The Hello Program was created with the TBSTYLE_TRANSPARENT style.

To create a transparent toolbar, all you need to do is add TBSTYLE_FLAT or TBSTYLE_TRANSPARENT to the window style parameter of CreateToolbarEx. If you do not want a line to appear to indicate the bottom of the toolbar, do not use the WS_BORDER window style. The following code snippet shows a call to CreateToolbarEx that produces a transparent toolbar with flat buttons.

hWndToolbar = CreateToolbarEx (hWndParent,
    WS_CHILD | WS_VISIBLE | TBSTYLE_TOOLTIPS | TBSTYLE_FLAT,
    ID_TOOLBAR, 11, (HINSTANCE)HINST_COMMCTRL, IDB_STD_SMALL_COLOR,
    (LPCTBBUTTON)&tbButtons, 4, 0, 0, 100, 30, sizeof (TBBUTTON));

To produce a transparent toolbar with raised buttons, change TBSTYLE_FLAT to TBSTYLE_TRANSPARENT.

Creating List-style Toolbars

Toolbar buttons enable you to display both text and bitmaps. The buttons on a toolbar created with the TBSTYLE_LIST style are different from other toolbar buttons because they place text to the right of the bitmap instead of under the image. Also, the list-style button leaves a blank space if you fail to provide images or text; other buttons do not. You can use the TBSTYLE_LIST toolbar style in combination with the TBSTYLE_FLAT style to create a toolbar with flat buttons. The following illustration shows two list-style toolbars that have buttons with both text and bitmaps. The toolbar for the Toolbar Program was created with the TBSTYLE_LIST style; the toolbar for The Hello Program was created with both the TBSTYLE_LIST and TBSTYLE_FLAT styles.

The following code snippet creates a toolbar with the TBSTYLE_LIST style.

hWndToolbar = CreateToolbarEx (hWndParent,
    WS_CHILD | WS_VISIBLE | TBSTYLE_TOOLTIPS | TBSTYLE_LIST,
    ID_TOOLBAR, 11, (HINSTANCE)HINST_COMMCTRL, IDB_STD_SMALL_COLOR,
    (LPCTBBUTTON)&tbButtons, 4, 0, 0, 100, 30, sizeof (TBBUTTON));

To create a flat list-style toolbar, use the following:

hWndToolbar = CreateToolbarEx (hWndParent,
    WS_CHILD | WS_VISIBLE | TBSTYLE_TOOLTIPS | TBSTYLE_FLAT |
    TBSTYLE_LIST, ID_TOOLBAR, 11, (HINSTANCE)HINST_COMMCTRL,
    IDB_STD_SMALL_COLOR, (LPCTBBUTTON)&tbButtons, 4, 0, 0, 100,
    30, sizeof (TBBUTTON));

When you create a list-style toolbar, you should provide text and bitmaps to avoid blank spaces on the button. For information about adding text and bitmaps to a button, see Assigning Text to a Toolbar Button and Defining Button Bitmaps.

Handling ToolTips

Applications that need to customize the text displayed in toolbar ToolTips must respond to the TTN_GETDISPINFO message sent by the toolbar control to its parent, rather than subclassing the toolbar control and intercepting the notification from the ToolTip to the toolbar. The method by which the toolbar and its associated ToolTip communicate varies from platform to platform.

A toolbar that has the TBSTYLE_TOOLTIPS style creates a ToolTip control, which an application can use to display Help text for toolbar buttons. The parent window receives the TTN_GETDISPINFO notification message when the toolbar needs the Help text for a button. The ToolTip control sends the notification in the form of a WM_NOTIFY message. The lParam parameter includes the address of an NMTTDISPINFO structure that specifies the command identifier of the button for which Help text is needed. An application can copy the Help text to the structure, specify the address of a string containing the Help text, or specify the instance handle and resource identifier of a string resource.

The following example specifies an instance handle and a resource identifier to handle the TTN_GETDISPINFO ToolTip notification.

case WM_NOTIFY:
    switch (((LPNMHDR) lParam)->code)
    {
        case TTN_GETDISPINFO:
            {
            LPTOOLTIPTEXT lpttt;

            lpttt = (LPTOOLTIPTEXT) lParam;
            lpttt->hinst = g_hinst;

            // Specify the resource identifier of the descriptive
            // text for the given button.
            idButton = lpttt->hdr.idFrom;
            switch (idButton)
            {
                case IDM_CUT:
                    lpttt->lpszText = MAKEINTRESOURCE(IDS_TIPS_CUT);
                    break;
                case IDM_COPY:
                    lpttt->lpszText = MAKEINTRESOURCE(IDS_TIPS_COPY);
                    break;
                case IDM_PASTE:
                    lpttt->lpszText = MAKEINTRESOURCE(IDS_TIPS_PASTE);
                    break;
            }
            break;
            }
        .
        . // Process other notifications here.
        .
        default:
            break;
    }

If an application specifies labels in the iString member of the associated TBBUTTON structure, the toolbar control automatically uses that string as the ToolTip. You must send a TB_SETMAXTEXTROWS message and set the maximum text rows to zero to keep the label from appearing on the button. If your application does not respond to TTN_GETDISPINFO, the toolbar uses the label as the ToolTip text.

You can also provide ToolTips by using the TBSTYLE_EX_MIXEDBUTTONS extended style. This style allows you to set text for all buttons, but only display it for those buttons with the BTNS_SHOWTEXT button style. The TBSTYLE_LIST style must also be set. Normally, when a button does not display text, your application must handle TBN_GETINFOTIP to display a ToolTip. With the TBSTYLE_EX_MIXEDBUTTONS extended style, text that is set but not displayed on a button will automatically be used as the button's ToolTip text. Your application needs to handle TBN_GETINFOTIP only if it needs more flexibility in specifying the ToolTip text.

Handling Drop-down Buttons

A drop-down button is designed to present users with a list of options. You create this style button by specifying the BTNS_DROPDOWN style, also called TBSTYLE_DROPDOWN for compatibility with previous versions of the common controls. To produce a drop-down button with an arrow displayed on the right, you must specify BTNS_DROPDOWN and set the TBSTYLE_EX_DRAWDDARROWS toolbar style by sending a TB_SETEXTENDEDSTYLE message. The following illustration shows the two kinds of drop-down buttons. The toolbar for the Toolbar Program was created with the BTNS_DROPDOWN button style; the toolbar of The Hello Program was created with the BTNS_DROPDOWN button style and the TBSTYLE_EX_DRAWDDARROWS toolbar style.

Drop-down button toolbar.

When the user clicks a toolbar button that uses the BTNS_DROPDOWN style, the toolbar control sends its parent a TBN_DROPDOWN notification message. The application's notification handler can then display a list of options. When you click a drop-down arrow button, a TBN_DROPDOWN notification is sent; if you click the associated arrow, a WM_COMMAND message is sent.

An application can support a drop-down button in a toolbar control, as illustrated in the following DoNotify application-defined function:

  • If the incoming notification message is TBN_DROPDOWN, DoNotify retrieves the bounding rectangle of the button the user clicked by sending the TB_GETRECT message.
  • When sending the message, DoNotify specifies the command identifier of the drop-down button as the wParam parameter of the SendMessage function.
  • The button's command identifier was retrieved from the iItem member of the NMTOOLBAR structure that lParam points to.
  • After DoNotify retrieves the bounding rectangle, it calls MapWindowPoints to convert the rectangle from client coordinates to screen coordinates.
  • It then retrieves the pop-up menu from a menu resource by using the GetSubMenu function and calls the TrackPopupMenuEx function to display the menu.
  • Note that DoNotify positions the menu under the correct button by using the rectangle it retrieved earlier. It also includes the TPM_VERTICAL flag to ensure that the menu is displayed so that it doesn't overlap the button.
  • Note also that DoNotify sets rcExclude equal to the button rectangle so that if the toolbar is too close to the bottom of the screen, the menu will appear above the button rather than below it.
BOOL DoNotify(HWND hwnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
#define lpnm   ((LPNMHDR)lParam)
#define lpnmTB ((LPNMTOOLBAR)lParam)

   RECT      rc;
   TPMPARAMS tpm;
   HMENU     hPopupMenu = NULL;
   HMENU     hMenuLoaded;
   BOOL      bRet = FALSE;

   switch(lpnm->code){
      case TBN_DROPDOWN:
         SendMessage(lpnmTB->hdr.hwndFrom, TB_GETRECT,
                     (WPARAM)lpnmTB->iItem, (LPARAM)&rc);

         MapWindowPoints(lpnmTB->hdr.hwndFrom,
                         HWND_DESKTOP, (LPPOINT)&rc, 2);

         tpm.cbSize = sizeof(TPMPARAMS);
         tpm.rcExclude = rc;
         hMenuLoaded = LoadMenu(g_hinst, MAKEINTRESOURCE(IDR_POPUP));
         hPopupMenu = GetSubMenu(LoadMenu(g_hinst,
            MAKEINTRESOURCE(IDR_POPUP)),0);
         TrackPopupMenuEx(hPopupMenu,
            TPM_LEFTALIGN|TPM_LEFTBUTTON|TPM_VERTICAL,
            rc.left, rc.bottom, g_hwndMain, &tpm);
         DestroyMenu(hMenuLoaded);
      return (FALSE);
   }

   return FALSE;
}

Customizing Toolbars

Most Windows-based applications use toolbar controls to provide their users with convenient access to various tools. However, static toolbars have some shortcomings, such as too little space to effectively display all the available tools.

The solution to this problem is to make your application's toolbars customizable. Users can then move, add, and delete tools to select only the ones they need and organize them in whatever way they find convenient.

To enable customization, include the CCS_ADJUSTABLE common controls style flag when you create the toolbar control. There are two basic approaches to customization:

  • The customization dialog box. This system-provided dialog box is the simplest approach. It gives users a graphical user interface that allows them to add, delete, or move icons.
  • Dragging and dropping tools. Implementing drag and drop allows users to move tools to another location on the toolbar or delete them by dragging them off the toolbar. It provides users a quick and easy way to organize their toolbar, but does not allow them to add tools.

You can implement either or both, depending on the needs of the application. Neither of these two approaches to customization provides a built-in mechanism, such as a Cancel or Undo button, to return the toolbar to its former state. You must explicitly use the toolbar control API to store the toolbar's precustomization state. If necessary, you can later use this stored information to restore the toolbar to its original state.

This topic discusses how to enable toolbar customization with the customization dialog box and with drag and drop.

Customization Dialog Box

The customization dialog box is provided by the toolbar control to give users a simple way to add, move, or delete tools. Users can launch it by double-clicking the toolbar. Applications can launch the customization dialog box by sending the toolbar control a TB_CUSTOMIZE message. The following illustration shows an example of the toolbar customization dialog box.

The tools in the right-hand list box are those currently on the toolbar. Initially, this list will contain the tools that you specify when you create the toolbar. The left-hand list box contains the tools that are available to add to the toolbar. Your application is responsible for populating that list and keeping track of what tools are currently on the toolbar.

Implementing the customization dialog box

The toolbar control notifies your application that it is launching a customization dialog box by sending its parent window a TBN_BEGINADJUST notification. It then sends a TBN_INITCUSTOMIZE notification. If you don't want the toolbar to display a Help button, handle this notification and return TBNRF_HIDEHELP.

The toolbar control then collects the information it needs to initialize the dialog box by sending three series of notifications in the following order:

  • A TBN_QUERYINSERT notification for each button on the toolbar to determine where buttons can be inserted. Return FALSE to prevent a button from being inserted to the left of the button specified in the notification. If you return FALSE to all TBN_QUERYINSERT notifications, the dialog box will not be displayed.
  • A TBN_QUERYDELETE notification for each tool currently on the toolbar. Return TRUE if a tool can be deleted, or FALSE if not.
  • A series of TBN_GETBUTTONINFO notifications to populate the list of available tools. To add a tool to the list, fill in the NMTOOLBAR structure that is passed with the notification and return TRUE. When you have no more tools to add, return FALSE.

The dialog box is then displayed, and the user can begin to customize the toolbar.

Once the dialog box is displayed, your application can receive a variety of notifications, depending on the users' actions:

  • TBN_QUERYINSERT. Each time the user changes the location of a tool on the toolbar, or adds a tool. Return FALSE to prevent the tool from being inserted at that location.
  • TBN_DELETINGBUTTON. The user is about to remove a tool from the toolbar.
  • TBN_CUSTHELP. The user has clicked the Help button.
  • TBN_TOOLBARCHANGE. The user has added, moved, or deleted a tool.
  • TBN_RESET. The user has clicked the Reset button.

After the dialog box is destroyed, your application will receive a TBN_ENDADJUST notification.

The following code example demonstrates how to handle notifications to enable toolbar customization.

LRESULT MsgNotify(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    static UINT		i=0;
    LPNMHDR         lpnmhdr;

    lpnmhdr = (LPNMHDR)lparam;

    // The following code allows the toolbar to be customized.
    // If you return FALSE the Customize Toolbar dialog flashes
    // and goes away.

    if (lpnmhdr->code == TBN_QUERYINSERT || lpnmhdr->code ==
        TBN_QUERYDELETE)
    {
     return TRUE;
    }

    if (lpnmhdr->code == TBN_GETBUTTONINFO)
    {
        LPTBNOTIFY lpTbNotify = (LPTBNOTIFY)lparam;
        char  szBuffer [20];

        // 20 = total number of buttons.
        // tbButton and tbButtonNew send information about
        // the other 12 buttons in tbButtonNew.

        if (lpTbNotify->iItem < 12)
        {
         lpTbNotify->tbButton = tbButtonNew[lpTbNotify->iItem]
         LoadString(hInst,
                    4000+ lpTbNotify->iItem,
                    szBuffer, sizeof(szBuffer));

         lstrcpy (lpTbNotify->pszText, szBuffer);
         lpTbNotify->cchText = sizeof (szBuffer);
         return TRUE;
        }
     else
        return 0;
    }
    return 0;
}

Dragging and Dropping Tools

Users can also rearrange the buttons on a toolbar by pressing the SHIFT key and dragging the button to another location. The drag-and-drop process is handled automatically by the toolbar control. It displays a ghost image of the button as it is dragged, and rearranges the toolbar after it is dropped. Users cannot add buttons in this way, but they can delete a button by dropping it off the toolbar.

Although the toolbar control normally does this operation automatically, it also sends your application two notifications: TBN_QUERYDELETE and TBN_QUERYINSERT. To control the drag-and-drop process, handle these notifications as follows:

  • The TBN_QUERYDELETE notification is sent as soon as the user attempts to move the button, before the ghost button is displayed. Return FALSE to prevent the button from being moved. If you return TRUE, the user will be able to either move the tool or delete it by dropping it off the toolbar. Once you have allowed the user to move a tool, you cannot prevent him or her from deleting it. However, if the user deletes a tool, the toolbar control will send your application a TBN_DELETINGBUTTON notification, at which point you can choose to reinsert the button at its original location, thereby canceling the deletion.
  • The TBN_QUERYINSERT notification is sent when the user attempts to drop the button on the toolbar. To prevent the button being moved from being dropped to the left of the button specified in the notification, return FALSE. This notification is not sent if the user drops the tool off the toolbar.

If the user attempts to drag a button without also pressing the SHIFT key, the toolbar control will not handle the drag-and-drop operation. However, it will send your application a TBN_BEGINDRAG notification to indicate the start of a drag operation, and a TBN_ENDDRAG notification to indicate the end. If you want to enable this form of drag-and-drop, your application must handle these notifications, provide the necessary user interface, and modify the toolbar to reflect any changes.

Saving and Restoring Toolbars

In the process of customizing a toolbar, your application might need to save information so that you can restore the toolbar to its original state. To initiate saving or restoring a toolbar state, send the toolbar control a TB_SAVERESTORE message with the lParam set to TRUE. The lParam value of this message specifies whether you are requesting a save or a restore operation. Once the message is sent, there are two ways to handle the save/restore operation:

  • With common controls version 4.72 and earlier, you must implement a TBN_GETBUTTONINFO handler. The toolbar control sends this notification to request information about each button as it is restored.
  • Version 5.80 includes a save/restore option. At the beginning of the process, and as each button is saved or restored, your application will receive a TBN_SAVE or TBN_RESTORE notification. To use this option, you must implement notification handlers to provide the Shell with the bitmap and state information it needs to successfully save or restore the toolbar state.

Toolbar states are saved in a data stream that consists of blocks of Shell-defined data alternating with blocks of application-defined data. One data block of each type is stored for each button, along with an optional block of global data that applications can place at the beginning of the stream. During the save process, your TBN_SAVE handler adds the application-defined blocks to the data stream. During the restore process, the TBN_RESTORE handler reads each block and gives the Shell the information it needs to reconstruct the toolbar.

How to Handle a TBN_SAVE Notification

The first TBN_SAVE notification is sent at the beginning of the save process. Before any buttons are saved, the members of the NMTBSAVE structure are set as shown in the following table.

Member | Setting
iItem | -1
cbData | Amount of memory needed for Shell-defined data.
cButtons | Number of buttons.
pData | Calculated amount of memory needed for application-defined data. Typically, you include some global data, plus data for each button. Add that value to cbData and allocate enough memory to pData to hold it all.
pCurrent | First unused byte in the data stream. If you do not require global toolbar information, set pCurrent = pData so that it points to the start of the data stream. If you do require global toolbar information, store it at pData, then set pCurrent to the beginning of the unused portion of the data stream before returning.

If you want to add some global toolbar information, put it at the start of the data stream. Advance pCurrent to the end of the global data so that it points to the beginning of the unused portion of the data stream, and return.

After you return, the Shell starts saving button information. It adds the Shell-defined data for the first button at pCurrent and then advances pCurrent to the start of the unused portion.

After each button is saved, a TBN_SAVE notification is sent and NMTBSAVE is returned with these members set as follows.

Member | Setting
iItem | Zero-based index of the button number.
pCurrent | Pointer to the first unused byte in the data stream. If you want to store additional information about the button, store it at the location pointed to by pCurrent and update pCurrent to point to the first unused portion of the data stream after that.
tbButton | TBBUTTON structure that describes the button being saved.

When you receive the notification, you should extract any button-specific information you need from tbButton. Remember that when you add a button, you can use the dwData member of TBBUTTON to hold application-specific data. Load your data into the data stream at pCurrent. Advance pCurrent to the end of your data, again pointing to the beginning of the unused portion of the stream, and return.

The Shell then goes to the next button, adds its information to pData, advances pCurrent, loads tbButton, and sends another TBN_SAVE notification. This process continues until all buttons are saved.

Restoring Saved Toolbars

The restore process basically reverses the save process. At the beginning, your application will receive a TBN_RESTORE notification with the iItem member of the NMTBRESTORE structure set to -1. The cbData member is set to the size of pData, and cButtons is set to the number of buttons.

Your notification handler should extract the global information placed at the beginning of pData during the save, and advance pCurrent to the start of the first block of Shell-defined data. Set cBytesPerRecord to the size of the data blocks you used to save the button data. Set cButtons to the number of buttons, and return.

The next TBN_RESTORE is for the first button. The pCurrent member points to the start of your first block of button data, and iItem is to the button index. Extract that data and advance pCurrent. Load the data into tbButton, and return. To omit a button from the restored toolbar, set the idCommand member of tbButton to zero. The Shell will repeat the process for the remaining buttons.

In addition to TBN_SAVE and TBN_RESTORE messages, you can also use messages such as TBN_RESET to save and restore a toolbar. The following code snippet saves a toolbar before it is customized and restores it if the application receives a TBN_RESET message.

int                    i;
LPNMHDR                lpnmhdr;
static int             nResetCount;
static LPTBBUTTON      lpSaveButtons;
LPARAM                 lParam;

switch( lpnmhdr->code)
{
   case TBN_BEGINADJUST: // Start customizing the toolbar.
     {
       LPTBNOTIFY  lpTB = (LPTBNOTIFY)lparam;

       // Allocate memory to store the button information.
       nResetCount = SendMessage(lpTB->hdr.hwndFrom,
         TB_BUTTONCOUNT, 0, 0);
       lpSaveButtons = (LPTBBUTTON)GlobalAlloc(GPTR,
         sizeof(TBBUTTON) * nResetCount);

      // Save the current configuration so if the user presses
      // reset, the original toolbar can be restored.
      for(i = 0; i < nResetCount; i++)
         {
         SendMessage(lpTB->hdr.hwndFrom, TB_GETBUTTON, i,
            (LPARAM)(lpSaveButtons + i));
         }
     }
     return TRUE;

   case TBN_RESET:
      {
      LPTBNOTIFY  lpTB = (LPTBNOTIFY)lparam;
      int         nCount, i;

      // Remove all of the existing buttons starting with the
      // last and working down.
      nCount = SendMessage(lpTB->hdr.hwndFrom, TB_BUTTONCOUNT, 0,
         0);
      for(i = nCount - 1; i >= 0; i--)
         {
         SendMessage(lpTB->hdr.hwndFrom, TB_DELETEBUTTON, i, 0);
         }

      // Restore the buttons that were saved.
      SendMessage(lpTB->hdr.hwndFrom, TB_ADDBUTTONS,
        (WPARAM)nResetCount, (LPARAM)lpSaveButtons);
      }
      return TRUE;

   case TBN_ENDADJUST:
      // Free the memory allocated during TBN_BEGINADJUST
      GlobalFree((HGLOBAL)lpSaveButtons);
      return TRUE;
 }

Embedding Nonbutton Controls in Toolbars

Toolbars support only buttons; therefore, if your application requires a different kind of control, you must create a child window. The following illustration shows a toolbar with an embedded edit control.

Toolbar with embedded edit control.

Any type of window can be placed on a toolbar. The following sample code adds an edit control as a child of the toolbar control window. Because the toolbar is created and then the edit control added, you must provide space for the edit control. One way to do this is to add a separator as a placeholder in the toolbar. For example, to add an edit control to the second code sample in the Creating Toolbars section of this article, you first add a separator to tbButtonsCreate, a customized TBBUTTON structure. You set the width of the separator to the number of pixels you want to reserve.

The following application-defined function creates the toolbar, and adds the buttons and the edit control.

HWND CreateAToolBar(HWND hWndParent)
{
HWND hWndToolbar;
HWND hWndEdit;
TBADDBITMAP tb;
int index, stdidx;
int cx_edit, CX_SEPARATOR = 250; // Width of edit control.
int cy_edit = 35;                // Height of edit control.

// The code example uses a MACRO defined in the header file as
// follows: #define ARRAYSIZE(a) (sizeof(a)/sizeof(a[0]))

// Toolbar buttons

TBBUTTON tbButtonsCreate [ ] =
{
// The separator is set to the width of the edit control.
{CX_SEPARATOR, 0, TBSTATE_ENABLED, BTNS_SEP, {0,0}, 0, -1},
{STD_FILENEW, IDM_NEW, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{STD_FILEOPEN, IDM_OPEN, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{STD_FILESAVE, IDM_SAVE, TBSTATE_ENABLED, BTNS_BUTTON, 0L, 0},
{0, 0, TBSTATE_ENABLED, BTNS_SEP, 0L, 0},
};

TBBUTTON tbButtonsAdd [ ] =
{
{VIEW_LARGEICONS, IDM_LARGEICON, TBSTATE_ENABLED, BTNS_BUTTON,
0L, 0},
{VIEW_SMALLICONS, IDM_SMALLICON, TBSTATE_ENABLED, BTNS_BUTTON,
0L, 0},
{VIEW_LIST, IDM_LISTVIEW, TBSTATE_ENABLED, BTNS_BUTTON,
0L, 0},
{VIEW_DETAILS, IDM_REPORTVIEW, TBSTATE_ENABLED, BTNS_BUTTON,
0L, 0},
};
// Create a toolbar containing separators and three buttons.
// In the CreateToolbarEx call the number 15 is used because there
// are 15 items in IDB_STD_SMALL_COLOR.
hWndToolbar = CreateToolbarEx (hWndParent,
    WS_CHILD | WS_BORDER | WS_VISIBLE | TBSTYLE_TOOLTIPS,
    ID_TOOLBAR, 15, HINST_COMMCTRL,
    IDB_STD_SMALL_COLOR, tbButtonsCreate, ARRAYSIZE(tbButtonsCreate), 0, 0, 100,
    30, sizeof (TBBUTTON));

// Add four view bitmaps. The view bitmaps are not in the same
// file as the standard bitmaps; therefore, you must change the
// resource identifier to IDB_VIEW_SMALL_COLOR.
tb.hInst = HINST_COMMCTRL;
tb.nID = IDB_VIEW_SMALL_COLOR;
// In the SendMessage call the number 12 is used because there
// are 12 items in IDB_VIEW_SMALL_COLOR.
stdidx = SendMessage (hWndToolbar, TB_ADDBITMAP, 12,
   (LPARAM)&tb);

// Update the indexes to the view bitmaps.
for (index = 0; index < 4; index++)
   tbButtonsAdd[index].iBitmap += stdidx;

// Add the view buttons.
SendMessage (hWndToolbar, TB_ADDBUTTONS, ARRAYSIZE(tbButtonsAdd), (LPARAM)
   &tbButtonsAdd[0]);

// Create the edit control child window.
hWndEdit = CreateWindowEx(0L, "Edit", NULL, WS_CHILD | WS_BORDER
   | WS_VISIBLE | ES_LEFT | ES_AUTOVSCROLL | ES_MULTILINE,
   0, 0, cx_edit, cy_edit, hWndToolbar, (HMENU) IDM_EDIT, hInst, 0 );

// Return the toolbar with the embedded edit control.
return hWndToolbar;
}

The sample hard-codes the dimensions of the child window; however, to make a more robust application, determine the size of the toolbar and make the edit control window to fit.

You might want the edit control notifications to go to another window, such as the toolbar's parent. To do this, create the edit control as a child of the toolbar's parent window. Then change the parent of the edit control to the toolbar. Notifications go to the original parent; therefore, the edit control messages go to the parent of the toolbar and yet the edit window resides in the toolbar window. The following code example demonstrates this.

// Create the edit control. Notice that hWndParent, parent of
// the toolbar, is used as the parent of the edit control.
hWndEdit = CreateWindowEx(0L, "Edit", NULL, WS_CHILD | WS_BORDER
   | WS_VISIBLE | ES_LEFT | ES_AUTOVSCROLL | ES_MULTILINE,
   0, 0, cx_edit, cy_edit, hWndParent, (HMENU) IDM_EDIT, hInst, 0 );

// Set the toolbar window as the parent of the edit control
// window. You must set the toolbar as the parent of the edit
// control for it to appear embedded in the toolbar.
SetParent (hWndEdit, hWndToolbar);

Using Hot-tracking with Toolbars

When a mouse pointer hovers over an item, the item becomes hot. If hot-tracking is enabled, the hot item is selected and the item under the mouse pointer is highlighted. Hot-tracking is supported by common controls, such as the toolbar, list view, tab, and header. Some controls have window styles that provide hot-tracking by default; others require that a specific hot-tracking window style be used. A toolbar created with the TBSTYLE_FLAT style supports hot-tracking by default. You can use TBSTYLE_FLAT in combination with other window styles to produce toolbars that enable hot-tracking. Hot-tracking requires that you create image lists; therefore, you cannot use TB_ADDBITMAP or CreateToolbarEx to create your toolbar.

When the mouse hovers over a toolbar button, a box is drawn around the button to highlight it. The following illustration shows a flat or transparent toolbar with hot-tracking enabled.

Transparent toolbar control with hot-tracking enabled.

If you want a toolbar button bitmap to change when the state of the control changes, store the different images in image lists. For example, some applications have black and white toolbar buttons that become colored when they are selected. The two different images are stored in image lists. Toolbars support using up to three image lists. Typically an application has a default, disabled, and hot-tracking list of images. To set and retrieve image lists for hot toolbar buttons, use TB_SETHOTIMAGELIST and TB_GETHOTIMAGELIST. The following code snippet creates, fills, and assigns an image list for hot buttons.

// Create the image list, himlHot.
himlHot = ImageList_Create(MYICON_CX,MYICON_CY,ILC_COLOR8,0,4);
// Load a bitmap from a resource file and adds the images to the
// image list. The bitmap contains four images.
   hBitmapHot = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_HOT));
   ImageList_Add(himlHot, hBitmapHot, NULL);

// Set the image list.
   SendMessage(hwndTB, TB_SETHOTIMAGELIST, 0, (LPARAM)himlHot);

// Loop to fill the array of TBBUTTON structures.
   for(i=0;i<MAX_BUTTONS;i++)
   {
      tbArray[i].iBitmap   = i; // Bitmap from image list.
      tbArray[i].idCommand = IDM_BUTTONSTART + i;
      tbArray[i].fsState   = TBSTATE_ENABLED;
      tbArray[i].fsStyle   = BTNS_DROPDOWN;
      tbArray[i].dwData    = 0;
      tbArray[i].iString   = i;
   }
// Delete the loaded bitmap.
DeleteObject(hBitmapHot);

Related Topics

For complete samples that demonstrate how to create and use toolbars, see the following:

  • Toolbar1
  • Toolbar2
  • Barsdi


Toolbar Control and Button Styles

The following window styles are specific to toolbars. They are combined with other window styles when the toolbar is created.

TBSTYLE_ALTDRAG | Allows users to change a toolbar button's position by dragging it while holding down the ALT key. If this style is not specified, the user must hold down the SHIFT key while dragging a button. Note that the CCS_ADJUSTABLE style must be specified to enable toolbar buttons to be dragged.
TBSTYLE_CUSTOMERASE | Version 4.70. Generates NM_CUSTOMDRAW notification messages when the toolbar processes WM_ERASEBKGND messages.
TBSTYLE_FLAT | Version 4.70. Creates a flat toolbar. In a flat toolbar, both the toolbar and the buttons are transparent and hot-tracking is enabled. Button text appears under button bitmaps. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
TBSTYLE_LIST | Version 4.70. Creates a flat toolbar with button text to the right of the bitmap. Otherwise, this style is identical to TBSTYLE_FLAT. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
TBSTYLE_REGISTERDROP | Version 4.71. Generates TBN_GETOBJECT notification messages to request drop target objects when the cursor passes over toolbar buttons.
TBSTYLE_TOOLTIPS | Creates a ToolTip control that an application can use to display descriptive text for the buttons in the toolbar.
TBSTYLE_TRANSPARENT | Version 4.71. Creates a transparent toolbar. In a transparent toolbar, the toolbar is transparent but the buttons are not. Button text appears under button bitmaps. To prevent repainting problems, this style should be set before the toolbar control becomes visible.
TBSTYLE_WRAPABLE | Creates a toolbar that can have multiple lines of buttons. Toolbar buttons can "wrap" to the next line when the toolbar becomes too narrow to include all buttons on the same line. When the toolbar is wrapped, the break will occur on either the rightmost separator or the rightmost button if there are no separators on the bar. This style must be set to display a vertical toolbar control when the toolbar is part of a vertical rebar control.

Toolbar Button Styles

A toolbar button can have a combination of the following styles. To specify a button style, set the appropriate flags in the fsStyle member of the button's TBBUTTON structure. Not all styles can be combined.

Note For Shell version 4.72 and earlier, both window and button style flags had the form TBSTYLE_XXX. If you are compiling an application with version 4.72 or earlier of Commctrl.h, you must use the TBSTYLE_XXX button style flags. For version 5.80 and later, all button styles have the form BTNS_XXX. All of the TBSTYLE_XXX values have equivalent BTNS_XXX values, with the same meaning and numerical value. For convenience, both forms are given in the following table.

BTNS_AUTOSIZE | Version 5.80. Specifies that the toolbar control should not assign the standard width to the button. Instead, the button's width will be calculated based on the width of the text plus the image of the button. Use the equivalent style flag, TBSTYLE_AUTOSIZE, for version 4.72 and earlier.
BTNS_BUTTON | Version 5.80. Creates a standard button. Use the equivalent style flag, TBSTYLE_BUTTON, for version 4.72 and earlier.
BTNS_CHECK | Version 5.80. Creates a dual-state push button that toggles between the pressed and nonpressed states each time the user clicks it. The button has a different background color when it is in the pressed state. Use the equivalent style flag, TBSTYLE_CHECK, for version 4.72 and earlier.
BTNS_CHECKGROUP | Version 5.80. Creates a button that stays pressed until another button in the group is pressed, similar to option buttons (also known as radio buttons). It is equivalent to combining BTNS_CHECK and BTNS_GROUP. Use the equivalent style flag, TBSTYLE_CHECKGROUP, for version 4.72 and earlier.
BTNS_DROPDOWN | Version 5.80. Creates a drop-down style button that can display a list when the button is clicked. Instead of the WM_COMMAND message used for normal buttons, drop-down buttons send a TBN_DROPDOWN notification. An application can then have the notification handler display a list of options. Use the equivalent style flag, TBSTYLE_DROPDOWN, for version 4.72 and earlier. If the toolbar has the TBSTYLE_EX_DRAWDDARROWS extended style, drop-down buttons will have a drop-down arrow displayed in a separate section to their right. If the arrow is clicked, a TBN_DROPDOWN notification will be sent. If the associated button is clicked, a WM_COMMAND message will be sent.
BTNS_GROUP | Version 5.80. When combined with BTNS_CHECK, creates a button that stays pressed until another button in the group is pressed. Use the equivalent style flag, TBSTYLE_GROUP, for version 4.72 and earlier.
BTNS_NOPREFIX | Version 5.80. Specifies that the button text will not have an accelerator prefix associated with it. Use the equivalent style flag, TBSTYLE_NOPREFIX, for version 4.72 and earlier.
BTNS_SEP | Version 5.80. Creates a separator, providing a small gap between button groups. A button that has this style does not receive user input. Use the equivalent style flag, TBSTYLE_SEP, for version 4.72 and earlier.
BTNS_SHOWTEXT | Version 5.81. Specifies that button text should be displayed. All buttons can have text, but only those buttons with the BTNS_SHOWTEXT button style will display it. This button style must be used with the TBSTYLE_LIST style and the TBSTYLE_EX_MIXEDBUTTONS extended style. If you set text for buttons that do not have the BTNS_SHOWTEXT style, the toolbar control will automatically display it as a ToolTip when the cursor hovers over the button. This feature allows your application to avoid handling the TBN_GETINFOTIP notification for the toolbar.
BTNS_WHOLEDROPDOWN | Version 5.80. Specifies that the button will have a drop-down arrow, but not as a separate section. Buttons with this style behave the same, regardless of whether the TBSTYLE_EX_DRAWDDARROWS extended style is set.
TBSTYLE_AUTOSIZE | Equivalent to BTNS_AUTOSIZE. Use TBSTYLE_AUTOSIZE for version 4.72 and earlier.
TBSTYLE_BUTTON | Equivalent to BTNS_BUTTON. Use TBSTYLE_BUTTON for version 4.72 and earlier.
TBSTYLE_CHECK | Equivalent to BTNS_CHECK. Use TBSTYLE_CHECK for version 4.72 and earlier.
TBSTYLE_CHECKGROUP | Equivalent to BTNS_CHECKGROUP. Use TBSTYLE_CHECKGROUP for version 4.72 and earlier.
TBSTYLE_DROPDOWN | Equivalent to BTNS_DROPDOWN. Use TBSTYLE_DROPDOWN for version 4.72 and earlier.
TBSTYLE_GROUP | Equivalent to BTNS_GROUP. Use TBSTYLE_GROUP for version 4.72 and earlier.
TBSTYLE_NOPREFIX | Equivalent to BTNS_NOPREFIX. Use TBSTYLE_NOPREFIX for version 4.72 and earlier.
TBSTYLE_SEP | Equivalent to BTNS_SEP. Use TBSTYLE_SEP for version 4.72 and earlier.


Toolbar Extended Styles

A toolbar can have the following extended styles. To set an extended style, send the toolbar control a TB_SETEXTENDEDSTYLE message. To determine what extended styles are currently set, send a TB_GETEXTENDEDSTYLE message.

TBSTYLE_EX_DRAWDDARROWS
Version 4.71. This style allows buttons to have a separate dropdown arrow. Buttons that have the BTNS_DROPDOWN style will be drawn with a drop-down arrow in a separate section, to the right of the button. If the arrow is clicked, only the arrow portion of the button will depress, and the toolbar control will send a TBN_DROPDOWN notification to prompt the application to display the dropdown menu. If the main part of the button is clicked, the toolbar control sends a WM_COMMAND message with the button's ID. The application normally responds by launching the first command on the menu.

There are many situations where you may want to have only some of the dropdown buttons on a toolbar with separated arrows. To do so, set the TBSTYLE_EX_DRAWDDARROWS extended style. Give those buttons that will not have separated arrows the BTNS_WHOLEDROPDOWN style. Buttons with this style will have an arrow displayed next to the image. However, the arrow will not be separate and when any part of the button is clicked, the toolbar control will send a TBN_DROPDOWN notification. To prevent repainting problems, this style should be set before the toolbar control becomes visible.

TBSTYLE_EX_HIDECLIPPEDBUTTONS
Version 5.81. This style hides partially clipped buttons. The most common use of this style is for toolbars that are part of a rebar control. If an adjacent band covers part of a button, the button will not be displayed. However, if the rebar band has the RBBS_USECHEVRON style, the button will be displayed on the chevron's dropdown menu.
TBSTYLE_EX_MIXEDBUTTONS
Version 5.81. This style allows you to set text for all buttons, but only display it for those buttons with the BTNS_SHOWTEXT button style. The TBSTYLE_LIST style must also be set. Normally, when a button does not display text, your application must handle TBN_GETINFOTIP to display a ToolTip. With the TBSTYLE_EX_MIXEDBUTTONS extended style, text that is set but not displayed on a button will automatically be used as the button's ToolTip text. Your application only needs to handle TBN_GETINFOTIP if it needs more flexibility in specifying the ToolTip text.


Toolbar Button States

A toolbar button can have a combination of the following states:

TBSTATE_CHECKED | The button has the TBSTYLE_CHECK style and is being clicked.
TBSTATE_ELLIPSES | Version 4.70. The button's text is cut off and an ellipsis is displayed.
TBSTATE_ENABLED | The button accepts user input. A button that doesn't have this state is grayed.
TBSTATE_HIDDEN | The button is not visible and cannot receive user input.
TBSTATE_INDETERMINATE | The button is grayed.
TBSTATE_MARKED | Version 4.71. The button is marked. The interpretation of a marked item is dependent upon the application.
TBSTATE_PRESSED | The button is being clicked.
TBSTATE_WRAP | The button is followed by a line break. The button must also have the TBSTATE_ENABLED state.


Toolbar Standard Button Image Index Values

The following values specify index values of images within standard bitmaps. Use these values to specify an image index within a standard image list that was loaded with the TB_LOADIMAGES message.

The following index values correspond to images within standard image lists that the control creates for your convenience. The images depict actions that Windows applications commonly perform.

Index values for IDB_HIST_LARGE_COLOR and IDB_HIST_SMALL_COLOR:
HIST_ADDTOFAVORITES | Add to favorites.
HIST_BACK | Move back.
HIST_FAVORITES | Open favorites folder.
HIST_FORWARD | Move forward.
HIST_VIEWTREE | View tree.
Index values for IDB_STD_LARGE_COLOR and IDB_STD_SMALL_COLOR:
STD_COPY | Copy operation.
STD_CUT | Cut operation.
STD_DELETE | Delete operation.
STD_FILENEW | New file operation.
STD_FILEOPEN | Open file operation.
STD_FILESAVE | Save file operation.
STD_FIND | Find operation.
STD_HELP | Help operation.
STD_PASTE | Paste operation.
STD_PRINT | Print operation.
STD_PRINTPRE | Print preview operation.
STD_PROPERTIES | Properties operation.
STD_REDOW | Redo operation.
STD_REPLACE | Replace operation.
STD_UNDO | Undo operation.
Index values for IDB_VIEW_LARGE_COLOR and IDB_VIEW_SMALL_COLOR:
VIEW_DETAILS | Details view.
VIEW_LARGEICONS | Large icons view.
VIEW_LIST | List view.
VIEW_NETCONNECT | Connect to network drive.
VIEW_NETDISCONNECT | Disconnect from network drive.
VIEW_NEWFOLDER | New folder.
VIEW_PARENTFOLDER | Go to parent folder.
VIEW_SMALLICONS | Small icon view.
VIEW_SORTDATE | Sort by date.
VIEW_SORTNAME | Sort by name.
VIEW_SORTSIZE | Sort by size.
VIEW_SORTTYPE | Sort by type.


CreateMappedBitmap

Creates a bitmap for use in a toolbar.

HBITMAP CreateMappedBitmap(
    HINSTANCE hInstance,
    INT_PTR idBitmap,
    UINT wFlags,
    LPCOLORMAP lpColorMap,
    int iNumMaps
);

Parameters

hInstance
Handle to the module instance with the executable file that contains the bitmap resource.
idBitmap
Resource identifier of the bitmap resource.
wFlags
Bitmap flag. This parameter can be zero or the following value:
CMB_MASKED Uses a bitmap as a mask.
lpColorMap
Address of a COLORMAP structure that contains the color information needed to map the bitmaps. If this parameter is NULL, the function uses the default color map.
iNumMaps
Number of color maps pointed to by lpColorMap.

Return Values

Returns the handle to the bitmap if successful, or NULL otherwise. To retrieve extended error information, call GetLastError.

Remarks

The function creates a new bitmap using the bitmap data and colors specified by the bitmap resource and the color mapping information.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


CreateToolbarEx

Creates a toolbar window and adds the specified buttons to the toolbar.

HWND CreateToolbarEx(
    HWND hwnd,
    DWORD ws,
    UINT wID,
    int nBitmaps,
    HINSTANCE hBMInst,
    UINT_PTR wBMID,
    LPCTBBUTTON lpButtons,
    int iNumButtons,
    int dxButton,
    int dyButton,
    int dxBitmap,
    int dyBitmap,
    UINT uStructSize
);

Parameters

hwnd
Handle to the parent window for the toolbar.
ws
Window styles for the toolbar. This parameter must specify at least the WS_CHILD style. It can also include a combination of styles as discussed in Toolbar Control and Button Styles.
wID
Control identifier for the toolbar.
nBitmaps
Number of button images contained in the bitmap specified by hBMInst and wBMID.
hBMInst
Module instance with the executable file that contains the bitmap resource.
wBMID
Resource identifier for the bitmap resource. If hBMInst is NULL, this parameter must be a valid bitmap handle.
lpButtons
Address of an array of TBBUTTON structures that contain information about the buttons to add to the toolbar.
iNumButtons
Number of buttons to add to the toolbar.
dxButton
Width, in pixels, of the buttons to add to the toolbar.
dyButton
Height, in pixels, of the buttons to add to the toolbar.
dxBitmap
Width, in pixels, of the button images to add to the buttons in the toolbar.
dyBitmap
Height, in pixels, of the button images to add to the buttons in the toolbar.
uStructSize
Size of a TBBUTTON structure.

Return Values

Returns the window handle to the toolbar if successful, or NULL otherwise. To retrieve extended error information, call GetLastError.

Remarks

Windows 95: The system can support a maximum of 16,364 window handles.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


TB_ADDBITMAP

Adds one or more images to the list of button images available for a toolbar.

TB_ADDBITMAP
    wParam = (WPARAM) nButtons;
    lParam = (LPARAM) (LPTBADDBITMAP) lptbab;

Parameters

nButtons
Number of button images in the bitmap. If lptbab specifies a system-defined bitmap, this parameter is ignored.
lptbab
Address of a TBADDBITMAP structure that contains the identifier of a bitmap resource and the handle to the module instance with the executable file that contains the bitmap resource.

Return Values

Returns the index of the first new image if successful, or -1 otherwise.

Remarks

If the toolbar was created using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBITMAP.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ADDBUTTONS

Adds one or more buttons to a toolbar.

TB_ADDBUTTONS
    wParam = (WPARAM) (UINT) uNumButtons;
    lParam = (LPARAM) (LPTBBUTTON) lpButtons;

Parameters

uNumButtons
Number of buttons to add.
lpButtons
Address of an array of TBBUTTON structures that contain information about the buttons to add. There must be the same number of elements in the array as buttons specified by uNumButtons.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the toolbar was created using the CreateWindowEx function, you must send the TB_BUTTONSTRUCTSIZE message to the toolbar before sending TB_ADDBUTTONS.

See TB_SETIMAGELIST for a discussion of how to assign bitmaps to toolbar buttons from one or more image lists.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ADDSTRING

Adds a new string to the toolbar's string pool.

TB_ADDSTRING
    wParam = (WPARAM) (HINSTANCE) hinst;
    lParam = (LPARAM) MAKELONG(idString, 0);

Parameters

hinst
Handle to the module instance with an executable file that contains the string resource. If idString instead points to a character array with one or more strings, set this parameter to NULL.
idString
Resource identifier for the string resource. If hinst is set to NULL, idString points to a character array with one or more null-terminated strings. The last string in the array must be terminated with two null characters.

Return Values

Returns the index of the first new string if successful, or -1 otherwise.

Remarks

Buttons can use strings from the string pool for their display text. See Toolbar Controls for a discussion of how to use the string pool.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_AUTOSIZE

Causes a toolbar to be resized.

TB_AUTOSIZE
    wParam = 0;
    lParam = 0;

Return Values

No return value.

Remarks

An application sends the TB_AUTOSIZE message after causing the size of a toolbar to change either by setting the button or bitmap size or by adding strings for the first time.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_BUTTONCOUNT

Retrieves a count of the buttons currently in the toolbar.

TB_BUTTONCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the count of the buttons.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_BUTTONSTRUCTSIZE

Specifies the size of the TBBUTTON structure.

TB_BUTTONSTRUCTSIZE
    wParam = (WPARAM) cb;
    lParam = 0;

Parameters

cb
Size, in bytes, of the TBBUTTON structure.

Return Values

No return value.

Remarks

The system uses the size to determine which version of the common control dynamic-link library (DLL) is being used.

If an application uses the CreateWindowEx function to create the toolbar, the application must send this message to the toolbar before sending the TB_ADDBITMAP or TB_ADDBUTTONS message. The CreateToolbarEx function automatically sends TB_BUTTONSTRUCTSIZE, and the size of the TBBUTTON structure is a parameter of the function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_CHANGEBITMAP

Changes the bitmap for a button in a toolbar.

TB_CHANGEBITMAP
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELPARAM(iBitmap, 0);

Parameters

idButton
Command identifier of the button that is to receive a new bitmap.
iBitmap
Zero-based index of an image in the toolbar's image list. The system displays the specified image in the button. Set this member to I_IMAGECALLBACK, and the toolbar will send the TBN_GETDISPINFO notification to retrieve the image index when it is needed.

Version 5.81. Set this member to I_IMAGENONE to indicate that the button does not have an image. The button layout will not include any space for a bitmap, only text.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TB_CHECKBUTTON

Checks or unchecks a given button in a toolbar.

TB_CHECKBUTTON
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fCheck, 0);

Parameters

idButton
Command identifier of the button to check.
fCheck
Check flag. If this parameter is TRUE, the check is added. If it is FALSE, the check is removed.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a button is checked, it is displayed in the pressed state.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_COMMANDTOINDEX

Retrieves the zero-based index for the button associated with the specified command identifier.

TB_COMMANDTOINDEX
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier associated with the button.

Return Values

Returns the zero-based index for the button or -1 if the specified command identifier is invalid.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_CUSTOMIZE

Displays the Customize Toolbar dialog box.

TB_CUSTOMIZE
    wParam = 0;
    lParam = 0;

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_DELETEBUTTON

Deletes a button from the toolbar.

TB_DELETEBUTTON
    wParam = (WPARAM) iButton;
    lParam = 0;

Parameters

iButton
Zero-based index of the button to delete.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ENABLEBUTTON

Enables or disables the specified button in a toolbar.

TB_ENABLEBUTTON
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fEnable, 0);

Parameters

idButton
Command identifier of the button to enable or disable.
fEnable
Enable flag. If this parameter is TRUE, the button is enabled. If it is FALSE, the button is disabled.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a button has been enabled, it can be pressed and checked.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETANCHORHIGHLIGHT

Retrieves the anchor highlight setting for a toolbar.

TB_GETANCHORHIGHLIGHT
    wParam = 0;
    lParam = 0;

Return Values

Returns a Boolean value that indicates if anchor highlighting is set. If this value is nonzero, anchor highlighting is enabled. If this value is zero, it is disabled.

See Also

TB_SETANCHORHIGHLIGHT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETBITMAP

Retrieves the index of the bitmap associated with a button in a toolbar.

TB_GETBITMAP
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button whose bitmap index is to be retrieved.

Return Values

Returns the index of the bitmap if successful, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETBITMAPFLAGS

Retrieves the flags that describe the type of bitmap to be used.

TB_GETBITMAPFLAGS
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that describes the type of bitmap that should be used. If this return value has the TBBF_LARGE flag set, applications should use large bitmaps (24 x 24); otherwise, applications should use small bitmaps (16 x 16). All other bits are reserved.

Remarks

The value returned by TB_GETBITMAPFLAGS is only advisory. The toolbar control recommends large or small bitmaps based upon whether the user has chosen large or small fonts.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETBUTTON

Retrieves information about the specified button in a toolbar.

TB_GETBUTTON
    wParam = (WPARAM) iButton;
    lParam = (LPARAM) (LPTBBUTTON) lpButton;

Parameters

iButton
Zero-based index of the button for which to retrieve information.
lpButton
Address of the TBBUTTON structure that receives the button information.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETBUTTONINFO

Retrieves extended information for a button in a toolbar.

TB_GETBUTTONINFO
    wParam = (WPARAM)(INT) iID;
    lParam = (LPARAM)(LPTBBUTTONINFO) lptbbi;

Parameters

iID
Command identifier of the button.
lptbbi
Address of a TBBUTTONINFO structure that receives the button information. The cbSize and dwMask members of this structure must be filled in prior to sending this message.

Return Values

Returns the zero-based index of the button, or -1 if an error occurs.

Remarks

When you use TB_ADDBUTTONS or TB_INSERTBUTTON to place buttons on the toolbar, the button text is commonly specified by its string pool index. TB_GETBUTTONINFO will not retrieve this string. To use TB_GETBUTTONINFO to retrieve button text, you must first set the text string with TB_SETBUTTONINFO. Once you have set the button text with TB_SETBUTTONINFO, you can no longer use the string pool index.

See Also

TB_SETBUTTONINFO, TB_GETBUTTONTEXT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETBUTTONSIZE

Retrieves the current width and height of toolbar buttons, in pixels.

TB_GETBUTTONSIZE
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that contains the width and height values in the low word and high word, respectively.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETBUTTONTEXT

Retrieves the display text of a button on a toolbar.

TB_GETBUTTONTEXT
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) (LPTSTR) lpszText;

Parameters

idButton
Command identifier of the button whose text is to be retrieved.
lpszText
Address of a buffer that receives the button text.

Return Values

Returns the length, in characters, of the string pointed to by lpszText. The length does not include the terminating null character. If unsuccessful, the return value is -1.

Remarks

The returned string corresponds to the text that is currently displayed by the button.

See Also

TB_GETBUTTONINFO, TB_GETSTRING, TB_SETBUTTONINFO

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETCOLORSCHEME

Retrieves the color scheme information from the toolbar control.

TB_GETCOLORSCHEME
    wParam = 0;
    lParam = (LPARAM)(LPCOLORSCHEME) lpcs;

Parameters

lpcs
Address of a COLORSCHEME structure that will receive the color scheme information. You must set the cbSize member of this structure to sizeof(COLORSCHEME) before sending this message.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

TB_SETCOLORSCHEME

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETDISABLEDIMAGELIST

Retrieves the image list that a toolbar control uses to display disabled buttons.

TB_GETDISABLEDIMAGELIST
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the disabled image list, or NULL if no disabled image list is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETEXTENDEDSTYLE

Retrieves the extended styles for a toolbar control.

TB_GETEXTENDEDSTYLE
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD that represents the styles currently in use for the toolbar control. This value can be a combination of extended styles.

See Also

TB_SETEXTENDEDSTYLE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETHOTIMAGELIST

Retrieves the image list that a toolbar control uses to display hot buttons.

TB_GETHOTIMAGELIST
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the image list that the control uses to display hot buttons, or NULL if no hot image list is set.

Remarks

A button is hot when the cursor is over it. Toolbar controls must have the TBSTYLE_FLAT or TBSTYLE_LIST style to have hot items.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETHOTITEM

Retrieves the index of the hot item in a toolbar.

TB_GETHOTITEM
    wParam = 0;
    lParam = 0;

Return Values

Returns the index of the hot item, or -1 if no hot item is set. Toolbar controls that do not have the TBSTYLE_FLAT style do not have hot items.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETIMAGELIST

Retrieves the image list that a toolbar control uses to display buttons in their default state. A toolbar control uses this image list to display buttons when they are not hot or disabled.

TB_GETIMAGELIST
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the image list, or NULL if no image list is set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETINSERTMARK

Retrieves the current insertion mark for the toolbar.

TB_GETINSERTMARK
    wParam = 0;
    lParam = (LPARAM)(LPTBINSERTMARK)lptbim;

Parameters

lptbim
Address of a TBINSERTMARK structure that receives the insertion mark.

Return Values

Always returns TRUE.

See Also

TB_SETINSERTMARK

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETINSERTMARKCOLOR

Retrieves the color used to draw the insertion mark for the toolbar.

TB_GETINSERTMARKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that contains the current insertion mark color.

See Also

TB_SETINSERTMARKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETITEMRECT

Retrieves the bounding rectangle of a button in a toolbar.

TB_GETITEMRECT
    wParam = (WPARAM) iButton;
    lParam = (LPARAM) (LPRECT) lprc;

Parameters

iButton
Zero-based index of the button for which to retrieve information.
lprc
Address of a RECT structure that receives the coordinates of the bounding rectangle.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

This message does not retrieve the bounding rectangle for buttons whose state is set to the TBSTATE_HIDDEN value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETMAXSIZE

Retrieves the total size of all of the visible buttons and separators in the toolbar.

TB_GETMAXSIZE
    wParam = 0;
    lParam = (LPARAM)(LPSIZE)lpSize;

Parameters

lpSize
Address of a SIZE structure that receives the size of the items.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETOBJECT

Retrieves the IDropTarget for a toolbar control.

TB_GETOBJECT
    wParam = (WPARAM) (REFIID) iid;
    lParam = (LPARAM) (LPVOID*) ppvObject;

Parameters

iid
Identifier of the interface being requested. This value must point to IID_IDropTarget.
ppvObject
Address that receives the interface pointer. If an error occurs, a NULL pointer is placed in this address.

Return Values

Returns an HRESULT value indicating success or failure of the operation.

Remarks

The toolbar's IDropTarget is used by the toolbar when objects are dragged over or dropped onto it.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETPADDING

Retrieves the padding for a toolbar control.

TB_GETPADDING
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that contains the horizontal padding in the low word and the vertical padding in the high word, in pixels.

See Also

TB_SETPADDING

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_GETRECT

Retrieves the bounding rectangle for a specified toolbar button.

TB_GETRECT
    wParam = (WPARAM)(INT) iID;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

iID
Button identifier.
lprc
Address of a RECT structure that will receive the bounding rectangle information.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETROWS

Retrieves the number of rows of buttons in a toolbar with the TBSTYLE_WRAPABLE style.

TB_GETROWS
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of rows.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETSTATE

Retrieves information about the state of the specified button in a toolbar, such as whether it is enabled, pressed, or checked.

TB_GETSTATE
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button for which to retrieve information.

Return Values

Returns the button state information if successful, or -1 otherwise. The button state information can be a combination of the values listed in Toolbar Button States.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETSTRING

Retrieves a string from a toolbar's string pool.

TB_GETSTRING
    HIWORD (wParam) = iString;
    LOWORD (wParam) = cchMax;
    lParam = (LPARAM)(LPTSTR) pszString;

Parameters

iString
Index of the string.
cchMax
Length of the pszText buffer in bytes.
pszString
Pointer to a buffer used to return the string.

Return Values

Returns the string length if successful, or -1 otherwise.

Remarks

This message returns the specified string from the toolbar's string pool. It does not necessarily correspond to the text string currently being displayed by a button. To retrieve a button's current text string, send the toolbar a TB_GETBUTTONTEXT message.

See Also

TB_ADDSTRING, TB_ADDBUTTONS, TB_INSERTBUTTON

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TB_GETSTYLE

Retrieves the styles currently in use for a toolbar control.

TB_GETSTYLE
    wParam = 0;
    lParam = 0;

Return Values

Returns a DWORD value that is a combination of toolbar control styles.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETTEXTROWS

Retrieves the maximum number of text rows that can be displayed on a toolbar button.

TB_GETTEXTROWS
    wParam = 0;
    lParam = 0;

Return Values

Returns an INT value representing the maximum number of text rows that the control will display for a button.

See Also

TB_SETMAXTEXTROWS

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_GETTOOLTIPS

Retrieves the handle to the ToolTip control, if any, associated with the toolbar.

TB_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the ToolTip control, or NULL if the toolbar has no associated ToolTip.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control.

TB_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

TB_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_HIDEBUTTON

Hides or shows the specified button in a toolbar.

TB_HIDEBUTTON
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fShow, 0);

Parameters

idButton
Command identifier of the button to hide or show.
fShow
Show flag. If this parameter is TRUE, the button is hidden. If it is FALSE, the button is shown.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_HITTEST

Determines where a point lies in a toolbar control.

TB_HITTEST
    wParam = 0;
    lParam = (LPARAM)(LPPOINT)pptHitTest;

Parameters

pptHitTest
Address of a point structure that contains the x-coordinate of the hit test in the x member and the y-coordinate of the hit test in the y member. The coordinates are relative to the toolbar's client area.

Return Values

Returns an integer value. If the return value is zero or a positive value, it is the zero-based index of the nonseparator item in which the point lies.

If the return value is negative, the point does not lie within a button. The absolute value of the return value is the index of a separator item or the nearest nonseparator item.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_INDETERMINATE

Sets or clears the indeterminate state of the specified button in a toolbar.

TB_INDETERMINATE
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fIndeterminate, 0);

Parameters

idButton
Command identifier of the button whose indeterminate state is to be set or cleared.
fIndeterminate
Indeterminate flag. If this parameter is TRUE, the indeterminate state is set. If it is FALSE, the state is cleared.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_INSERTBUTTON

Inserts a button in a toolbar.

TB_INSERTBUTTON
    wParam = (WPARAM) iButton;
    lParam = (LPARAM) (LPTBBUTTON) lpButton;

Parameters

iButton
Zero-based index of a button. The message inserts the new button to the left of this button.
lpButton
Address of a TBBUTTON structure containing information about the button to insert.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_INSERTMARKHITTEST

Retrieves the insertion mark information for a point in a toolbar.

TB_INSERTMARKHITTEST
    wParam = (WPARAM)(LPPOINT)lppt;
    lParam = (LPARAM)(LPTBINSERTMARK)lptbim;

Parameters

lppt
Address of a POINT structure that contains the hit test coordinates, relative to the client area of the toolbar.
lptbim
Address of a TBINSERTMARK structure that receives the insertion mark information.

Return Values

Returns nonzero if the point is an insertion mark, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_ISBUTTONCHECKED

Determines whether the specified button in a toolbar is checked.

TB_ISBUTTONCHECKED
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Returns nonzero if the button is checked, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ISBUTTONENABLED

Determines whether the specified button in a toolbar is enabled.

TB_ISBUTTONENABLED
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Returns nonzero if the button is enabled, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ISBUTTONHIDDEN

Determines whether the specified button in a toolbar is hidden.

TB_ISBUTTONHIDDEN
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Returns nonzero if the button is hidden, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ISBUTTONHIGHLIGHTED

Checks the highlight state of a toolbar button.

TB_ISBUTTONHIGHLIGHTED
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier for a toolbar button.

Return Values

Returns nonzero if the button is highlighted, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_ISBUTTONINDETERMINATE

Determines whether the specified button in a toolbar is indeterminate.

TB_ISBUTTONINDETERMINATE
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Returns nonzero if the button is indeterminate, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_ISBUTTONPRESSED

Determines whether the specified button in a toolbar is pressed.

TB_ISBUTTONPRESSED
    wParam = (WPARAM) idButton;
    lParam = 0;

Parameters

idButton
Command identifier of the button.

Return Values

Returns nonzero if the button is pressed, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_LOADIMAGES

Loads system-defined button images into a toolbar control's image list.

TB_LOADIMAGES
    wParam = (WPARAM)(INT) iBitmapID;
    lParam = (LPARAM)(HINSTANCE) hinst;

Parameters

iBitmapID
Identifier of a system-defined button image list. This parameter can be set to one of the following values.
IDB_HIST_LARGE_COLOR | Microsoft® Windows® Explorer bitmaps in large size.
IDB_HIST_SMALL_COLOR | Microsoft® Windows® Explorer bitmaps in small size.
IDB_STD_LARGE_COLOR | Standard bitmaps in large size.
IDB_STD_SMALL_COLOR | Standard bitmaps in small size.
IDB_VIEW_LARGE_COLOR | View bitmaps in large size.
IDB_VIEW_SMALL_COLOR | View bitmaps in small size.
hinst
Instance handle. This parameter must be set to HINST_COMMCTRL.

Return Values

Returns an INT value that represents the count of images in the image list, not including the one just added. Returns zero if the toolbar has no image list or if the existing image list is empty.

Remarks

You must use the proper image index values when you prepare TBBUTTON structures prior to sending the TB_ADDBUTTONS message. For a list of image index values for these preset bitmaps, see Toolbar Standard Button Image Index Values.

See Also

TB_ADDBITMAP

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_MAPACCELERATOR

Determines the ID of the button that corresponds to the specified accelerator character.

TB_MAPACCELERATOR
    wParam = (WPARAM)(TCHAR) chAccel;
    lParam = (LPARAM)(LPUINT) pIDBtn;

Parameters

chAccel
[in] The accelerator character.
pIDBtn
[out] Pointer to a UINT. On return, if successful, this parameter will hold the id of the button that has chAccel as its accelerator character.

Return Values

Returns a nonzero value if one of the buttons has chAccel as its accelerator character, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_MARKBUTTON

Sets the highlight state of a given button in a toolbar control.

TB_MARKBUTTON
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fHighlight,0);

Parameters

idButton
Command identifier for a toolbar button.
fHighlight
Value that specifies the highlight state to be set. If this value is TRUE, the button is highlighted. If it's FALSE, the button is set to its default state.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_MOVEBUTTON

Moves a button from one index to another.

TB_MOVEBUTTON
    wParam = (WPARAM)(UINT)uOldPos;
    lParam = (LPARAM)(UINT)uNewPos;

Parameters

uOldPos
Zero-based index of the button to be moved.
uNewPos
Zero-based index where the button will be moved.

Return Values

Returns nonzero if successful, or zero otherwise.

See Also

TB_SETANCHORHIGHLIGHT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_PRESSBUTTON

Presses or releases the specified button in a toolbar.

TB_PRESSBUTTON
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fPress, 0);

Parameters

idButton
Command identifier of the button to press or release.
fPress
Press flag. If this parameter is TRUE, the button is pressed. If it is FALSE, the button is released.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_REPLACEBITMAP

Replaces an existing bitmap with a new bitmap.

TB_REPLACEBITMAP
    wParam = 0;
    lParam = (LPARAM) (LPTBREPLACEBITMAP) ptbrb;

Parameters

ptbrb
Address of a TBREPLACEBITMAP structure that contains the information of the bitmap to be replaced and the new bitmap.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SAVERESTORE

Send this message to initiate saving or restoring a toolbar state.

TB_SAVERESTORE
    wParam = (WPARAM) (BOOL) fSave;
    lParam = (LPARAM)  (TBSAVEPARAMS *)ptbsp;

Parameters

fSave
Save or restore flag. If this parameter is TRUE, the information is saved. If it is FALSE, the information is restored.
ptbsp
Address of a TBSAVEPARAMS structure that specifies the registry key, subkey, and value name for the toolbar state information.

Return Values

No return value.

Remarks

For version 4.72 and earlier, to use this message to save or restore a toolbar, the parent window of the toolbar control must implement a handler for the TBN_GETBUTTONINFO notification message. The toolbar issues this notification to retrieve information about each button as it is restored.

Version 5.80 includes a new save/restore option. At the beginning of the process, and as each button is saved or restored, your application will receive a TBN_SAVE or TBN_RESTORE notification. To use this option, you must implement notification handlers to provide the Shell with the bitmap and state information it needs to successfully save or restore the toolbar state. See Saving and Restoring Toolbar States for a detailed explanation of how to handle TBN_SAVE and TBN_RESTORE.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TB_SETANCHORHIGHLIGHT

Sets the anchor highlight setting for a toolbar.

TB_SETANCHORHIGHLIGHT
    wParam = (WPARAM)(BOOL) fAnchor;
    lParam = 0;

Parameters

fAnchor
Boolean value that specifies if anchor highlighting is enabled or disabled. If this value is nonzero, anchor highlighting will be enabled. If this value is zero, anchor highlighting will be disabled.

Return Values

Returns the previous anchor highlight setting. If this value is nonzero, anchor highlighting was enabled. If this value is zero, anchor highlighting was disabled.

Remarks

Anchor highlighting in a toolbar means that the last highlighted item will remain highlighted until another item is highlighted. This occurs even if the cursor leaves the toolbar control.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETBITMAPSIZE

Sets the size of the bitmapped images to be added to a toolbar.

TB_SETBITMAPSIZE
    wParam = 0;
    lParam = (LPARAM) MAKELONG(dxBitmap, dyBitmap)

Parameters

dxBitmap
Width, in pixels, of the bitmapped images.
dyBitmap
Height, in pixels, of the bitmapped images.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The size can be set only before adding any bitmaps to the toolbar. If an application does not explicitly set the bitmap size, the size defaults to 16 by 15 pixels.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETBUTTONINFO

Sets the information for an existing button in a toolbar.

TB_SETBUTTONINFO
    wParam = (WPARAM)(INT) iID;
    lParam = (LPARAM)(LPTBBUTTONINFO) lptbbi;

Parameters

iID
Button identifier.
lptbbi
Address of a TBBUTTONINFO structure that contains the new button information. The cbSize and dwMask members of this structure must be filled in prior to sending this message.

Return Values

Returns nonzero if successful, or zero otherwise.

Remarks

Text is commonly assigned to buttons when they are added to a toolbar by specifying the index of a string in the toolbar's string pool. If you use a TB_SETBUTTONINFO to assign new text to a button, it will permanently override the text from the string pool. You can change the text by calling TB_SETBUTTONINFO again, but you cannot reassign the string from the string pool.

See Also

TB_ADDBUTTONS, TB_GETBUTTONINFO, TB_GETBUTTONTEXT, TB_GETSTRING, TB_INSERTBUTTON

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETBUTTONSIZE

Sets the size of the buttons to be added to a toolbar.

TB_SETBUTTONSIZE
    wParam = 0;
    lParam = (LPARAM) MAKELONG(dxButton, dyButton)

Parameters

dxButton
Width, in pixels, of the buttons.
dyButton
Height, in pixels, of the buttons.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The size can be set only before adding any buttons to the toolbar. If an application does not explicitly set the button size, the size defaults to 24 by 22 pixels.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETBUTTONWIDTH

Sets the minimum and maximum button widths in the toolbar control.

TB_SETBUTTONWIDTH
    wParam = 0;
    lParam = (LPARAM)(DWORD) MAKELONG(cxMin,cxMax);

Parameters

cxMin
Minimum button width, in pixels. Toolbar buttons will never be narrower than this value.
cxMax
Maximum button width, in pixels. If button text is too wide, the control displays it with ellipsis points.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETCMDID

Sets the command identifier of a toolbar button.

TB_SETCMDID
    wParam = (WPARAM) (UINT) index;
    lParam = (WPARAM) (UINT) cmdId;

Parameters

index
Zero-based index of the button whose command identifier is to be set.
cmdId
Command identifier.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETCOLORSCHEME

Sets the color scheme information for the toolbar control.

TB_SETCOLORSCHEME
    wParam = 0;
    lParam = (LPARAM)(LPCOLORSCHEME) lpcs;

Parameters

lpcs
Address of a COLORSCHEME structure that contains the color scheme information.

Return Values

The return value for this message is not used.

Remarks

The toolbar control uses the color scheme information when drawing the 3-D elements in the control.

See Also

TB_GETCOLORSCHEME

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETDISABLEDIMAGELIST

Sets the image list that the toolbar control will use to display disabled buttons.

TB_SETDISABLEDIMAGELIST
    wParam = 0;
    lParam = (LPARAM)(HIMAGELIST) himlNewDisabled;

Parameters

himlNewDisabled
Handle to the image list that will be set.

Return Values

Returns the handle to the image list previously used to display disabled buttons, or NULL if no image list was previously set.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETDRAWTEXTFLAGS

Sets the text drawing flags for the toolbar.

TB_SETDRAWTEXTFLAGS
    wParam = (WPARAM)(DWORD) dwMask;
    lParam = (LPARAM)(DWORD) dwDTFlags;

Parameters

dwMask
One or more of the DT_ flags, specified in DrawText, that indicate which bits in dwDTFlags will be used when drawing the text.
dwDTFlags
One or more of the DT_ flags, specified in DrawText, that indicate how the button text will be drawn. This value will be passed to the DrawText API when the button text is drawn.

Return Values

Returns the previous text drawing flags.

Remarks

The dwMask parameter allows you to specify which flags will be used when drawing the text, even if these flags are turned off. For example, if you don't want the DT_CENTER flag used when drawing text, you would add the DT_CENTER flag to dwMask and not specify the DT_CENTER flag in dwDTFlags. This prevents the control from passing the DT_CENTER flag to the DrawText API.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETEXTENDEDSTYLE

Sets the extended styles for a toolbar control.

TB_SETEXTENDEDSTYLE
    wParam = 0;
    lParam = (LPARAM)(DWORD)dwExStyle;

Parameters

dwExStyle
Value specifying the new extended styles. This parameter can be a combination of extended styles.

Return Values

Returns a DWORD that represents the previous extended styles. This value can be a combination of extended styles.

See Also

TB_GETEXTENDEDSTYLE

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETHOTIMAGELIST

Sets the image list that the toolbar control will use to display hot buttons.

TB_SETHOTIMAGELIST
    wParam = 0;
    lParam = (LPARAM)(HIMAGELIST) himlNewHot;

Parameters

himlNewHot
Handle to the image list that will be set.

Return Values

Returns the handle to the image list previously used to display hot buttons, or NULL if no image list was previously set.

Remarks

A button is hot when the cursor is over it. Toolbar controls must have the TBSTYLE_FLAT or TBSTYLE_LIST style to have hot items.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETHOTITEM

Sets the hot item in a toolbar. This message is ignored for toolbar controls that do not have the TBSTYLE_FLAT style.

TB_SETHOTITEM
    wParam = (WPARAM)(INT)iHot;
    lParam = 0;

Parameters

iHot
Index of the item that will be made hot. If this value is -1, none of the items will be hot.

Return Values

Returns the index of the previous hot item, or -1 if there was no hot item.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETIMAGELIST

Sets the image list that the toolbar will use to display buttons that are in their default state.

TB_SETIMAGELIST
    wParam = 0;
    --or--
    wParam = (WPARAM) (INT) iImageID; //Version 5.80

    lParam = (LPARAM)(HIMAGELIST) himlNew;

Parameters

iImageID
Version 5.80. The index of the list. If you are using only one image list, or an earlier version of the common controls, set iImageID to zero. See the Remarks for details on using multiple image lists.
himlNew
Handle to the image list that will be set. If this parameter is NULL, no images will be displayed in the buttons.

Return Values

Returns the handle to the image list previously used to display buttons in their default state, or NULL if no image list was previously set.

Example

The following code fragment illustrates how to add five buttons to a toolbar, with images from three different image lists. Support for multiple image lists is enabled with a CCM_SETVERSION message. The image lists are then set and assigned IDs of 0-2. The buttons are assigned images from the image lists as follows:

  • Button 0 is from image list zero (ahim[0]) with index of 1.
  • Button 1 is from image list one (ahim[1]) with an index of 1.
  • Button 2 is from image list two (ahim[2]) with an index of 1.
  • Button 3 is from image list zero (ahim[0]) with an index of 2.
  • Button 4 is from image list one (ahim[1]) with an index of 3.

Finally, the buttons are added to the toolbar control with a TB_ADDBUTTONS message. See Remarks for further discussion of the procedure.

    //Enable multiple image lists
    SendMessage(hwndTB, CCM_SETVERSION, (WPARAM) 5, 0);

    //Set the image lists and assign them IDs of 0-2
    SendMessage(hwndTB, TB_SETIMAGELIST, 0, (LPARAM)ahiml[0]);
    SendMessage(hwndTB, TB_SETIMAGELIST, 1, (LPARAM)ahiml[1]);
    SendMessage(hwndTB, TB_SETIMAGELIST, 2, (LPARAM)ahiml[2]);

    // Create the five buttons
    TBBUTTON rgtb[5];

    //... initialize the TBBUTTON structures as usual ...

    //Assign images to each button
    rgtb[0].iBitmap = MAKELONG(1, 0);
    rgtb[1].iBitmap = MAKELONG(1, 1);
    rgtb[2].iBitmap = MAKELONG(1, 2);
    rgtb[3].iBitmap = MAKELONG(2, 0);
    rgtb[4].iBitmap = MAKELONG(3, 1);

    // add the five buttons to the toolbar control
    SendMessage(hwndTB, TB_ADDBUTTONS, 5, (LPARAM)&rgtb);

Remarks

Note: Your application is responsible for freeing the image list after the toolbar is destroyed.

This message cannot be combined with TB_ADDBITMAP. It also cannot be used with toolbars created with CreateToolbarEx, which calls TB_ADDBITMAP internally. When you create a toolbar with CreateToolbarEx or use TB_ADDBITMAP to add images, the toolbar manages the image list internally. Attempting to modify it with TB_SETIMAGELIST will have unpredictable consequences.

With version 5.80 and later of the common controls, button images need not come from the same image list. To use multiple image lists for your toolbar button images:

  1. Enable multiple image lists by sending the toolbar control a CCM_SETVERSION message with iVersion set to 5.
  2. For each image list you wish to use, send the toolbar control a TB_SETIMAGELIST message. Set wParam to an application-defined iImageID value that will be used to identify the list. Set lParam to the list's HIMAGELIST handle.
  3. For each button, set the iBitmap member of the button's TBBUTTON structure to MAKELONG(iIndex, iImageID). The iImageId value is the ID of the appropriate image list that was defined in step two. The iIndex value is the index of the particular image within that list.
  4. Add the buttons by sending the toolbar control a TB_ADDBUTTONS message.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETINDENT

Sets the indentation for the first button in a toolbar control.

TB_SETINDENT
    wParam = (WPARAM)(INT) iIndent;
    lParam = 0;

Parameters

iIndent
Value specifying the indentation, in pixels.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETINSERTMARK

Sets the current insertion mark for the toolbar.

TB_SETINSERTMARK
    wParam = 0;
    lParam = (LPARAM)(LPTBINSERTMARK)lptbim;

Parameters

lptbim
Address of a TBINSERTMARK structure that contains the insertion mark.

Return Values

The return value for this message is not used.

See Also

TB_GETINSERTMARK

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETINSERTMARKCOLOR

Sets the color used to draw the insertion mark for the toolbar.

TB_SETINSERTMARKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrInsertMark;

Parameters

clrInsertMark
COLORREF value that contains the new insertion mark color.

Return Values

Returns a COLORREF value that contains the previous insertion mark color.

See Also

TB_GETINSERTMARKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETMAXTEXTROWS

Sets the maximum number of text rows displayed on a toolbar button.

TB_SETMAXTEXTROWS
    wParam = (WPARAM)(INT) iMaxRows;
    lParam = 0;

Parameters

iMaxRows
Maximum number of rows of text that can be displayed.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETPADDING

Sets the padding for a toolbar control.

TB_SETPADDING
    wParam = 0;
    lParam = MAKELPARAM(cx, cy);

Parameters

cx
The horizontal padding, in pixels.
cy
The vertical padding, in pixels.

Return Values

Returns a DWORD value that contains the previous horizontal padding in the low word and the previous vertical padding in the high word, in pixels.

Remarks

The padding values are used to create a blank area between the edge of the button and the button's image and/or text. The horizontal padding value is applied to both the right and left of the button, and the vertical padding value is applied to both the top and bottom of the button. Padding is only applied to buttons that have the TBSTYLE_AUTOSIZE style.

See Also

TB_GETPADDING

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TB_SETPARENT

Sets the window to which the toolbar control sends notification messages.

TB_SETPARENT
    wParam = (WPARAM) (HWND) hwndParent;
    lParam = 0;

Parameters

hwndParent
Handle to the window to receive notification messages.

Return Values

The return value is a handle to the previous notification window, or NULL if there is no previous notification window.

Remarks

The TB_SETPARENT message does not change the parent window that was specified when the control was created. Calling the GetParent function for a toolbar control will return the actual parent window, not the window specified in TB_SETPARENT. To change the control's parent window, call the SetParent function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETROWS

Sets the number of rows of buttons in a toolbar.

TB_SETROWS
    wParam = (WPARAM) MAKEWPARAM(cRows, fLarger);
    lParam = (LPARAM) (LPRECT) lprc;

Parameters

cRows
Number of rows requested. The minimum number of rows is one, and the maximum number of rows is equal to the number of buttons in the toolbar.
fLarger
Flag that indicates whether to create more rows than requested when the system cannot create the number of rows specified by cRows. If this parameter is TRUE, the system creates more rows. If it is FALSE, the system creates fewer rows.
lprc
Address of a RECT structure that receives the bounding rectangle of the toolbar after the rows are set.

Return Values

No return value.

Remarks

Because the system does not break up button groups when setting the number of rows, the resulting number of rows might differ from the number requested.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETSTATE

Sets the state for the specified button in a toolbar.

TB_SETSTATE
    wParam = (WPARAM) idButton;
    lParam = (LPARAM) MAKELONG(fState, 0);

Parameters

idButton
Command identifier of the button.
fState
State flags. This parameter can be a combination of the values listed in Toolbar Button States.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETSTYLE

Sets the style for a toolbar control.

TB_SETSTYLE
    wParam = 0;
    lParam = (LPARAM)(DWORD) dwStyle;

Parameters

dwStyle
Value specifying the styles to be set for the control. This value can be a combination of toolbar control styles.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TB_SETTOOLTIPS

Associates a ToolTip control with a toolbar.

TB_SETTOOLTIPS
    wParam = (WPARAM) (HWND) hwndToolTip;
    lParam = 0;

Parameters

hwndToolTip
Handle to the ToolTip control.

Return Values

No return value.

Remarks

Any buttons added to a toolbar before sending the TB_SETTOOLTIPS message will not be registered with the ToolTip control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TB_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

TB_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

TB_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CHAR (toolbar)

Sent by the toolbar when it receives a WM_CHAR message. This notification message is sent in the form of a WM_NOTIFY message.

NM_CHAR
    lpnmc = (LPNMCHAR) lParam;

Return Values

Returns TRUE to indicate that the toolbar should not process the character and FALSE to have the toolbar process the character.

lpnmc
Pointer to an NMCHAR structure that contains additional information about the character that caused the notification message. The dwItemPrev member of this structure contains the command identifier of the item that is currently hot or -1 if no item is currently hot. The dwItemNext member of this structure contains the command identifier of the item that will become hot or -1 if the key does not match any item's accelerator.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (toolbar)

Sent by the toolbar to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMTBCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Version 4.70. Address of an NMCUSTOMDRAW structure that contains information about the drawing operation. The dwItemSpec member of this structure contains the command identifier of the item being drawn. The lItemlParam member of this structure contains the dwData value for the item being drawn.

Version 4.71. Address of an NMTBCUSTOMDRAW structure that contains information about the drawing operation. The dwItemSpec member of the nmcd member of this structure contains the command identifier of the item being drawn. The lItemlParam member of the nmcd member of this structure contains the dwData value for the item being drawn.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:
CDRF_DODEFAULT
The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW
The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE
The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE
The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT
The control will notify the parent after painting an item.
CDRF_NOTIFYSUBITEMDRAW
Version 4.71. The control will notify the parent when a list-view subitem is being drawn.

When dwDrawStage equals CDDS_ITEMPREPAINT:
CDRF_NEWFONT
Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing fonts and colors.
CDRF_SKIPDEFAULT
Your application drew the item manually. The control will not draw the item.
TBCDRF_NOEDGES
Version 4.71. Don't draw button edges.
TBCDRF_HILITEHOTTRACK
Version 4.71. Use the clrHighlightHotTrack member of the NMTBCUSTOMDRAW structure to drawing the background of hot-tracked items.
TBCDRF_NOOFFSET
Version 4.71. Don't offset button when pressed.
TBCDRF_NOMARK
Version 4.71. Don't draw default highlight of items that have the TBSTATE_MARKED state.
TBCDRF_NOETCHEDEFFECT
Version 4.71. Don't draw etched effect for disabled items.

See Also

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_KEYDOWN (toolbar)

Sent by a control when the control has the keyboard focus and the user presses a key. This notification message is sent in the form of a WM_NOTIFY message.

NM_KEYDOWN
    lpnmk = (LPNMKEY) lParam;

Parameters

lpnmk
Address of an NMKEY structure that contains additional information about the key that caused the notification message.

Return Values

Return nonzero to prevent the control from processing the key, or zero otherwise.

Remarks

Currently, only the toolbar control sends this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_LDOWN (toolbar)

NM_LDOWN

Notifies a toolbar's parent window that the left mouse button has been pressed.

NM_LDOWN
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

No return value.

Remarks

This notification is sent after the WM_COMMAND or TBN_DROPDOWN notification has been sent.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


NM_RCLICK (toolbar)

Sent by a toolbar control when the user clicks the toolbar with the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnmmouse = (LPNMMOUSE) lParam;

Parameters

lpnmmouse
Address of an NMMOUSE structure that contains information about this notification. If the mouse was clicked on a toolbar item, the dwItemSpec member contains the item identifier and the dwItemData member contains the item data. If the mouse was clicked on a separator or white space in the toolbar, the dwItemSpec member will contain -1.

Return Values

Returns FALSE to allow the toolbar control to perform default processing of the event, or TRUE to prevent the control from processing the event.

Remarks

This notification is identical to the standard NM_RCLICK notification except that the toolbar supplies an NMMOUSE structure instead of an NMHDR structure for the lParam.

Version 4.71. Prior versions send a standard NM_RCLICK message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RDBLCLK (toolbar)

Notifies a control's parent window that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.

NM_RDBLCLK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Returns FALSE to allow the toolbar control to perform default processing of the event, or TRUE to prevent the control from processing the event.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (toolbar)

Notifies a toolbar control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_TOOLTIPSCREATED (toolbar)

Notifies a toolbar's parent window that the toolbar has created a ToolTip control. This notification is sent in the form of a WM_NOTIFY message.

NM_TOOLTIPSCREATED
    lpnmttc = (LPNMHDR) lParam;

Parameters

lpnmttc
Address of an NMTOOLTIPSCREATED structure that contains additional information about this notification message.

Return Value

The toolbar control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBN_BEGINADJUST

Notifies a toolbar's parent window that the user has begun customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_BEGINADJUST
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_BEGINDRAG

Notifies a toolbar's parent window that the user has begun dragging a button in a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_BEGINDRAG
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure. The iItem member contains the command identifier of the button being dragged.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_CUSTHELP

Notifies a toolbar's parent window that the user has chosen the Help button in the Customize Toolbar dialog box. This message is sent in the form of a WM_NOTIFY message.

TBN_CUSTHELP
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_DELETINGBUTTON

Sent by a toolbar control when a button is about to be deleted.

 TBN_DELETINGBUTTON
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure that contains information about the button being deleted. For this notification message, only the hdr and iItem members of this structure are valid. The iItem member of this structure contains the command identifier of the button being deleted.

Return Values

The return value is ignored.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBN_DRAGOUT

Sent by a toolbar control when the user clicks a button and then moves the cursor off the button. This notification message is sent in the form of a WM_NOTIFY message.

TBN_DRAGOUT
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure that contains information about this notification. For this notification message, only the hdr and iItem members of this structure are valid. The iItem member of this structure contains the command identifier of the button being dragged.

Return Values

The return value is ignored.

Remarks

This notification allows an application to implement drag-and-drop functionality for toolbar buttons. When processing this notification, the application will begin the drag-and-drop operation.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBN_DROPDOWN

Sent by a toolbar control when the user clicks a dropdown button. This notification message is sent in the form of a WM_NOTIFY message.

TBN_DROPDOWN
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure that contains information about this notification. For this notification message, only the hdr and iItem members of this structure are valid.

Return Values

Returns one of the following values:

Value | Description
TBDDRET_DEFAULT | The drop-down was handled.
TBDDRET_NODEFAULT | The drop-down was not handled.
TBDDRET_TREATPRESSED | The drop-down was handled, but treat the button like a regular button.

Remarks

Note: Dropdown buttons can be plain (BTNS_DROPDOWN style), display an arrow next to the button image (BTNS_WHOLEDROPDOWN style), or display an arrow that is separated from the image (TBSTYLE_EX_DRAWDDARROWS style). If a separated arrow is used, TBN_DROPDOWN is sent only if the user clicks the arrow portion of the button. If the user clicks the main part of the button, a WM_COMMAND message with button's ID is sent, just as with a standard button. For the other two styles of dropdown button, TBN_DROPDOWN is sent when the user clicks any part of the button.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBN_ENDADJUST

Notifies a toolbar's parent window that the user has stopped customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_ENDADJUST
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_ENDDRAG

Notifies the toolbar's parent window that the user has stopped dragging a button in a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_ENDDRAG
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure. The iItem member contains the command identifier of the button being dragged.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_GETBUTTONINFO

Retrieves toolbar customization information and notifies the toolbar's parent window of any changes being made to the toolbar. This is sent in the form of a WM_NOTIFY message.

TBN_GETBUTTONINFO
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure. The iItem member specifies a zero-based index that provides a count of the buttons the Customize Toolbar dialog box displays as both available and present on the toolbar.

The pszText member specifies the address of the current button text, and cchText specifies its length in characters. The application should fill the structure with information about the button.

Return Values

Returns TRUE if button information was copied to the specified structure, or FALSE otherwise.

Remarks

The toolbar control allocates a buffer, and the receiver (parent window) must copy the text into that buffer. The cchText member contains the length of the buffer allocated by the toolbar when TBN_GETBUTTONINFO is sent to the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_GETDISPINFO

Retrieves display information for a toolbar item. This notification is sent in the form of a WM_NOTIFY message.

TBN_GETDISPINFO
    lptbdi = (LPNMTBDISPINFO) lParam;

Parameters

lptbdi
Address of an NMTBDISPINFO structure. The idCommand member specifies the item's command identifier, the lParam member contains the item's application-defined data, and the dwMask member specifies what information is being requested.

Return Values

The return value is ignored by the control.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_GETINFOTIP

Retrieves infotip information for a toolbar item. This notification is sent in the form of a WM_NOTIFY message.

TBN_GETINFOTIP
    lptbgit = (LPNMTBGETINFOTIP) lParam;

Parameters

lptbgit
Address of an NMTBGETINFOTIP structure that contains item information and receives infotip information.

Return Values

The return value is ignored by the control.

Remarks

The infotip support in the toolbar allows the toolbar to display ToolTips for items that are as large as INFOTIPSIZE characters. If this notification is not processed, the toolbar will use the item's text for the infotip.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBN_GETOBJECT

Sent by a toolbar control that uses the TBSTYLE_REGISTERDROP style to request a drop target object when the pointer passes over one of its buttons.

TBN_GETOBJECT
    lpnmon = (LPNMOBJECTNOTIFY) lParam;

Parameters

lpnmon
Address of an NMOBJECTNOTIFY structure that contains information about the button that the pointer passed over and receives data the application provides in response to this message.

Return Values

The application processing this notification must return zero.

Remarks

To provide an object, an application must set values in some members of the NMOBJECTNOTIFY structure at lpnmon. The pObject member must be set to a valid object pointer, and the hResult member must be set to a success flag. To comply with Component Object Model (COM) standards, always increment the object's reference count when providing an object pointer.

If an application does not provide an object, it must set pObject to NULL and hResult to a failure flag.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBN_HOTITEMCHANGE

Sent by a toolbar control when the hot (highlighted) item changes. This notification message is sent in the form of a WM_NOTIFY message.

TBN_HOTITEMCHANGE
    lpnmhi = (LPNMTBHOTITEM) lParam;

Parameters

lpnmhi
Address of an NMTBHOTITEM structure that contains information about this notification.

Return Values

Return zero to allow the item to be highlighted, or nonzero to prevent the item from being highlighted.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBN_INITCUSTOMIZE

Notifies a toolbar's parent window that customizing has started.

TBN_INITCUSTOMIZE
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of the toolbar's NMHDR structure.

Return Values

Returns TBNRF_HIDEHELP to suppress the Help button.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TBN_QUERYDELETE

Notifies the toolbar's parent window whether a button may be deleted from a toolbar while the user is customizing the toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_QUERYDELETE
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure. The iItem member contains the zero-based index of the button to be deleted.

Return Values

Returns TRUE to allow the button to be deleted, or FALSE to prevent the button from being deleted.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_QUERYINSERT

Notifies the toolbar's parent window whether a button may be inserted to the left of the specified button while the user is customizing a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_QUERYINSERT
    lpnmtb = (LPNMTOOLBAR) lParam;

Parameters

lpnmtb
Address of an NMTOOLBAR structure. The iItem member contains the zero-based index of the button to be inserted.

Return Values

Returns TRUE to allow a button to be inserted in front of the given button, or FALSE to prevent the button from being inserted.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_RESET

Notifies the toolbar's parent window that the user has reset the content of the Customize Toolbar dialog box. This message is sent in the form of a WM_NOTIFY message.

TBN_RESET
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBN_RESTORE

Notifies a toolbar's parent window that a toolbar is in the process of being restored.

TBN_RESTORE
    lpnmtb = (LPNMTBRESTORE) lParam;

Parameters

lpnmtb
Address of an NMTBRESTORE structure.

Return Values

The application should return zero in response to the first TBN_RESTORE notification received at the start of the restore process to continue restoring the button information. If the application returns a non-zero value, the restore process is cancelled.

Remarks

The application will receive a notification once at the start of the restore process and once for each button. This notification gives you an opportunity to extract the information from the data stream that you saved previously. If you haven't saved any information, ignore the notification. See Toolbar Customization for a more detailed discussion of how to handle TBN_RESTORE.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TBN_SAVE

Notifies a toolbar's parent window that a toolbar is in the process of being saved.

TBN_SAVE
    lpnmtb = (LPNMTBSAVE) lParam;

Parameters

lpnmtb
Address of an NMTBSAVE structure.

Return Values

No return value.

Remarks

The application will receive a notification once at the start of the save process and once for each button. This notification gives you an opportunity to add your own information to that saved by the Shell. If you don't wish to add information, ignore the notification. See Toolbar Customization for a more detailed discussion of how to handle TBN_SAVE.

See Also

TBN_RESTORE

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TBN_TOOLBARCHANGE

Notifies the toolbar's parent window that the user has customized a toolbar. This message is sent in the form of a WM_NOTIFY message.

TBN_TOOLBARCHANGE
    lpnmhdr = (LPNMHDR) lParam;

Parameters

lpnmhdr
Address of an NMHDR structure that contains information about the notification message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


COLORMAP

Contains information used by the CreateMappedBitmap function to map the colors of the bitmap.

typedef struct _COLORMAP {
    COLORREF from;
    COLORREF to;
} COLORMAP, FAR* LPCOLORMAP;

Members

from
Color to map from.
to
Color to map to.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMTBCUSTOMDRAW

Contains information specific to an NM_CUSTOMDRAW notification message sent by a toolbar control.

typedef struct _NMTBCUSTOMDRAW {
    NMCUSTOMDRAW nmcd;
    HBRUSH hbrMonoDither;
    HBRUSH hbrLines;
    HPEN hpenLines;
    COLORREF clrText;
    COLORREF clrMark;
    COLORREF clrTextHighlight;
    COLORREF clrBtnFace;
    COLORREF clrBtnHighlight;
    COLORREF clrHighlightHotTrack;
    RECT rcText;
    int nStringBkMode;
    int nHLStringBkMode;
} NMTBCUSTOMDRAW, * LPNMTBCUSTOMDRAW;

Members

nmcd
NMCUSTOMDRAW structure that contains general custom draw information. The uItemState member of this structure can be modified so that a toolbar item will be drawn in the specified state without actually changing the item's state.
hbrMonoDither
HBRUSH that the control will use when drawing the background of marked or dithered items. This member is ignored if TBCDRF_NOMARK is returned from the NM_CUSTOMDRAW notification.
hbrLines
HBRUSH that the control will use when drawing lines on the buttons.
hpenLines
HPEN that the control will use when drawing lines on the buttons.
clrText
COLORREF that represents the color that the control will use when drawing text on normal items.
clrMark
COLORREF that represents the background color that the control will use when drawing text on marked items.
clrTextHighlight
COLORREF that represents the color that the control will use when drawing text on highlighted items.
clrBtnFace
COLORREF that represents the face color that the control will use when drawing buttons.
clrBtnHighlight
COLORREF that represents the face color that the control will use when drawing highlighted items. An item is highlighted if it has the TBSTATE_MARKED style and is contained in a toolbar that has the TBSTYLE_FLAT style.
clrHighlightHotTrack
COLORREF that represents the background color that the control will use when drawing text on hot tracked items. This member is ignored if TBCDRF_HILITEHOTTRACK is not returned from the NM_CUSTOMDRAW notification.
rcText
RECT structure that, on entry, contains the rectangle of the item's text. The right and bottom members of this structure can be modified to change the width and height, respectively, of the text rectangle of the item.
nStringBkMode
Background mode that the control will use when drawing the text of a nonhighlighted item. This can be either the TRANSPARENT or OPAQUE value.
nHLStringBkMode
Background mode that the control will use when drawing the text of a highlighted item. This can be either the TRANSPARENT or OPAQUE value.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTBDISPINFO

Contains and receives display information for a toolbar item. This structure is used with the TBN_GETDISPINFO notification.

typedef struct{
    NMHDR  hdr;
    DWORD dwMask;
    int idCommand;
    DWORD_PTR lParam;
    int iImage;
    LPTSTR pszText;
    int cchText;
} NMTBDISPINFO, *LPNMTBDISPINFO;

Members

hdr
NMHDR structure that contains additional information about the notification message.
dwMask
Set of flags that indicate which members of this structure are being requested. This can be one or more of the following values.
TBNF_IMAGE | The item's image index is being requested. The image index must be placed in the iImage member.
TBNF_TEXT | Not currently implemented.
TBNF_DI_SETITEM | Set this flag when processing TBN_GETDISPINFO; the toolbar control will retain the supplied information and not request it again.
idCommand
Command identifier of the item for which display information is being requested. This member is filled in by the control before it sends the notification.
lParam
Application-defined value associated with the item for which display information is being requested. This member is filled in by the control before sending the notification.
iImage
Image index for the item.
pszText
Pointer to a character buffer that receives the item's text.
cchText
Size of the pszText buffer, in characters.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTBGETINFOTIP

Contains and receives infotip information for a toolbar item. This structure is used with the TBN_GETINFOTIP notification.

typedef struct tagNMTBGETINFOTIP{
    NMHDR hdr;
    LPTSTR pszText;
    int cchTextMax;
    int iItem;
    LPARAM lParam;
} NMTBGETINFOTIP, *LPNMTBGETINFOTIP;

Members

hdr
NMHDR structure that contains additional information about the notification message.
pszText
Address of a character buffer that receives the infotip text.
cchTextMax
Size of the buffer, in characters, at pszText. In most cases, the buffer will be INFOTIPSIZE characters in size, but you should always make sure that your application does not copy more than cchTextMax characters to the buffer at pszText.
iItem
The command identifier of the item for which infotip information is being requested. This member is filled in by the control before sending the notification.
lParam
The application-defined value associated with the item for which infotip information is being requested. This member is filled in by the control before sending the notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTBHOTITEM

Contains information used with the TBN_HOTITEMCHANGE notification.

typedef struct tagNMTBHOTITEM {
    NMHDR hdr;
    int idOld;
    int idNew;
    DWORD dwFlags;
} NMTBHOTITEM, FAR* LPNMTBHOTITEM;

Members

hdr
NMHDR structure that contains additional information about the notification message.
idOld
Command identifier of the previously highlighted item.
idNew
Command identifier of the item about to be highlighted.
dwFlags
Flags that indicate why the hot item has changed. This can be one or more of the following values:
HICF_ACCELERATOR | The change in the hot item was caused by a shortcut key.
HICF_ARROWKEYS | The change in the hot item was caused by an arrow key.
HICF_DUPACCEL | Modifies HICF_ACCELERATOR. If this flag is set, more than one item has the same shortcut key character.
HICF_ENTERING | Modifies the other reason flags. If this flag is set, there is no previous hot item and idOld does not contain valid information.
HICF_LEAVING | Modifies the other reason flags. If this flag is set, there is no new hot item and idNew does not contain valid information.
HICF_MOUSE | The change in the hot item resulted from a mouse event.
HICF_OTHER | The change in the hot item resulted from an event that could not be determined. This will most often be due to a change in focus or the TB_SETHOTITEM message.
HICF_RESELECT | The change in the hot item resulted from the user entering the shortcut key for an item that was already hot.
HICF_TOGGLEDROPDOWN | Version 5.80. Causes the button to switch states.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTBRESTORE

Allows applications to extract the information that was placed in NMTBSAVE when the toolbar state was saved. This structure is passed to applications when they receive a TBN_RESTORE notification message.

typedef struct tagNMTBRESTORE{
    NMHDR nmhdr;
    DWORD* pData;
    DWORD* pCurrent;
    UINT cbData;
    int iItem;
    int cButtons;
    int cbBytesPerRecord;
    TBBUTTON tbButton;
} NMTBRESTORE, *LPNMTBRESTORE;

Members

nmhdr
NMHDR structure that contains additional information about the notification message.
pData
Pointer to the data stream with the stored save information. It contains Shell-defined blocks of information for each button, alternating with application-defined blocks. Applications may also place a block of global data at the start of pData. The format and length of the application-defined blocks are determined by the application.
pCurrent
Pointer to the current block of application-defined data. After extracting the data, the application must advance pCurrent to the end of the block, so it is pointing to the next block of Shell-defined data.
cbData
Size of pData.
iItem
Value of -1 indicates that the restore is starting, and pCurrent will point to the start of the data stream. Otherwise, it is the zero-based button index, and pCurrent will point to the current button's data.
cButtons
Estimate of the number of buttons. Because the estimate is based on the size of the data stream, it might be incorrect. The client should update it as appropriate.
cbBytesPerRecord
Number of bytes needed to hold the data for each button. When the restore starts, cbBytesPerRecord will be set to the size of the Shell-defined data structure. You need to increment it by the size of the structure that holds the application-defined data.
tbButton
TBBUTTON structure that contains information about the button currently being restored. Applications must modify this structure as necessary before returning.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


NMTBSAVE

This structure is passed to applications when they receive a TBN_SAVE notification. It contains information about the button currently being saved. Applications can modify the values of the members to save additional information.

typedef struct tagNMTBSAVE{
    NMHDR nmhdr;
    DWORD* pData;
    DWORD* pCurrent;
    UINT cbData;
    int iItem;
    int cButtons;
    TBBUTTON tbButton;
} NMTBSAVE, *LPNMTBSAVE;

Members

nmhdr
An NMHDR structure that contains additional information about the notification message.
pData
A pointer to the data stream used to store the save information. When complete, it will contain blocks of Shell-defined information for each button, alternating with blocks defined by the application. Applications may also choose to place a block of global data at the start of pData. The format and length of the application-defined blocks are determined by the application. When the save starts, the Shell will pass the amount of memory it needs in cbData, but no memory will be allocated. You must allocate enough memory for pData to hold your data, plus the Shell's.
pCurrent
A pointer to the start of the unused portion of the data stream. You should load your data here, and then advance pCurrent to the start of the remaining unused portion. The Shell will then load the information for the next button, advance pCurrent, and so on.
cbData
The size of the data stream. When the save starts, cbData will be set to the amount of data needed by the Shell. You should change it to the total amount allocated.
iItem
This parameter is usually the zero-based index of the button currently being saved. It is set to -1 to indicate that a save is starting.
cButtons
An estimate of the number of buttons. Because it is based on the size of the data stream, it may be incorrect. The client should update it as appropriate.
tbButton
A TBBUTTON structure that contains information about the button currently being saved.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


NMTOOLBAR

Contains information used to process toolbar notification messages. This structure supersedes the TBNOTIFY structure.

typedef struct tagNMTOOLBAR {
    NMHDR		hdr;
    int		iItem;
    TBBUTTON	tbButton;
    int		cchText;
    LPTSTR		pszText;
    RECT		rcButton; //Version 5.80
} NMTOOLBAR, FAR* LPNMTOOLBAR;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iItem
Command identifier of the button associated with the notification.
tbButton
TBBUTTON structure that contains information about the toolbar button associated with the notification. This member only contains valid information with the TBN_QUERYINSERT and TBN_QUERYDELETE notifications.
cchText
Count of characters in the button text.
pszText
Address of a character buffer that contains the button text.
rcButton
Version 5.80. A RECT structure that defines the area covered by the button.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBADDBITMAP

Adds a bitmap that contains button images to a toolbar.

typedef struct {
    HINSTANCE hInst;
    UINT_PTR nID;
} TBADDBITMAP, *LPTBADDBITMAP;

Members

hInst
Handle to the module instance with the executable file that contains a bitmap resource. To use bitmap handles instead of resource IDs, set this member to NULL.

You can add the system-defined button bitmaps to the list by specifying HINST_COMMCTRL as the hInst member and one of the following values as the nID member.

Value | Description
IDB_STD_LARGE_COLOR | Adds large, color standard bitmaps.
IDB_STD_SMALL_COLOR | Adds small, color standard bitmaps.
IDB_VIEW_LARGE_COLOR | Adds large, color view bitmaps.
IDB_VIEW_SMALL_COLOR | Adds small, color view bitmaps.

For more information about the system-defined standard and view bitmaps, see the comments at the end of this reference.

nID
If hInst is NULL, set this member to the bitmap handle of the bitmap with the button images. Otherwise, set it to the resource identifier of the bitmap with the button images.

Remarks

If nID holds a bitmap handle, rather than a resource ID, do not destroy the bitmap until it has been replaced with TB_REPLACEBITMAP. Otherwise, the toolbar is destroyed.

The Windows header files provide the following values to be used as indexes to the standard and view bitmaps.

Standard Bitmaps
Value | Description
STD_COPY | Specifies the copy image.
STD_CUT | Specifies the cut image.
STD_DELETE | Specifies the delete image.
STD_FILENEW | Specifies the new file image.
STD_FILEOPEN | Specifies the open file image.
STD_FILESAVE | Specifies the save file image.
STD_FIND | Specifies the find image.
STD_HELP | Specifies the help image.
STD_PASTE | Specifies the paste image.
STD_PRINT | Specifies the print image.
STD_PRINTPRE | Specifies the print preview image.
STD_PROPERTIES | Specifies the properties image.
STD_REDOW | Specifies the redo image.
STD_REPLACE | Specifies the replace image.
STD_UNDO | Specifies the undo image.
View Bitmaps
Value | Description
VIEW_DETAILS | Specifies the view details image.
VIEW_LARGEICONS | Specifies the view large icons image.
VIEW_LIST | Specifies the view list image.
VIEW_SMALLICONS | Specifies the view small icons image.
VIEW_SORTDATE | Specifies the sort by date image.
VIEW_SORTNAME | Specifies the sort by name image.
VIEW_SORTSIZE | Specifies the sort by size image.
VIEW_SORTTYPE | Specifies the sort by type image.

Remarks

The TBADDBITMAP structure is used with the TB_ADDBITMAP message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TBBUTTON

Contains information about a button in a toolbar.

typedef struct _TBBUTTON {
    int       iBitmap;
    int       idCommand;
    BYTE      fsState;
    BYTE      fsStyle;
    DWORD_PTR dwData;
    INT_PTR   iString;
} TBBUTTON, NEAR* PTBBUTTON, FAR* LPTBBUTTON;

Members

iBitmap
Zero-based index of the button image. Set this member to I_IMAGECALLBACK, and the toolbar will send the TBN_GETDISPINFO notification to retrieve the image index when it is needed.

Version 5.81. Set this member to I_IMAGENONE to indicate that the button does not have an image. The button layout will not include any space for a bitmap, only text.

If the button is a separator, that is, if fsStyle is set to BTNS_SEP, iBitmap determines the width of the separator, in pixels.

idCommand
Command identifier associated with the button. This identifier is used in a WM_COMMAND message when the button is chosen.
fsState
Button state flags. This member can be a combination of the values listed in Toolbar Button States.
fsStyle
Button style. This member can be a combination of the button style values listed in Toolbar Control and Button Styles.
dwData
Application-defined value.
iString
Zero-based index of the button string.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBBUTTONINFO

Contains or receives information for a specific button in a toolbar.

typedef struct {
    UINT cbSize;
    DWORD dwMask;
    int idCommand;
    int iImage;
    BYTE fsState;
    BYTE fsStyle;
    WORD cx;
    DWORD_PTR lParam;
    LPTSTR pszText;
    int cchText;
} TBBUTTONINFO, *LPTBBUTTONINFO;

Members

cbSize
Size of the structure, in bytes. This member must be filled in prior to sending the associated message.
dwMask
Set of flags that indicate which members contain valid information. This member must be filled in prior to sending the associated message. This can be one or more of the following values.
TBIF_BYINDEX | Version 5.80. The wParam sent with a TB_GETBUTTONINFO or TB_SETBUTTONINFO message is an index, not an identifier.
TBIF_COMMAND | The idCommand member contains valid information or is being requested.
TBIF_IMAGE | The iImage member contains valid information or is being requested.
TBIF_LPARAM | The lParam member contains valid information or is being requested.
TBIF_SIZE | The cx member contains valid information or is being requested.
TBIF_STATE | The fsState member contains valid information or is being requested.
TBIF_STYLE | The fsStyle member contains valid information or is being requested.
TBIF_TEXT | The pszText member contains valid information or is being requested.
idCommand
Command identifier of the button.
iImage
Image index of the button. Set this member to I_IMAGECALLBACK, and the toolbar will send the TBN_GETDISPINFO notification to retrieve the image index when it is needed.

Version 5.81. Set this member to I_IMAGENONE to indicate that the button does not have an image. The button layout will not include any space for a bitmap, only text.

fsState
State flags of the button. This can be one or more of the toolbar button states.
fsStyle
Style flags of the button. This can be one or more of the toolbar button styles.
cx
Width of the button, in pixels.
lParam
Application-defined value associated with the button.
pszText
Address of a character buffer that contains or receives the button text.
cchText
Size of the buffer at pszText. If the button information is being set, this member is ignored.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TBINSERTMARK

Contains information on the insertion mark in a toolbar control.

typedef struct {
    int   iButton;
    DWORD dwFlags;
} TBINSERTMARK, * LPTBINSERTMARK;

Members

iButton
Zero-based index of the insertion mark. If this member is -1, there is no insertion mark.
dwFlags
Defines where the insertion mark is in relation to iButton. This can be one of the following values:
0 | The insertion mark is to the left of the specified button.
TBIMHT_AFTER | The insertion mark is to the right of the specified button.
TBIMHT_BACKGROUND | The insertion mark is on the background of the toolbar. This flag is only used with the TB_INSERTMARKHITTEST message.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBREPLACEBITMAP

Used with the TB_REPLACEBITMAP message to replace one toolbar bitmap with another.

typedef struct {
    HINSTANCE hInstOld;
    UINT_PTR nIDOld;
    HINSTANCE hInstNew;
    UINT_PTR nIDNew;
    int nButtons;
} TBREPLACEBITMAP, *LPTBREPLACEBITMAP;

Members

hInstOld
Module instance handle to the bitmap resource being replaced. Set this member to NULL to instead use a bitmap handle.
nIDOld
If hInstOld is NULL, set this member to the bitmap handle of the bitmap that is being replaced. Otherwise, set it to the resource identifier of the bitmap being replaced.
hInstNew
Module instance handle that contains the new bitmap resource. Set this member to NULL to instead use a bitmap handle.
nIDNew
If hInstNew is NULL, set this member to the bitmap handle of the bitmap with the new button images. Otherwise, set it to the resource identifier of the bitmap with the new button images.
nButtons
Number of button images contained in the new bitmap.

Remarks

If nIDNew holds a bitmap handle, rather than a resource ID, do not destroy the bitmap until it has been replaced with TB_REPLACEBITMAP, or the toolbar is destroyed.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TBSAVEPARAMS

Specifies the location in the registry where the TB_SAVERESTORE message stores and retrieves information about the state of a toolbar.

typedef struct {
    HKEY hkr;
    LPCTSTR pszSubKey;
    LPCTSTR pszValueName;
} TBSAVEPARAMS;

Members

hkr
Handle to the registry key.
pszSubKey
Subkey name.
pszValueName
Value name.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Barsdi

Barsdi Sample Application

This sample demonstrates the use of statusbar and toolbar controls in their simplest forms. These controls are attached to the main window (typically) of an application to give users a visual indication of menu items and other relevant pieces of information. This is a 32-bit only sample. Following is a list of the modules that comprise the application.

MODULE MAP:

  • Dispatch- Message dispatching routines.
  • WinMain - Calls initialization functions and processes the message loop.
  • BarSDI - Implements the windows procedure for the main application window.
  • Init - Performs application and instance specific initialization.
  • About - Defines a standard about dialog box.
  • Misc - Defines the applications specific commands not related to a specific module.
  • ToolBar - Creates the toolbar and processes ToolTips notifications.
  • StatBar - Creates and manages the status bar.

The Barsdi sample application is implemented in the following source files:

  • C source code
    • About.c
    • Barsdi.c
    • Dispatch.c
    • Init.c
    • Misc.c
    • Statbar.c
    • Toolbar.c
    • Winmain.c
  • Header files
    • Globals.h
    • Resource.h
    • Statbar.h
    • Toolbar.h
  • Resource files
    • Barsdi.rc


ABOUT.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE:   about.c
//
//  PURPOSE:   Displays the "About" dialog box
//
//  FUNCTIONS:
//    CmdAbout        - Displays the "About" dialog box
//    About           - Processes messages for "About" dialog box.
//    MsgAboutInit    - To initialize the about box with version info
//                      from resources.
//    MsgAboutCommand - Process WM_COMMAND message sent to the about box.
//    CmdAboutDone    - Free the about box and related data.
//
//  COMMENTS:
//
//

#include <windows.h>            // required for all Windows applications
#include <windowsx.h>
#include "globals.h"            // prototypes specific to this application
#include "resource.h"

LRESULT CALLBACK About(HWND, UINT, WPARAM, LPARAM);
LRESULT MsgAboutInit(HWND, UINT, WPARAM, LPARAM);
LRESULT MsgAboutCommand(HWND, UINT, WPARAM, LPARAM);
LRESULT CmdAboutDone(HWND, WORD, WORD, HWND);

// About dialog message table definition.
MSD rgmsdAbout[ ] =
{
    {WM_COMMAND,    MsgAboutCommand},
    {WM_INITDIALOG, MsgAboutInit}
};

MSDI msdiAbout =
{
    sizeof(rgmsdAbout) / sizeof(MSD),
    rgmsdAbout,
    edwpNone
};

// About dialog command table definition.
CMD rgcmdAbout[ ] =
{
    {IDOK,     CmdAboutDone},
    {IDCANCEL, CmdAboutDone}
};

CMDI cmdiAbout =
{
    sizeof(rgcmdAbout) / sizeof(CMD),
    rgcmdAbout,
    edwpNone
};

// Module specific "globals"  Used when a variable needs to be
// accessed in more than on handler function.

HFONT hFontCopyright;

//
//  FUNCTION: CmdAbout(HWND, WORD, WORD, HWND)
//
//  PURPOSE: Displays the "About" dialog box
//
//  PARAMETERS:
//    hwnd      - Window handle
//    wCommand  - IDM_ABOUT (unused)
//    wNotify   - Notification number (unused)
//    hwndCtrl  - NULL (unused)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//    To process the IDM_ABOUT message, call DialogBox() to display the
//    about dialog box.

LRESULT CmdAbout(HWND hwnd, WORD wCommand, WORD wNotify, HWND hwndCtrl)
{
    DialogBox(hInst, "AboutBox", hwnd, (DLGPROC)About);
    return 0;
}

//
//  FUNCTION: About(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  Processes messages for "About" dialog box.
//
//  PARAMETERS:
//    hdlg - window handle of the dialog box
//    wMessage - type of message
//    wparam - message-specific information
//    lparam - message-specific information
//
//  RETURN VALUE:
//    TRUE - message handled
//    FALSE - message not handled
//
//  COMMENTS:
//
//     Display version information from the version section of the
//     application resource.
//
//     Wait for user to click OK, then close the dialog box.
//

LRESULT CALLBACK About(HWND hdlg, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    return DispMessage(&msdiAbout, hdlg, uMessage, wparam, lparam);
}

//
//  FUNCTION: MsgAboutInit(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: To initialize the about box with version info from resources.
//
//  PARAMETERS:
//    hwnd - The window handing the message.
//    uMessage - The message number. (unused).
//    wparam - Message specific data (unused).
//    lparam - Message specific data (unused).
//
//  RETURN VALUE:
//    Always returns 0 - message handled.
//
//  COMMENTS:
//    Uses the version apis to retrieve version information for
//    each of the static text boxes in the about box.
//

LRESULT MsgAboutInit(HWND hdlg, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    #define POINTSIZE 8

    char  szFullPath[256];
    DWORD dwVerHnd;
    DWORD dwVerInfoSize;
    HDC   hDC;
    int   iLogPixelsY, iPointSize;

    // Center the dialog over the application window
    CenterWindow(hdlg, GetWindow(hdlg, GW_OWNER));

    // Set the copyright font to something smaller than default
    hDC = GetDC(hdlg);
    iLogPixelsY = GetDeviceCaps(hDC, LOGPIXELSY);
    ReleaseDC(hdlg, hDC);
    iPointSize = MulDiv(iLogPixelsY, POINTSIZE, 72);
    iPointSize *= -1;

    hFontCopyright = CreateFont(iPointSize,
                                0, 0, 0,
                                FW_BOLD,
                                0, 0, 0, 0,
                                0, 0, 0, 0,
                                "Arial");

    SendDlgItemMessage(hdlg,
                       IDD_VERLAST,
                       WM_SETFONT,
                       (WPARAM)hFontCopyright,
                       0L);

    // Get version information from the application
    GetModuleFileName(hInst, szFullPath, sizeof(szFullPath));
    dwVerInfoSize = GetFileVersionInfoSize(szFullPath, &dwVerHnd);
    if (dwVerInfoSize)
    {
        // If we were able to get the information, process it:
        HANDLE  hMem;
        LPVOID  lpvMem;
        char    szGetName[256];
        int     cchRoot;
        int     i;

        hMem = GlobalAlloc(GMEM_MOVEABLE, dwVerInfoSize);
        lpvMem = GlobalLock(hMem);
        GetFileVersionInfo(szFullPath, dwVerHnd, dwVerInfoSize, lpvMem);
        lstrcpy(szGetName, "\\StringFileInfo\\040904E4\\");
        cchRoot = lstrlen(szGetName);

        // Walk through the dialog items that we want to replace:
        for (i = IDD_VERFIRST; i <= IDD_VERLAST; i++)
        {
            BOOL  fRet;
            UINT  cchVer = 0;
            LPSTR lszVer = NULL;
            char  szResult[256];

            GetDlgItemText(hdlg, i, szResult, sizeof(szResult));
            lstrcpy(&szGetName[cchRoot], szResult);
            fRet = VerQueryValue(lpvMem, szGetName, &lszVer, &cchVer);

            if (fRet && cchVer && lszVer)
            {
                // Replace dialog item text with version info
                lstrcpy(szResult, lszVer);
                SetDlgItemText(hdlg, i, szResult);
            }
        }
        GlobalUnlock(hMem);
        GlobalFree(hMem);
    }
    return TRUE;
}

//
//  FUNCTION: MsgAboutCommand(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Process WM_COMMAND message sent to the about box.
//
//  PARAMETERS:
//    hwnd - The window handing the message.
//    uMessage - The message number. (unused).
//    wparam - Message specific data (unused).
//    lparam - Message specific data (unused).
//
//  RETURN VALUE:
//    Always returns 0 - message handled.
//
//  COMMENTS:
//    Uses this DipsCommand function defined in wndproc.c combined
//    with the cmdiAbout structure defined in this file to handle
//    the command messages for the about dialog box.
//

LRESULT MsgAboutCommand(HWND   hwnd,
                        UINT   uMessage,
                        WPARAM wparam,
                        LPARAM lparam)
{
    return DispCommand(&cmdiAbout, hwnd, wparam, lparam);
}

//
//  FUNCTION: CmdAboutDone(HWND, WORD, HWND)
//
//  PURPOSE: Free the about box and related data.
//
//  PARAMETERS:
//    hwnd - The window handling the command.
//    wCommand - The command to be handled (unused).
//    wNotify   - Notification number (unused)
//    hwndCtrl - NULL (unused).
//
//  RETURN VALUE:
//    Always returns TRUE.
//
//  COMMENTS:
//    Calls EndDialog to finish the dialog session.
//

LRESULT CmdAboutDone(HWND hdlg, WORD wCommand, WORD wNotify, HWND hwndCtrl)
{
    if (hFontCopyright)
       DeleteObject(hFontCopyright);

    EndDialog(hdlg, TRUE);          // Exit the dialog
    return TRUE;
}

Built on: Thursday, October 21, 1999


BARSDI.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE: barsdi.c
//
//  PURPOSE: Handles general routines for the Barsdi sample.
//
//  FUNCTIONS:
//    WndProc     - Processes messages for the main window.
//    MsgCommand  - Handle the WM_COMMAND messages for the main window.
//    MsgCreate   - Handle the WM_CREATE messages for the main window.
//    MsgSize     - Handles the WM_SIZE message by calling SendMessage() to pass
//                  the WM_SIZE message onto the status bar and tool bar controls.
//    MsgDestroy  - Handles the WM_DESTROY message by calling
//                  PostQuitMessage().
//    CmdExit     - Handles the file exit command by calling destory
//                  window on the main window.
//
//  COMMENTS:
//    Message dispatch table -
//      For every message to be handled by the main window procedure
//      place the message number and handler function pointer in
//      rgmsd (the message dispatch table).  Place the prototype
//      for the function in globals.h and the definition of the
//      function in the appropriate module.
//    Command dispatch table -
//      For every command to be handled by the main window procedure
//      place the command number and handler function pointer in
//      rgcmd (the command dispatch table).  Place the prototype
//      for the function in globals.h and the definition of the
//      function in the appropriate module.
//    Globals.h Contains the definitions of the structures and dispatch.c
//      contains the functions that use these structures.
//

#include <windows.h>            // required for all Windows applications
#include <windowsx.h>
#include <commctrl.h>           // prototypes and defs for common controls
#include "globals.h"            // prototypes specific to this application
#include "statbar.h"            // prototypes specific to statbar.c
#include "toolbar.h"            // prototypes specific to toolbar.c
#include "resource.h"

// Main window message table definition.
MSD rgmsd[ ] =
{
    {WM_CREATE,     MsgCreate    },
    {WM_SIZE,       MsgSize      },
    {WM_TIMER,      MsgTimer     },
    {WM_MOUSEMOVE,    MsgMousemove   },
    {WM_NCMOUSEMOVE,  MsgNCMousemove },
    {WM_COMMAND,      MsgCommand     },
    {WM_NOTIFY,       MsgNotify      },
    {WM_MENUSELECT,   MsgMenuSelect  },
    {WM_DESTROY,      MsgDestroy     }
};

MSDI msdiMain =
{
    sizeof(rgmsd) / sizeof(MSD),
    rgmsd,
    edwpWindow
};

// Main window command table definition.
CMD rgcmd[ ] =
{
    {IDM_FILENEW,     CmdStub},
    {IDM_FILEOPEN,    CmdStub},
    {IDM_FILESAVE,    CmdStub},
    {IDM_BRUSH,       CmdStub},
    {IDM_FILECLOSE,   CmdStub},
    {IDM_FILEPRINT,   CmdStub},
    {IDM_FILL,        CmdStub},
    {IDM_SELECT,      CmdStub},
    {IDM_EXIT,        CmdExit},

    {IDM_ERASE,       CmdStub},
    {IDM_EDITCUT,     CmdStub},
    {IDM_EDITCOPY,    CmdStub},
    {IDM_AIRBRUSH,    CmdStub},
    {IDM_LINE,          CmdStub},
    {IDM_EYEDROP,     CmdStub},
    {IDM_ZOOM,        CmdStub},
    {IDM_RECT,        CmdStub},
    {IDM_OVAL,        CmdStub},
    {IDM_FRAME,          CmdStub},
    {IDM_PEN,            CmdStub},
    {IDM_ABOUT,       CmdAbout}
};

CMDI cmdiMain =
{
    sizeof(rgcmd) / sizeof(CMD),
    rgcmd,
    edwpWindow
};

//
//  FUNCTION: WndProc(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  Processes messages for the main window.
//
//  PARAMETERS:
//    hwnd     - window handle
//    uMessage - message number
//    wparam   - additional information (dependant on message number)
//    lparam   - additional information (dependant on message number)
//
//  RETURN VALUE:
//    The return value depends on the message number.  If the message
//    is implemented in the message dispatch table, the return value is
//    the value returned by the message handling function.  Otherwise,
//    the return value is the value returned by the default window procedure.
//
//  COMMENTS:
//    Call the DispMessage() function with the main window's message dispatch
//    information (msdiMain) and the message specific information.
//

LRESULT CALLBACK WndProc(HWND   hwnd,
                         UINT   uMessage,
                         WPARAM wparam,
                         LPARAM lparam)
{
    return DispMessage(&msdiMain, hwnd, uMessage, wparam, lparam);
}

//
//  FUNCTION: MsgCommand(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Handle the WM_COMMAND messages for the main window.
//
//  PARAMETERS:
//    hwnd     - window handle
//    uMessage - WM_COMMAND (Unused)
//    GET_WM_COMMAND_ID(wparam, lparam)   - Command identifier
//    GET_WM_COMMAND_HWND(wparam, lparam) - Control handle
//
//  RETURN VALUE:
//    The return value depends on the message number.  If the message
//    is implemented in the message dispatch table, the return value is
//    the value returned by the message handling function.  Otherwise,
//    the return value is the value returned by the default window procedure.
//
//  COMMENTS:
//    Call the DispCommand() function with the main window's command dispatch
//    information (cmdiMain) and the command specific information.
//

LRESULT MsgCommand(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    return DispCommand(&cmdiMain, hwnd, wparam, lparam);
}

//
//  FUNCTION: MsgCreate(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Handle the WM_CREATE messages for the main window.
//           and call InitCommonControls() API to initialize the
//           common control library.
//
//  PARAMETERS:
//    hwnd     - window handle
//
//  RETURN VALUE:
//    Return 0 if the StatusBar and ToolBar Windows could be created
//    successfully. Otherwise, returns -1 to abort the main window
//    creation.
//
//  COMMENTS:
//    Call the CreateTSBars function with the main window's window handle
//    information (msdiMain).
//

LRESULT MsgCreate(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
   InitCommonControls() ; // Initialize the common control library.

   if(CreateTBar(hwnd) && CreateSBar(hwnd))
       return 0;    // Tool and status bars were created, so return 0.
   else
       return -1;   // Tool and status bars were not created, so return -1.
}

//
//  FUNCTION: MsgSize(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  This function resizes the toolbar and statusbar controls.
//
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Used)
//    uMessage  - Message number (Used)
//    wparam    - Extra data     (Used)
//    lparam    - Extra data     (Used)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//
//    When the window procdure that has the status and tool bar controls
//    receive the WM_SIZE message, it has to pass the message on to these
//    controls so that these controls can adjust their size accordingly.
//
//

LRESULT MsgSize(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    SendMessage(hWndStatusbar,  uMessage, wparam, lparam);
    SendMessage(hWndToolbar, uMessage, wparam, lparam);

    // Re-position the panes in the status bar
    InitializeStatusBar(hwnd);

    return 0 ;
}

//
//  FUNCTION: MsgDestroy(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Calls PostQuitMessage().
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Unused)
//    uMessage  - Message number (Unused)
//    wparam    - Extra data     (Unused)
//    lparam    - Extra data     (Unused)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//
//

LRESULT MsgDestroy(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    PostQuitMessage(0);
    return 0;
}

//
//  FUNCTION: CmdExit(HWND, WORD, WORD, HWND)
//
//  PURPOSE: Exit the application.
//
//  PARAMETERS:
//    hwnd     - The window.
//    wCommand - IDM_EXIT (unused)
//    wNotify  - Notification number (unused)
//    hwndCtrl - NULL (unused)
//
//  RETURN VALUE:
//    Always returns 0 - command handled.
//
//  COMMENTS:
//
//

LRESULT CmdExit(HWND hwnd, WORD wCommand, WORD wNotify, HWND hwndCtrl)
{
    char szBuffer[50];
    int  cbWritten = 0;

    cbWritten = LoadString(hInst, wCommand, szBuffer, sizeof(szBuffer));
    if(cbWritten == 0)
        lstrcpy(szBuffer, "Unknown Command");

    UpdateStatusBar(szBuffer, 0, 0);
    MessageBox(hwnd,
               "EXIT APPLICATION:",
               "EXIT",
               MB_OK | MB_ICONEXCLAMATION);

    DestroyWindow(hwnd);
    return 0;
}

Built on: Thursday, October 21, 1999


BARSDI.RC

//Microsoft Visual C++ generated resource script.
//
#include "resource.h"

#define APSTUDIO_READONLY_SYMBOLS
/////////////////////////////////////////////////////////////////////////////
//
// Generated from the TEXTINCLUDE 2 resource.
//
#define APSTUDIO_HIDDEN_SYMBOLS
#include "windows.h"
#undef APSTUDIO_HIDDEN_SYMBOLS
#include "winver.h"
#include "globals.h"
#include "toolbar.h"
#include "statbar.h"

/////////////////////////////////////////////////////////////////////////////
#undef APSTUDIO_READONLY_SYMBOLS

/////////////////////////////////////////////////////////////////////////////
//
// Icon
//

IDI_APPICON             ICON    DISCARDABLE     "BARSDI.ICO"

/////////////////////////////////////////////////////////////////////////////
//
// Bitmap
//

IDB_BMP                 BITMAP  MOVEABLE PURE   "toolbar.bmp"

/////////////////////////////////////////////////////////////////////////////
//
// Dialog
//

ABOUTBOX DIALOG DISCARDABLE  22, 17, 167, 64
STYLE DS_MODALFRAME | WS_CAPTION | WS_SYSMENU
CAPTION "About BARSDI"
FONT 8, "Courier"
BEGIN
    DEFPUSHBUTTON   "OK",IDOK,132,2,32,14,WS_GROUP
    ICON            IDI_APPICON,IDC_STATIC,3,2,18,20
    LTEXT           "CompanyName",IDD_VERFIRST,30,2,100,8
    LTEXT           "FileDescription",101,30,10,82,8
    LTEXT           "FileVersion",102,100,10,30,8
    LTEXT           "LegalCopyright",103,30,18,137,8
    CONTROL         "",501,"Static",SS_BLACKRECT,28,31,138,1
    LTEXT           "Static",IDC_STATIC,113,40,30,8
END

IDD_DIALOG1 DIALOG DISCARDABLE  0, 0, 186, 90
STYLE DS_MODALFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION | WS_SYSMENU
CAPTION "Dialog"
FONT 8, "MS Serif"
BEGIN
    DEFPUSHBUTTON   "OK",IDOK,130,6,50,14
    PUSHBUTTON      "Cancel",IDCANCEL,130,23,50,14
    LTEXT           "Static",IDC_STATIC,39,20,30,8
END

/////////////////////////////////////////////////////////////////////////////
//
// Menu
//

BARSDI MENU DISCARDABLE
BEGIN
    POPUP "&File"
    BEGIN
        MENUITEM "&New",                        IDM_FILENEW
        MENUITEM "&Open...",                    IDM_FILEOPEN
        MENUITEM "&Save",                       IDM_FILESAVE
        MENUITEM "Save &As...",                 IDM_FILESAVEAS
        MENUITEM "&Close",                      IDM_FILECLOSE
        MENUITEM SEPARATOR
        MENUITEM "&Print",                      IDM_FILEPRINT
        MENUITEM "Page Se&tup...",              IDM_FILEPAGESU
        MENUITEM "P&rint Setup...",             IDM_FILEPRINTSU
        MENUITEM SEPARATOR
        MENUITEM "E&xit",                       IDM_EXIT
    END
    POPUP "&Edit"
    BEGIN
        MENUITEM "&Undo\tAlt+BkSp",             IDM_EDITUNDO
        MENUITEM SEPARATOR
        MENUITEM "Cu&t\tShift+Del",             IDM_EDITCUT
        MENUITEM "&Copy\tCtrl+Ins",             IDM_EDITCOPY
        MENUITEM "&Paste\tShift+Ins",           IDM_EDITPASTE
        MENUITEM "&Delete\tDel",                IDM_EDITCLEAR
    END
    POPUP "&Help"
    BEGIN
        MENUITEM "&About...",                   IDM_ABOUT
    END
END

/////////////////////////////////////////////////////////////////////////////
//
// Accelerator
//

BARSDI ACCELERATORS MOVEABLE PURE
BEGIN
    "Q",            IDM_EXIT,               VIRTKEY, CONTROL
END

/////////////////////////////////////////////////////////////////////////////
//
// Version
//

VS_VERSION_INFO VERSIONINFO
 FILEVERSION 4,0,0,0
 PRODUCTVERSION 4,0,0,0
 FILEFLAGSMASK 0x3fL
#ifdef _DEBUG
 FILEFLAGS 0xbL
#else
 FILEFLAGS 0xaL
#endif
 FILEOS 0x10001L
 FILETYPE 0x1L
 FILESUBTYPE 0x0L
BEGIN
    BLOCK "StringFileInfo"
    BEGIN
        BLOCK "040904E4"
        BEGIN
            VALUE "CompanyName", "Microsoft Corporation\0"
            VALUE "FileDescription", "Toolbar/Statusbar Sample\0"
            VALUE "FileVersion", "4.0\0"
            VALUE "InternalName", "BARSDI\0"
            VALUE "LegalCopyright", "Copyright \251 Microsoft Corp. 1990-1995\0"
            VALUE "LegalTrademarks", "Microsoft\256 is a registered trademark of Microsoft Corporation. Windows(TM) is a trademark of Microsoft Corporation\0"
            VALUE "ProductName", "BARSDI\0"
            VALUE "ProuctVersion", "4.0\0"
        END
    END
    BLOCK "VarFileInfo"
    BEGIN
        VALUE "Translation", 0x409, 1252
    END
END

#ifdef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// TEXTINCLUDE
//

1 TEXTINCLUDE DISCARDABLE
BEGIN
    "resource.h\0"
END

2 TEXTINCLUDE DISCARDABLE
BEGIN
    "#define APSTUDIO_HIDDEN_SYMBOLS\r\n"
    "#include ""windows.h""\r\n"
    "#undef APSTUDIO_HIDDEN_SYMBOLS\r\n"
    "#include ""winver.h""\r\n"
    "#include ""globals.h""\r\n"
    "#include ""toolbar.h""\r\n"
    "#include ""statbar.h""\r\n"
    "\0"
END

3 TEXTINCLUDE DISCARDABLE
BEGIN
    "\r\n"
    "\0"
END

/////////////////////////////////////////////////////////////////////////////
#endif    // APSTUDIO_INVOKED

/////////////////////////////////////////////////////////////////////////////
//
// String Table
//

STRINGTABLE DISCARDABLE
BEGIN
    IDS_APPNAME             "BARSDI"
    IDS_DESCRIPTION         "Toolbar/Statusbar Sample"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SYSMENU             "Move, size, or close application window"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCRESTORE           "Restores the window to normal size"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCMOVE              "Changes the position of the window"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCSIZE              "Changes the size of the window"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCMINIMIZE          "Minimizes the window to an icon"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCMAXIMIZE          "Enlarges the window to full size"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCCLOSE             "Closes the window"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_SCTASKLIST          "Switches to another application through the Windows Task Manager"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_FILEMENU            "Create, open, save, or print documents"
    IDM_FILENEW             "Creates a new document"
    IDM_FILEOPEN            "Opens an existing document"
    IDM_FILESAVE            "Saves the active document"
    IDM_FILESAVEAS          "Saves the active document under a different name"
    IDM_FILECLOSE           "Closes the active document"
    IDM_FILEPRINT           "Prints the active document"
    IDM_FILEPAGESU          "Changes the page setup"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDM_ERASE               "Erase"
    IDM_PEN                 "Pen"
    IDM_SELECT              "Select"
    IDM_BRUSH               "Brush"
    IDM_AIRBRUSH            "Air Brush"
    IDM_FILL                "Fill"
    IDM_LINE                "Line"
    IDM_EYEDROP             "Eye Drop"
    IDM_ZOOM                "Zoom"
    IDM_RECT                "Rectangle"
    IDM_FRAME               "Frame"
    IDM_OVAL                "Oval"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDM_FILEPRINTSU         "Changes the printer selection or configuration"
    IDM_EXIT                "Quits this application"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_EDITMENU            "Undo, delete, copy, and insert"
    IDM_EDITUNDO            "Reverses the last action"
    IDM_EDITCUT             "Cuts the selection and puts it on the clipboard"
    IDM_EDITCOPY            "Copies the selection and puts it on the clipboard"
    IDM_EDITPASTE           "Inserts the clipboard contents at the insertion point"
    IDM_EDITCLEAR           "Removes the selection without putting it on the clipboard"
END

STRINGTABLE DISCARDABLE
BEGIN
    IDS_HELPMENU            "Get Help"
    IDM_ABOUT               "Displays information about this application"
END

#ifndef APSTUDIO_INVOKED
/////////////////////////////////////////////////////////////////////////////
//
// Generated from the TEXTINCLUDE 3 resource.
//

/////////////////////////////////////////////////////////////////////////////
#endif    // not APSTUDIO_INVOKED

Built on: Thursday, October 21, 1999


DISPATCH.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE:   dispatch.c
//
//  PURPOSE:  Implement the generic message and command dispatchers.
//
//
//  FUNCTIONS:
//    DispMessage - Call the function associated with a message.
//    DispCommand - Call the function associated with a command.
//    DispDefault - Call the appropriate default window procedure.
//
//  COMMENTS:
//

#include <windows.h>            // required for all Windows applications
#include <windowsx.h>
#include "globals.h"            // prototypes specific to this application

LRESULT DispDefault(EDWP, HWND, UINT, WPARAM, LPARAM);

//
//  FUNCTION: DispMessage(LPMSDI, HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Call the function associated with a message.
//
//  PARAMETERS:
//    lpmsdi - Structure containing the message dispatch information.
//    hwnd - The window handle
//    uMessage - The message number
//    wparam - Message specific data
//    lparam - Message specific data
//
//  RETURN VALUE:
//    The value returned by the message function that was called.
//
//  COMMENTS:
//    Runs the table of messages stored in lpmsdi->rgmsd searching
//    for a message number that matches uMessage.  If a match is found,
//    call the associated function.  Otherwise, call DispDefault to
//    call the default function, if any, associated with the message
//    structure.  In either case, return the value recieved from the
//    message or default function.
//

LRESULT DispMessage(LPMSDI lpmsdi,
                    HWND   hwnd,
                    UINT   uMessage,
                    WPARAM wparam,
                    LPARAM lparam)
{
    int  imsd = 0;

    MSD *rgmsd = lpmsdi->rgmsd;
    int  cmsd  = lpmsdi->cmsd;

    for (imsd = 0; imsd < cmsd; imsd++)
    {
        if (rgmsd[imsd].uMessage == uMessage)
            return rgmsd[imsd].pfnmsg(hwnd, uMessage, wparam, lparam);
    }

    return DispDefault(lpmsdi->edwp, hwnd, uMessage, wparam, lparam);
}

//
//  FUNCTION: DispCommand(LPCMDI, HWND, WPARAM, LPARAM)
//
//  PURPOSE: Call the function associated with a command.
//
//  PARAMETERS:
//    lpcmdi - Structure containing the command dispatch information.
//    hwnd - The window handle
//    GET_WM_COMMAND_ID(wparam, lparam) - Identifier of the menu item,
//      control, or accelerator.
//    GET_WM_COMMAND_CMD(wparam, lparam) - Notification code.
//    GET_WM_COMMAND_HWND(wparam, lparam) - The control handle or NULL.
//
//  RETURN VALUE:
//    The value returned by the command function that was called.
//
//  COMMENTS:
//    Runs the table of commands stored in lpcmdi->rgcmd searching
//    for a command number that matches wCommand.  If a match is found,
//    call the associated function.  Otherwise, call DispDefault to
//    call the default function, if any, associated with the command
//    structure.  In either case, return the value recieved from the
//    command or default function.
//

LRESULT DispCommand(LPCMDI lpcmdi,
                    HWND   hwnd,
                    WPARAM wparam,
                    LPARAM lparam)
{
    LRESULT lRet = 0;
    WORD    wCommand = GET_WM_COMMAND_ID(wparam, lparam);
    int     icmd;

    CMD    *rgcmd = lpcmdi->rgcmd;
    int     ccmd  = lpcmdi->ccmd;

    // Message packing of wparam and lparam have changed for Win32,
    // so use the GET_WM_COMMAND macro to unpack the commnad

    for (icmd = 0; icmd < ccmd; icmd++)
    {
        if (rgcmd[icmd].wCommand == wCommand)
        {
            return rgcmd[icmd].pfncmd(hwnd,
                                      wCommand,
                                      GET_WM_COMMAND_CMD(wparam, lparam),
                                      GET_WM_COMMAND_HWND(wparam, lparam));
        }
    }

    return DispDefault(lpcmdi->edwp, hwnd, WM_COMMAND, wparam, lparam);
}

//
//  FUNCTION: DispDefault(EDWP, HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Call the appropriate default window procedure.
//
//  PARAMETERS:
//    edwp - Enumerate specifying the appropriate default winow procedure.
//    hwnd - The window handle
//    uMessage - The message number
//    wparam - Message specific data
//    lparam - Message specific data
//
//  RETURN VALUE:
//    If there is a default proc, return the value returned by the
//    default proc.  Otherwise, return 0.
//
//  COMMENTS:
//    Calls the default procedure associated with edwp using the specified
//    parameters.
//

LRESULT DispDefault(EDWP   edwp,
                    HWND   hwnd,
                    UINT   uMessage,
                    WPARAM wparam,
                    LPARAM lparam)
{
    switch (edwp)
    {
        case edwpNone:
            return 0;
        case edwpWindow:
            return DefWindowProc(hwnd, uMessage, wparam, lparam);
        case edwpDialog:
            return DefDlgProc(hwnd, uMessage, wparam, lparam);
        case edwpMDIFrame:
            return DefFrameProc(hwnd, hwndMDIClient, uMessage, wparam, lparam);
        case edwpMDIChild:
            return DefMDIChildProc(hwnd, uMessage, wparam, lparam);
    }
    return 0;
}

Built on: Thursday, October 21, 1999


GLOBALS.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
// PURPOSE:
//
//  Contains declarations for all globally scoped names in the program
//

//
// Product identifier string defines
//
//  **TODO** Change these strings to the name of your application.

#define APPNAME  BARSDI
#define ICONFILE BARSDI.ICO
#define SZAPPNAME "BARSDI"
#define SZDESCRIPTION "Toolbar/Statusbar Sample"
#define SZABOUT "About BARSDI"
#define SZVERSION "4.0"

//-------------------------------------------------------------------------
// Functions for handling main window messages.  The message-dispatching
// mechanism expects all message-handling functions to have the following
// prototype:
//
//     LRESULT FunctionName(HWND, UINT, WPARAM, LPARAM);

// **TODO**  Add message-handling function prototypes here.  Be sure to
//           add the function names to the main window message table in
//           barsdi.c.

LRESULT MsgCommand   (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgCreate    (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgDestroy   (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgSize      (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgTimer     (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgMousemove   (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgNCMousemove (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgMenuSelect  (HWND, UINT, WPARAM, LPARAM);
LRESULT MsgNotify      (HWND, UINT, WPARAM, LPARAM);

//-------------------------------------------------------------------------
// Functions for handling main window commands--ie. functions for
// processing WM_COMMAND messages based on the wParam value.
// The message-dispatching mechanism expects all command-handling
// functions to have the following prototype:
//
//     LRESULT FunctionName(HWND, WORD, WORD, HWND);

// **TODO**  Add message-handling function prototypes here.  Be sure to
//           add the function names to the main window command table in
//           barsdi.c.

LRESULT CmdExit (HWND, WORD, WORD, HWND);
LRESULT CmdAbout(HWND, WORD, WORD, HWND);
LRESULT CmdStub (HWND, WORD, WORD, HWND);

//-------------------------------------------------------------------------
// Global function prototypes.

// **TODO**  Add global function prototypes here.

BOOL InitApplication(HINSTANCE, int);
BOOL CenterWindow(HWND, HWND);

    // Callback functions.  These are called by Windows.

// **TODO**  Add new callback function prototypes here.

LRESULT CALLBACK WndProc(HWND, UINT, WPARAM, LPARAM);

// -----------------------------------------------------------------------
// Global Variable declarations
//

extern HINSTANCE hInst;     // The current instance
extern char szAppName[ ];    // The name of this application
extern char szTitle[ ];      // The title bar text

// **TODO**  For NON-MDI applications, uncomment line 1 below and comment
//           line 2.  For MDI applications, uncomment line 2 below, comment
//           line 1, and then define hwndMDIClient as a global variable in
//           INIT.C
#define hwndMDIClient NULL        /* (1) Stub for NON-MDI applications. */
// extern HWND hwndMDIClient;     /* (2) For MDI applications.          */

//-------------------------------------------------------------------------
// Message and command dispatch infrastructure.  The following type
// definitions and functions are used by the message and command dispatching
// mechanism and do not need to be changed.

    // Function pointer prototype for message handling functions.
typedef LRESULT (*PFNMSG)(HWND,UINT,WPARAM,LPARAM);

    // Function pointer prototype for command handling functions.
typedef LRESULT (*PFNCMD)(HWND,WORD,WORD,HWND);

    // Enumerated type used to determine which default window procedure
    // should be called by the message- and command-dispatching mechanism
    // if a message or command is not handled explicitly.
typedef enum
{
   edwpNone,            // Do not call any default procedure.
   edwpWindow,          // Call DefWindowProc.
   edwpDialog,          // Call DefDlgProc (This should be used only for
                        // custom dialog boxes - standard dialog box use edwpNone).
   edwpMDIChild,        // Call DefMDIChildProc.
   edwpMDIFrame         // Call DefFrameProc.
} EDWP;                // Enumeration for Default Window Procedures

    // This structure maps messages to message handling functions.
typedef struct _MSD
{
    UINT   uMessage;
    PFNMSG pfnmsg;
} MSD;                 // MeSsage Dispatch structure

    // This structure contains all of the information that a window
    // procedure passes to DispMessage in order to define the message
    // dispatching behavior for the window.
typedef struct _MSDI
{
    int  cmsd;          // Number of message dispatch structs in rgmsd
    MSD *rgmsd;         // Table of message dispatch structures
    EDWP edwp;          // Type of default window handler needed.
} MSDI, FAR *LPMSDI;   // MeSsage Dipatch Information

    // This structure maps command IDs to command handling functions.
typedef struct _CMD
{
    WORD   wCommand;
    PFNCMD pfncmd;
} CMD;                 // CoMmand Dispatch structure

    // This structure contains all of the information that a command
    // message procedure passes to DispCommand in order to define the
    // command dispatching behavior for the window.
typedef struct _CMDI
{
    int  ccmd;          // Number of command dispatch structs in rgcmd
    CMD *rgcmd;         // Table of command dispatch structures
    EDWP edwp;          // Type of default window handler needed.
} CMDI, FAR *LPCMDI;   // CoMmand Dispatch Information

    // Message and command dispatching functions.  They look up messages
    // and commands in the dispatch tables and call the appropriate handler
    // function.
LRESULT DispMessage(LPMSDI, HWND, UINT, WPARAM, LPARAM);
LRESULT DispCommand(LPCMDI, HWND, WPARAM, LPARAM);

    // Message dispatch information for the main window
extern MSDI msdiMain;
    // Command dispatch information for the main window
extern CMDI cmdiMain;

Built on: Thursday, October 21, 1999


INIT.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE:   init.c
//
//  PURPOSE:   Performs application and instance specific initialization.
//
//  FUNCTIONS:
//    InitApplication() - Initializes window data and registers window.
//
//  COMMENTS:
//

#include <windows.h>            // required for all Windows applications
#include "globals.h"            // prototypes specific to this application
#include "resource.h"

HINSTANCE hInst;                // current instance

char szAppName[9];              // The name of this application
char szTitle[40];               // The title bar text

//
//  FUNCTION: InitApplication(HINSTANCE, int)
//
//  PURPOSE: Initializes window data and registers window class.
//
//  PARAMETERS:
//    hInstance - The handle to the instance of this application that
//                is currently being executed.
//    nCmdShow  - Specifies how the main window is to be displayed.
//
//  RETURN VALUE:
//    TRUE  - Success
//    FALSE - Initialization failed
//
//  COMMENTS:
//
//    This function is called at application initialization time.  It
//    performs initialization tasks for the current application instance.
//    Unlike Win16, in Win32, each instance of an application must register
//    window classes.
//
//    In this function, we initialize a window class by filling out a data
//    structure of type WNDCLASS and calling the Windows RegisterClass()
//    function.  Then we create the main window and show it.
//
//

BOOL InitApplication(HINSTANCE hInstance, int nCmdShow)
{
    WNDCLASSEX wc;
    HWND       hwnd; // Main window handle.

    // Load the application name and description strings.

    LoadString(hInstance, IDS_APPNAME, szAppName, sizeof(szAppName));
    LoadString(hInstance, IDS_DESCRIPTION, szTitle, sizeof(szTitle));

    // Save the instance handle in static variable, which will be used in
    // many subsequence calls from this application to Windows.

    hInst = hInstance; // Store instance handle in our global variable

    // Fill in window class structure with parameters that describe the
    // main window.

    wc.cbSize        = sizeof(WNDCLASSEX);
    wc.style         = CS_HREDRAW | CS_VREDRAW; // Class style(s).
    wc.lpfnWndProc   = (WNDPROC)WndProc;        // Window Procedure
    wc.cbClsExtra    = 0;                       // No per-class extra data.
    wc.cbWndExtra    = 0;                       // No per-window extra data.
    wc.hInstance     = hInstance;               // Owner of this class
    wc.hIcon         = LoadIcon(hInstance, MAKEINTRESOURCE(IDI_APPICON)); // Icon name from .RC
    wc.hCursor       = LoadCursor(NULL, IDC_ARROW); // Cursor
    wc.hbrBackground = (HBRUSH)GetStockObject(BLACK_BRUSH); // Black color
    wc.lpszMenuName  = szAppName;               // Menu name from .RC
    wc.lpszClassName = szAppName;               // Name to register as
    wc.hIconSm       = LoadImage(hInstance,     // Load small icon image
                                 MAKEINTRESOURCE(IDI_APPICON),
                                 IMAGE_ICON,
                                 16, 16,
                                 0);

    // Register the window class and return FALSE if unsuccesful.

    if (!RegisterClassEx(&wc))
    {
        //Assume we are running on NT where RegisterClassEx() is
        //not implemented, so let's try calling RegisterClass().

        if (!RegisterClass((LPWNDCLASS)&wc.style))
            return FALSE;
    }

    // Create a main window for this application instance.
    hwnd = CreateWindow(szAppName,           // See RegisterClass() call
                        szTitle,             // Text for window title bar
                        WS_OVERLAPPEDWINDOW, // Window style
                        CW_USEDEFAULT, 0,    // Use default positioning
                        CW_USEDEFAULT, 0,    // Use default size
                        NULL,                // Overlapped has no parent
                        NULL,                // Use the window class menu
                        hInstance,           // This instance owns this
                                             // window
                        NULL                 // Don't need data in WM_CREATE
    );

    // If window could not be created, return "failure"
    if (!hwnd)
        return FALSE;

    // Make the window visible; update its client area; and return "success"
    ShowWindow(hwnd, nCmdShow);  // Show the window
    UpdateWindow(hwnd);          // Sends WM_PAINT message

    return TRUE;                 // We succeeded...
}

Built on: Thursday, October 21, 1999


MISC.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE:   misc.c
//
//  PURPOSE:  Contains all helper functions "global" to the application.
//
//  FUNCTIONS:
//    CenterWindow - Center one window over another.
//    CmdStub      - Handles unimplemented commands.
//                   Demonstrates the statusbar updating.
//
//  COMMENTS:
//

#include <windows.h>            // required for all Windows applications
#include <windowsx.h>
#include "globals.h"            // prototypes specific to this application
#include "statbar.h"

//
//  FUNCTION: CenterWindow(HWND, HWND)
//
//  PURPOSE:  Center one window over another.
//
//  PARAMETERS:
//    hwndChild - The handle of the window to be centered.
//    hwndParent- The handle of the window to center on.
//
//  RETURN VALUE:
//
//    TRUE  - Success
//    FALSE - Failure
//
//  COMMENTS:
//
//    Dialog boxes take on the screen position that they were designed
//    at, which is not always appropriate. Centering the dialog over a
//    particular window usually results in a better position.
//

BOOL CenterWindow(HWND hwndChild, HWND hwndParent)
{
    RECT    rcChild, rcParent;
    int     cxChild, cyChild, cxParent, cyParent;
    int     cxScreen, cyScreen, xNew, yNew;
    HDC     hdc;

    // Get the Height and Width of the child window
    GetWindowRect(hwndChild, &rcChild);
    cxChild = rcChild.right - rcChild.left;
    cyChild = rcChild.bottom - rcChild.top;

    // Get the Height and Width of the parent window
    GetWindowRect(hwndParent, &rcParent);
    cxParent = rcParent.right - rcParent.left;
    cyParent = rcParent.bottom - rcParent.top;

    // Get the display limits
    hdc = GetDC(hwndChild);
    cxScreen = GetDeviceCaps(hdc, HORZRES);
    cyScreen = GetDeviceCaps(hdc, VERTRES);
    ReleaseDC(hwndChild, hdc);

    // Calculate new X position, then adjust for screen
    xNew = rcParent.left + ((cxParent - cxChild) / 2);
    if (xNew < 0)
    {
        xNew = 0;
    }
    else if ((xNew + cxChild) > cxScreen)
    {
        xNew = cxScreen - cxChild;
    }

    // Calculate new Y position, then adjust for screen
    yNew = rcParent.top  + ((cyParent - cyChild) / 2);
    if (yNew < 0)
    {
        yNew = 0;
    }
    else if ((yNew + cyChild) > cyScreen)
    {
        yNew = cyScreen - cyChild;
    }

    // Set it, and return
    return SetWindowPos(hwndChild,
                        NULL,
                        xNew, yNew,
                        0, 0,
                        SWP_NOSIZE | SWP_NOZORDER);
}

//
//  FUNCTION: CmdStub(HWND, WORD, WORD, HWND)
//
//  PURPOSE:  Display statusbar updates by calling UpdateStatusBar
//
//  PARAMETERS:
//    hwnd     - The window.
//    wCommand - Menu command ID
//    wNotify  - Notification number (unused)
//    hwndCtrl - NULL (unused)
//
//  RETURN VALUE:
//    Always returns 0 - command handled.
//
//  COMMENTS:
//    Assumes there is a resource string describing this command with the
//    same ID as the command ID.  Loads the string and calls UpdateStatusBar
//    to put the string into main pane of the status bar.
//

LRESULT CmdStub(HWND hwnd, WORD wCommand, WORD wNotify, HWND hwndCtrl)
{
    char szBuffer[50];
    int  cbWritten = 0;

    cbWritten = LoadString(hInst, wCommand, szBuffer, sizeof(szBuffer));
    if(cbWritten == 0)
    {
        lstrcpy(szBuffer, "Unknown Command");
        UpdateStatusBar(szBuffer, 0, 0);
    }
    else
    {
        UpdateStatusBar(szBuffer, 0, 0);
        MessageBox (hwnd,
                    "Command Not Implemented:\r\n Demonstration Purposes
                        Only",
                    "BarSDI",
                    MB_OK | MB_ICONEXCLAMATION);
    }
     /*
      * Once the command is executed, set the statusbar text to
      * original text.
      */
    UpdateStatusBar(SZDESCRIPTION, 0, 0);

    return 0;
}

Built on: Thursday, October 21, 1999


RESOURCE.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
//{{NO_DEPENDENCIES}}
// Microsoft Visual C++ generated include file.
// Used by BARSDI.RC
//
#define IDS_APPNAME                     1
#define IDS_DESCRIPTION                 2
#define IDD_VERFIRST                    100
#define IDI_APPICON                     101
#define IDB_BITMAP1                     102
#define IDD_DIALOG1                     103
#define IDD_VERLAST                     104
#define IDS_FILEMENU                    1000
#define IDM_FILENEW                     1001
#define IDM_FILEOPEN                    1002
#define IDM_FILESAVE                    1003
#define IDM_FILESAVEAS                  1004
#define IDM_FILECLOSE                   1005
#define IDM_FILEPRINT                   1006
#define IDM_FILEPAGESU                  1007
#define IDM_FILEPRINTSU                 1008
#define IDM_EXIT                        1009
#define IDS_EDITMENU                    2000
#define IDM_EDITUNDO                    2001
#define IDM_EDITCUT                     2002
#define IDM_EDITCOPY                    2003
#define IDM_EDITPASTE                   2004
#define IDM_EDITCLEAR                   2005
#define IDS_HELPMENU                    3000
#define IDM_ABOUT                       3001
#define IDM_ERASE                       4000
#define IDM_PEN                         4001
#define IDM_SELECT                      4002
#define IDM_BRUSH                       4003
#define IDM_AIRBRUSH                    4004
#define IDM_FILL                        4005
#define IDM_LINE                        4006
#define IDM_EYEDROP                     4007
#define IDM_ZOOM                        4008
#define IDM_RECT                        4009
#define IDM_FRAME                       4010
#define IDM_OVAL                        4011
#define IDC_STATIC                      -1

// Next default values for new objects
//
#ifdef APSTUDIO_INVOKED
#ifndef APSTUDIO_READONLY_SYMBOLS
#define _APS_NO_MFC                     1
#define _APS_NEXT_RESOURCE_VALUE        104
#define _APS_NEXT_COMMAND_VALUE         40001
#define _APS_NEXT_CONTROL_VALUE         1000
#define _APS_NEXT_SYMED_VALUE           101
#endif
#endif

Built on: Thursday, October 21, 1999


STATBAR.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE: statbar.c
//
//  PURPOSE: Handles general routines for the Barsdi sample.
//
//  FUNCTIONS:
//    MsgTimer      - Handles the WM_TIMER messages to set the time on
//                    the status bar.
//    MsgMouseMove  - Handles the WM_MOUSEMOVE to display the cursor
//                    position.
//    MsgMenuSelect - Handle the WM_MENUSELECT message. This message will
//                    enable the status bar control to update when the user
//                    moves across menu items on the main window.
//    InitializeStatusBar - Sets the pane positions in the statusbar control
//    CreateSBar    - Calls CreateStatusWindow() to create the status bar
//    UpdateStatusBar - Updates the statusbar control with appropriate text
//

#include <windows.h>            // required for all Windows applications
#include <windowsx.h>
#include <commctrl.h>           // prototypes and defs for common controls
#include "globals.h"            // prototypes specific to this application
#include "statbar.h"            // prototypes specific to statbar.c
#include "resource.h"

// Global Variables for the status bar control.

HWND  hWndStatusbar;

//  **TODO**  Add entries to the string table in barsdi.rc for each menu
//            command.  MsgMenuSelect (below) loads these strings to display
//            information in the status bar.  MsgMenuSelect assumes that the
//            string ID is the same as the command ID and that a string
//            exists for every command.
//
// The following array contains resource string ID's for popup menus
// in the main application menu.  This array is used by MsgMenuSelect
// to display information in the status bar.
//
//  **TODO**  Add entries to this array for each popup menu in the same
//            positions as they appear in the main menu.  Remember to define
//            the ID's in globals.h and add the strings to barsdi.rc.

UINT idPopup[ ] =
{
    IDS_FILEMENU,
    IDS_EDITMENU,
    IDS_HELPMENU,
};

//
//  FUNCTION: MsgTimer(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE: Calls GetLocalTime() to set the time on the status bar
//
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Unused)
//    uMessage  - Message number (Unused)
//    wparam    - Extra data     (Unused)
//    lparam    - Extra data     (Unused)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//
//    Every time the window procedure receives a Timer message, it calls
//    GetLocalTime() to obtain the time and then formats the time into
//    a string. The time sting is then displayed on the status bar.
//

LRESULT MsgTimer(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    char        szBuf[16];      // Temp buffer.
    SYSTEMTIME  sysTime;

    GetLocalTime(&sysTime);

    wsprintf(szBuf,
             "%2d:%02d:%02d %s",
             (sysTime.wHour == 0 ? 12 :
             (sysTime.wHour <= 12 ? sysTime.wHour : sysTime.wHour -12)),
             sysTime.wMinute,
             sysTime.wSecond,
             (sysTime.wHour < 12 ? "AM":"PM"));

    UpdateStatusBar(szBuf, 4, 0);
    return 0;
}

//
//  FUNCTION: MsgMousemove(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  Obtains the Cursor position to display coordinates on
//            the staus bar.
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Unused)
//    uMessage  - Message number (Unused)
//    wparam    - Extra data     (Unused)
//    lparam    - Extra data     (Used)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//
//    The mouse coordinates (x and y) are in the HI And LO words
//    of LPARAM
//
//

LRESULT MsgMousemove(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    char szBuf[20];             // Array for formatting mouse coordinates

    wsprintf(szBuf, "%d,%d", LOWORD(lparam), HIWORD(lparam));

    // reset the first partition of the status bar to
    // display the application title.
    UpdateStatusBar("Toolbar/Statubar Sample", 0, 0);

     // Display the mouse position in the 2nd partition.
    UpdateStatusBar(szBuf, 2, 0);
    return 0;
}

//
//  FUNCTION: MsgNCMousemove(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  Processes the non client area messages to reset the
//            first partition of the staus bar.
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Unused)
//    uMessage  - Message number (Unused)
//    wparam    - Extra data     (Unused)
//    lparam    - Extra data     (Used)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//
//
//

LRESULT MsgNCMousemove(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    UpdateStatusBar("Toolbar/Statubar Sample", 0, 0);
    return 0;
}

//
//  FUNCTION: MsgMenuSelect(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  Upadates menu selections on the staus bar.
//
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Used)
//    uMessage  - Message number (Used)
//    wparam    - Extra data     (Used)
//    lparam    - Extra data     (Used)
//
//  RETURN VALUE:
//
//    Always returns 0 - Message handled
//
//  COMMENTS:
//    This message is sent when the user selects menu items by
//    by pulling down  a popup menu move the mouse around to highlite
//    different menu items.
//
//

LRESULT MsgMenuSelect(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{
    static char szBuffer[128];
    UINT   nStringID = 0;
    UINT   fuFlags = GET_WM_MENUSELECT_FLAGS(wparam, lparam) & 0xffff;
    UINT   uCmd    = GET_WM_MENUSELECT_CMD(wparam, lparam);
    HMENU  hMenu   = GET_WM_MENUSELECT_HMENU(wparam, lparam);

    szBuffer[0] = 0;                            // First reset the buffer

    if (fuFlags == 0xffff && hMenu == NULL)     // Menu has been closed
        nStringID = IDS_DESCRIPTION;

    else if (fuFlags & MFT_SEPARATOR)           // Ignore separators
        nStringID = 0;

    else if (fuFlags & MF_POPUP)                // Popup menu
    {
        if (fuFlags & MF_SYSMENU)               // System menu
            nStringID = IDS_SYSMENU;

        else
            // Get string ID for popup menu from idPopup array.
            nStringID = ((uCmd < sizeof(idPopup)/sizeof(idPopup[0])) ?
                            idPopup[uCmd] : 0);
    }  // for MF_POPUP

    else                                        // Must be a command item
        nStringID = uCmd;                       // String ID == Command ID

    // Load the string if we have an ID
    if (0 != nStringID)
        LoadString(hInst, nStringID, szBuffer, sizeof(szBuffer));

    // Finally... send the string to the status bar
    UpdateStatusBar(szBuffer, 0, 0);

    return 0;
}

//
//  FUNCTION: InitializeStatusBar(HWND)
//
//  PURPOSE:  Initialize statusbar control with time and mouse positions.
//
//
//  PARAMETERS:
//
//  hwndParent - Window handle of the status bar's parent
//
//
//  RETURN VALUE:  NONE
//
//
//  COMMENTS:
//
//   This function initializes the time  and mouse positions sections of
//   the statubar window. The Date for the time section is obtained by
//   calling SetTimer API. When the timer messages start comming in,
//   GetSytemTime() to fill the time section.
//   The WPARAM of SB_SETTEXT is divided into 2 parameters. The LOWORD
//   determines which section/part the text goes into, and the HIWORD
//   tells how the bar is drawn (popin or popout).
//

void InitializeStatusBar(HWND hwndParent)
{
    const cSpaceInBetween = 8;
    int   ptArray[5];   // Array defining the number of parts/sections
    SIZE  size;         // the Status bar will display.
    RECT  rect;
    HDC   hDC;

   /*
    * Fill in the ptArray...
    */

    hDC = GetDC(hwndParent);
    GetClientRect(hwndParent, &rect);

    ptArray[4] = rect.right;

    if (GetTextExtentPoint(hDC, "00:00:00 PM", 12, &size))
        ptArray[3] = ptArray[4] - (size.cx) - cSpaceInBetween;
    else
        ptArray[3] = 0;

    if (GetTextExtentPoint(hDC, "Time:", 6, &size))
        ptArray[2] = ptArray[3] - (size.cx) - cSpaceInBetween;
    else
        ptArray[2] = 0;

    if (GetTextExtentPoint(hDC, "123,123", 8, &size))
        ptArray[1] = ptArray[2] - (size.cx) - cSpaceInBetween;
    else
        ptArray[1] = 0;

    if (GetTextExtentPoint(hDC, "Cursor Pos:", 12, &size))
        ptArray[0] = ptArray[1] - (size.cx) - cSpaceInBetween;
    else
        ptArray[0] = 0;

    ReleaseDC(hwndParent, hDC);

    SendMessage(hWndStatusbar,
                SB_SETPARTS,
                sizeof(ptArray)/sizeof(ptArray[0]),
                (LPARAM)(LPINT)ptArray);

    UpdateStatusBar(SZDESCRIPTION, 0, 0);
    UpdateStatusBar("Cursor Pos:", 1, SBT_POPOUT);
    UpdateStatusBar("Time:", 3, SBT_POPOUT);
}

//
//  FUNCTION: CreateSBar(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  Calls CreateStatusWindow() to create the status bar
//
//
//  PARAMETERS:
//
//  hwndParent - Window handle of the status bar's parent
//
//  RETURN VALUE:
//
//  If both controls were created successfully Return TRUE,
//  else returns FALSE.
//
//  COMMENTS:
//
//

BOOL CreateSBar(HWND hwndParent)
{
    hWndStatusbar = CreateStatusWindow(WS_CHILD | WS_VISIBLE | WS_BORDER,
                                       SZDESCRIPTION,
                                       hwndParent,
                                       IDM_STATUSBAR);
    if(hWndStatusbar)
    {
        InitializeStatusBar(hwndParent);
        SetTimer(hwndParent, IDM_TIMER, TIMER_TIMEOUT, NULL);
        return TRUE;
    }

    return FALSE;
}

//
//  FUNCTION: UpdateStatusBar(HWND)
//
//  PURPOSE:  Updates the statusbar control with appropriate text
//
//
//  PARAMETERS:
//
//  lpszStatusString - text to be displayed
//  partNumber       - which part of the status bar to display text in
//  displayFlags     - display flags
//
//
//  RETURN VALUE: NONE
//
//
//  COMMENTS:
//      None
//
//

void UpdateStatusBar(LPSTR lpszStatusString, WORD partNumber, WORD displayFlags)
{
    SendMessage(hWndStatusbar,
                SB_SETTEXT,
                partNumber | displayFlags,
                (LPARAM)lpszStatusString);
}

Built on: Thursday, October 21, 1999


STATBAR.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
// PURPOSE:
//    Contains declarations for the status bar module.
//

//-------------------------------------------------------------------------
#define IDM_STATUSBAR       501
#define IDM_TIMER           701
#define TIMER_TIMEOUT       1000

// System Menu string ID's
#define IDS_SYSMENU         900

#define IDS_SCSIZE          SC_SIZE
#define IDS_SCMOVE          SC_MOVE
#define IDS_SCMINIMIZE      SC_MINIMIZE
#define IDS_SCMAXIMIZE      SC_MAXIMIZE
#define IDS_SCCLOSE         SC_CLOSE
#define IDS_SCRESTORE       SC_RESTORE
#define IDS_SCTASKLIST      SC_TASKLIST

// Global variables for status bar window
extern HWND hWndStatusbar;

// Function prototypes for status bar creation
BOOL CreateSBar(HWND);
void InitializeStatusBar(HWND);
void UpdateStatusBar(LPSTR, WORD, WORD);

Built on: Thursday, October 21, 1999


TOOLBAR.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE: toolbar.c
//
//  PURPOSE: Handles general routines for the Toolbar control
//
//  FUNCTIONS:
//    CreateTBar    - Creates the Toolbar control for the sample.
//    MsgNotify     - Handles the WM_NOTIFY message that gets sent to
//                    the parent window to get ToolTip Text.
//  COMMENTS:
//

#include <windows.h>            // required for all Windows applications
#include <windowsx.h>
#include <commctrl.h>           // prototypes and defs for common controls
#include "globals.h"            // prototypes specific to this application
#include "toolbar.h"            // prototypes and #defines for toolbar.c
#include "statbar.h"
#include "resource.h"

// Global Variable for the toolbar control.

HWND    hWndToolbar;

//  **TODO**  Change the following values to match your toolbar bitmap
//
// NUMIMAGES    = Number of images in toolbar.bmp.  Note that this is not
//                the same as the number of elements on the toolbar.
// IMAGEWIDTH   = Width of a single button image in toolbar.bmp
// IMAGEHEIGHT  = Height of a single button image in toolbar.bmp
// BUTTONWIDTH  = Width of a button on the toolbar (zero = default)
// BUTTONHEIGHT = Height of a button on the toolbar (zero = default)

#define NUMIMAGES       20
#define IMAGEWIDTH      18
#define IMAGEHEIGHT     17
#define BUTTONWIDTH     0
#define BUTTONHEIGHT    0

//  **TODO**  Add/remove entries in the following array to define the
//            toolbar buttons (see documentation for TBBUTTON).

TBBUTTON tbButton[ ] =
{
    {0,   IDM_FILENEW,     TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {1,   IDM_FILEOPEN,    TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {2,   IDM_FILESAVE,    TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {3,   IDM_EDITCUT,     TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {0,   0,               TBSTATE_ENABLED, TBSTYLE_SEP,    0, 0},
    {4,   IDM_EDITCOPY,    TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {5,   IDM_EDITPASTE,   TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {6,   IDM_FILEPRINT,   TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {0,   0,               TBSTATE_ENABLED, TBSTYLE_SEP,    0, 0},
    {7,   IDM_ABOUT,       TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
};

TBBUTTON tbButtonNew[ ] =
{
    { 8,  IDM_ERASE,       TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    { 9,  IDM_PEN,         TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {10,  IDM_SELECT,      TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {11,  IDM_BRUSH,       TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {12,  IDM_AIRBRUSH,    TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {13,  IDM_FILL,        TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {14,  IDM_LINE,        TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {15,  IDM_EYEDROP,     TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {16,  IDM_ZOOM,        TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {17,  IDM_RECT,        TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {18,  IDM_FRAME,       TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},
    {19,  IDM_OVAL,        TBSTATE_ENABLED, TBSTYLE_BUTTON, 0, 0},

};

//
//  FUNCTION: CreateTBar(HWND)
//
//  PURPOSE:  Calls CreateToolBarEx()
//
//
//  PARAMETERS:
//
//  hwnd - Window handle : Used for the hWndParent parameter of the control.
//
//  RETURN VALUE:
//
//  If toolbar control was created successfully Return TRUE,
//  else returns FALSE.
//
//  COMMENTS:
//
//

char pszStrings[ ] = {'&','N','E','W','\0','\0'};

BOOL CreateTBar(HWND hwnd)
{
  int iNew;
  UINT ID;

  hWndToolbar = CreateToolbarEx(hwnd,
                                  WS_CHILD | WS_VISIBLE
                                  | CCS_ADJUSTABLE | TBSTYLE_TOOLTIPS,
                                  IDM_TOOLBAR,
                                  NUMIMAGES,
                                  hInst,
                                  IDB_BMP,
                                  tbButton,
                                  sizeof(tbButton)/sizeof(TBBUTTON),
                                  BUTTONWIDTH,
                                  BUTTONHEIGHT,
                                  IMAGEWIDTH,
                                  IMAGEHEIGHT,
                                  sizeof(TBBUTTON));
    iNew = SendMessage(hWndToolbar, TB_ADDSTRING,(WPARAM) 0, (LPARAM) pszStrings);
    iNew = SendMessage(hWndToolbar, TB_MAPACCELERATOR, (WPARAM) 'N', (LPARAM) &ID);

    return (hWndToolbar != NULL);
}

//
//  FUNCTION: MsgNotify(HWND, UINT, WPARAM, LPARAM)
//
//  PURPOSE:  WM_NOTIFY is sent to the parent window to retrieve the
//            ToolTip text associated with that toolbar button.
//
//  PARAMETERS:
//
//    hwnd      - Window handle  (Unused)
//    uMessage  - Message number (Unused)
//    wparam    - Extra data     (Unused)
//    lparam    - TOOLTIPTEXT FAR*
//
//  RETURN VALUE:
//    Always returns 0 - Message handled
//
//
//  COMMENTS:
//    This message fills in the lpszText field of the TOOLTIPTEXT
//    structure if code == TTN_NEEDTEXT
//

LRESULT MsgNotify(HWND hwnd, UINT uMessage, WPARAM wparam, LPARAM lparam)
{

    LPTOOLTIPTEXT   lpToolTipText;
    static char     szBuffer[64];
    static UINT     i=0;
    LPNMHDR         lpnmhdr;

    lpToolTipText = (LPTOOLTIPTEXT)lparam;
    lpnmhdr = (LPNMHDR)lparam;

    // We do this to customize the toolbar; otherwise
    // the customize dialog box goes away.

    if (lpnmhdr->code == TBN_QUERYINSERT)
        return TRUE;

    else if (lpnmhdr->code == TBN_QUERYDELETE)
    {
        return TRUE;
    }

    else if (lpnmhdr->code == TBN_DELETINGBUTTON)
    {
        return TRUE;
    }

    else if (lpnmhdr->code == TBN_BEGINDRAG)
        return TRUE;

    else if (lpnmhdr->code == TBN_ENDDRAG)
        return TRUE;

    else if (lpnmhdr->code == TBN_BEGINADJUST)
        return TRUE;

    else if (lpnmhdr->code == TBN_INITCUSTOMIZE)
        return TRUE;

    else

    if (lpnmhdr->code == TBN_GETBUTTONINFO)
    {
        LPTBNOTIFY lpTbNotify = (LPTBNOTIFY)lparam;
        char  szBuffer [20];
        if (lpTbNotify->iItem < 12)    // 20 = the total number of buttons
        {                              // tbButton and tbButtonNew
                                                    // Send back information about the
                                                    // other 12 buttons in tbButtonNew;

            lpTbNotify->tbButton = tbButtonNew[lpTbNotify->iItem];

            LoadString(hInst,
                       4000+ lpTbNotify->iItem,   // string ID == command ID
                       szBuffer,
                       sizeof(szBuffer));

            lstrcpy (lpTbNotify->pszText, szBuffer);
            lpTbNotify->cchText = sizeof (szBuffer);
            return TRUE;
        }
        else
        return 0;
    }

    else
    if (lpToolTipText->hdr.code == TTN_NEEDTEXT)
    {

        LoadString(hInst,
                   lpToolTipText->hdr.idFrom,   // string ID == command ID
                   szBuffer,
                   sizeof(szBuffer));

        UpdateStatusBar(lpToolTipText->lpszText, 0, 0);

//        lpToolTipText->lpszText = szBuffer;
// Depending on what is entered into the hInst parameter of TOOLTIPTEXT
// structure, the lpszText member can be a buffer or an INTEGER VALUE
// obtained from MAKEINTRESOURCE()...

        lpToolTipText->hinst = hInst;
        lpToolTipText->lpszText = MAKEINTRESOURCE(lpToolTipText->hdr.idFrom);
    }

    return 0;
}

Built on: Thursday, October 21, 1999


TOOLBAR.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
// PURPOSE:
//    Contains declarations for the toolbar module.
//

//-------------------------------------------------------------------------
#define IDM_TOOLBAR         500 // ID for the toolbar.
#define IDB_BMP             700 // Bitmap ID for the toolbar.

// Global variable for Toolbar window
extern HWND hWndToolbar;

// Function protoptype for Creating Toolbar
BOOL CreateTBar(HWND);

Built on: Thursday, October 21, 1999


WINMAIN.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

--*/

// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//
// Copyright (C) 1993-1995 Microsoft Corporation.  All Rights Reserved.
//
//  MODULE:   winmain.c
//
//  PURPOSE:   Calls initialization functions and processes the message loop
//
//
//  PLATFORMS: Windows 95, NT
//
//  FUNCTIONS:
//    WinMain() - calls initialization functions, processes message loop
//
//  COMMENTS:
//
//

#include <windows.h>            // required for all Windows applications
#include "globals.h"            // prototypes specific to this application

//
//  FUNCTION: WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
//
//  PURPOSE: calls initialization function, processes message loop
//
//  PARAMETERS:
//
//    hInstance - The handle to the instance of this application that
//          is currently being executed.
//
//    hPrevInstance - This parameter is always NULL in Win32
//          applications.
//
//    lpCmdLine - A pointer to a null terminated string specifying the
//          command line of the application.
//
//    nCmdShow - Specifies how the main window is to be diplayed.
//
//  RETURN VALUE:
//    If the function terminates before entering the message loop,
//    return FALSE.
//    Otherwise, return the WPARAM value sent by the WM_QUIT message.
//
//
//  COMMENTS:
//
//    Windows recognizes this function by name as the initial entry point
//    for the program.  This function calls the initialization routine
//    It then executes a message retrieval and dispatch loop that is the
//    top-level control structure for the remainder of execution.  The
//    loop is terminated when a WM_QUIT  message is received, at which
//    time this function exits the application instance by returning the
//    value passed by PostQuitMessage().
//
//    If this function must abort before entering the message loop, it
//    returns the conventional value NULL.
//

int WINAPI   WinMain(HINSTANCE hInstance,
                     HINSTANCE hPrevInstance,
                     LPSTR lpCmdLine,
                     int nCmdShow)
{
    MSG msg;
    HANDLE hAccelTable;

    // Initialize application by setting up the main window.
    if (!InitApplication(hInstance, nCmdShow))
    {
        return FALSE;           // Exits if unable to initialize
    }

    hAccelTable = LoadAccelerators(hInstance, szAppName);

    // Acquire and dispatch messages until a WM_QUIT message is received.
    while( GetMessage(&msg, NULL, 0, 0))
    {
        if (!TranslateAccelerator (msg.hwnd, hAccelTable, &msg))
        {
            TranslateMessage(&msg);  // Translates virtual key codes
            DispatchMessage(&msg);   // Dispatches message to window
        }
    }
    return msg.wParam;  // Returns the value from PostQuitMessage
}

Built on: Thursday, October 21, 1999


Toolbar1

Toolbar1 Sample Application

This sample program implements a simple Hello application with a toolbar added. It is implemented in the following source files:

  • Hello.c: The C source code.
  • Hello.h: The header file for Hello.c.
  • Hello.rc: The Resource file.


HELLO.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:Hello

--*/

/**************************************************************
This is a simple Hello program with an application-defined function,
CreateAToolBar, that creates a toolbar. CreateAToolBar uses
CreateWindowEx to create a toolbar with three buttons. The buttons
have text labels. The label text is loaded from hello.rc and the
identifiers for the buttons are defined in hello.h.
**************************************************************/

#include <windows.h>
#include <commctrl.h>
#include "hello.h"

long PASCAL WndProc (HWND, UINT, WPARAM, LPARAM);
HWND CreateAToolBar(HWND);

HINSTANCE hInst;
int NUM_BUTTONS = 3;

int APIENTRY WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,
                    LPSTR lpszCmdParam, int nCmdShow)
{
    static char         szAppName[ ] = "HelloWin";
    HWND                hwnd;
    MSG                 msg;
    WNDCLASS            wndclass;

    if (!hPrevInstance)
    {
        wndclass.style          = CS_HREDRAW|CS_VREDRAW;
        wndclass.lpfnWndProc    = WndProc;
        wndclass.cbClsExtra     = 0;
        wndclass.cbWndExtra     = 0;
        wndclass.hInstance      = hInstance;
        wndclass.hIcon          = LoadIcon (NULL, IDI_APPLICATION);
        wndclass.hCursor        = LoadCursor (NULL, IDC_ARROW);
        wndclass.hbrBackground  = GetStockObject (WHITE_BRUSH);
        wndclass.lpszMenuName   = NULL;
        wndclass.lpszClassName  = szAppName;

        RegisterClass (&wndclass);
    }

    hwnd = CreateWindow(szAppName,
                        "The Hello Program",
                        WS_OVERLAPPEDWINDOW,
                        CW_USEDEFAULT,
                        CW_USEDEFAULT,
                        CW_USEDEFAULT,
                        CW_USEDEFAULT,
                        NULL,
                        NULL,
                        hInstance,
                        NULL);

    hInst = hInstance;
    ShowWindow (hwnd, nCmdShow);
    UpdateWindow (hwnd);

    while (GetMessage (&msg, NULL, 0, 0))
    {
        TranslateMessage (&msg);
        DispatchMessage (&msg);
    }
    return msg.wParam;
}

long APIENTRY WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
    {
        HDC         hdc;
        PAINTSTRUCT ps;
        RECT        rect;

        switch (message)
        {
        switch (message)
        {
        case WM_CREATE:
            CreateAToolBar(hwnd);
            return 0;
        case WM_PAINT:
            hdc = BeginPaint (hwnd, &ps);
            GetClientRect (hwnd, &rect);
            SetBkMode(hdc, TRANSPARENT);
            DrawText (hdc, "Hello Windows!", -1, &rect,
                DT_SINGLELINE|DT_CENTER|DT_VCENTER);
            SetTextColor(hdc, RGB(255, 0, 0));
            TextOut(hdc, rect.right/2, 200, "Hello World", 11);
            EndPaint (hwnd, &ps);
            return 0;
        case WM_DESTROY:
            PostQuitMessage (0);
            return 0;
        }

    return DefWindowProc (hwnd, message, wParam, lParam);
    }

HWND CreateAToolBar(HWND hwndParent)
{
    HWND hwndTB;
    TBBUTTON tbb[3];
    char szBuf[16];
    int iCut, iCopy, iPaste;
    int MAX_LEN = 10;
    INITCOMMONCONTROLSEX icex;

    // Ensure that the common control DLL is loaded.
    icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
    icex.dwICC  = ICC_BAR_CLASSES;
    InitCommonControlsEx(&icex);
    //Create a toolbar that the user can customize and that has a
    // ToolTip associated with it.
    hwndTB = CreateWindowEx(0, TOOLBARCLASSNAME, (LPSTR) NULL,
       WS_CHILD | TBSTYLE_TOOLTIPS | CCS_ADJUSTABLE,
       0, 0, 0, 0, hwndParent, (HMENU) ID_TOOLBAR, g_hinst, NULL);

    // Send the TB_BUTTONSTRUCTSIZE message, which is required for
    // backward compatibility.
    SendMessage(hwndTB, TB_BUTTONSTRUCTSIZE,
        (WPARAM) sizeof(TBBUTTON), 0);

    // Add the button strings to the toolbar.
    LoadString(hInst, IDS_CUT, (LPSTR) &szBuf, MAX_LEN);
    iCut = SendMessage(hwndTB, TB_ADDSTRING, 0, (LPARAM) (LPSTR) &szBuf);

    LoadString(hInst, IDS_COPY, (LPSTR) &szBuf, MAX_LEN);
    iCopy = SendMessage(hwndTB, TB_ADDSTRING, (WPARAM) 0,
        (LPARAM) (LPSTR) szBuf);

    LoadString(hInst, IDS_PASTE, (LPSTR) &szBuf, MAX_LEN);
    iPaste = SendMessage(hwndTB, TB_ADDSTRING, (WPARAM) 0,
        (LPARAM) (LPSTR) szBuf);

    // Fill the TBBUTTON array with button information, and add the
    // buttons to the toolbar.
    tbb[0].iBitmap = -1;
    tbb[0].idCommand = IDS_CUT;
    tbb[0].fsState = TBSTATE_ENABLED;
    tbb[0].fsStyle = TBSTYLE_BUTTON;
    tbb[0].dwData = 0;
    tbb[0].iString = iCut;

    tbb[1].iBitmap = -1;
    tbb[1].idCommand = IDS_COPY;
    tbb[1].fsState = TBSTATE_ENABLED;
    tbb[1].fsStyle = TBSTYLE_BUTTON;
    tbb[1].dwData = 0;
    tbb[1].iString = iCopy;

    tbb[2].iBitmap = -1;
    tbb[2].idCommand = IDS_PASTE;
    tbb[2].fsState = TBSTATE_ENABLED;
    tbb[2].fsStyle = TBSTYLE_AUTOSIZE;
    tbb[2].dwData = 0;
    tbb[2].iString = iPaste; //(int) pszBuf2;

SendMessage(hwndTB, TB_ADDBUTTONS, (WPARAM) NUM_BUTTONS,
        (LPARAM) (LPTBBUTTON) &tbb);

SendMessage(hwndTB, TB_AUTOSIZE, 0, 0);
ShowWindow(hwndTB, SW_SHOWNORMAL);

return hwndTB;
}

/*
</BODY>
</HTML>
*/

Built on: Thursday, October 21, 1999


HELLO.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
//Toolbar ID
#define ID_TOOLBAR 1

//Toolbar button IDs
#define IDB_BUTTONS 2
#define IDS_CUT 3
#define IDS_COPY 4
#define IDS_PASTE 5
/*
</BODY>
</HTML>
*/

Built on: Thursday, October 21, 1999


HELLO.RC

#include "hello.h"

STRINGTABLE
{
IDS_CUT, "CUT"
IDS_COPY, "COPY"
IDS_PASTE, "PASTE"
}

/*
</BODY>
</HTML>
*/

Built on: Thursday, October 21, 1999


Toolbar2

Toolbar2 Sample Application

This sample program implements a simple Hello application with a toolbar added. It is implemented in the following source files:

  • Hello.c: The C source code.
  • Hello.h: The header file for Hello.c.


HELLO.C

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:Hello

--*/

/******************************************************************
This is a simple Hello program with an application-defined function,
CreateAToolBar2, that creates a toolbar. CreateAToolBar2 uses
CreateToolbarEx to create a toolbar with seven buttons and a separator.
CreateAToolbar2 adds three standard file bitmaps and four view bitmaps.
The identifiers for the buttons are defined in hello.h. By changing the
parameters passed to CreateToolbarEx you can created different types of toolbar. At the end of this file some examples are given.
*******************************************************************/

#include <windows.h>
#include <commctrl.h>
#include "hello.h"

HWND CreateAToolBar2 (HWND);
long PASCAL WndProc (HWND, UINT, WPARAM, LPARAM);

HINSTANCE hInst;

int APIENTRY WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,
                    LPSTR lpszCmdParam, int nCmdShow)
{
    static char         szAppName[ ] = "HelloWin";
    HWND                hwnd;
    MSG                 msg;
    WNDCLASS            wndclass;

    if (!hPrevInstance)
    {
        wndclass.style          = CS_HREDRAW|CS_VREDRAW;
        wndclass.lpfnWndProc    = WndProc;
        wndclass.cbClsExtra     = 0;
        wndclass.cbWndExtra     = 0;
        wndclass.hInstance      = hInstance;
        wndclass.hIcon          = LoadIcon (NULL, IDI_APPLICATION);
        wndclass.hCursor        = LoadCursor (NULL, IDC_ARROW);
        wndclass.hbrBackground  = GetStockObject (WHITE_BRUSH);
        wndclass.lpszMenuName   = NULL;
        wndclass.lpszClassName  = szAppName;

        RegisterClass (&wndclass);
    }

    hwnd = CreateWindow(szAppName,
                        "The Hello Program",
                        WS_OVERLAPPEDWINDOW,
                        CW_USEDEFAULT,
                        CW_USEDEFAULT,
                        CW_USEDEFAULT,
                        CW_USEDEFAULT,
                        NULL,
                        NULL,
                        hInstance,
                        NULL);

    ShowWindow (hwnd, nCmdShow);
    UpdateWindow (hwnd);
    hInst = hInstance;

    while (GetMessage (&msg, NULL, 0, 0))
    {
        TranslateMessage (&msg);
        DispatchMessage (&msg);
    }
    return msg.wParam;
}

long APIENTRY WndProc (HWND hwnd, UINT message, WPARAM wParam, LPARAM lParam)
    {
        HDC         hdc;
        PAINTSTRUCT ps;
        RECT        rect;

        switch (message)
        {
        case WM_CREATE:
            CreateAToolBar2(hwnd);
            return 0;
        case WM_PAINT:
            hdc = BeginPaint (hwnd, &ps);
            GetClientRect (hwnd, &rect);
            SetBkMode(hdc, TRANSPARENT);
            DrawText (hdc, "Hello Windows!", -1, &rect,
                DT_SINGLELINE|DT_CENTER|DT_VCENTER);
            SetTextColor(hdc, RGB(255, 0, 0));
            TextOut(hdc, rect.right/2, 200, "Hello World", 11);
            return 0;

        case WM_NOTIFY:
            return 0;

        case WM_DESTROY:
            PostQuitMessage (0);
            return 0;
        }

    return DefWindowProc (hwnd, message, wParam, lParam);
    }

HWND CreateAToolBar2(HWND hWndParent)
{
HWND hWndToolbar;
TBADDBITMAP tb;
int index, stdidx;
INITCOMMONCONTROLSEX icex;

// Toolbar buttons
TBBUTTON tbButtons [ ] =
{
{STD_FILENEW, IDM_NEW, TBSTATE_ENABLED, TBSTYLE_BUTTON, 0L, 0},
{STD_FILEOPEN, IDM_OPEN, TBSTATE_ENABLED, TBSTYLE_BUTTON, 0L, 0},
{STD_FILESAVE, IDM_SAVE, TBSTATE_ENABLED, TBSTYLE_BUTTON, 0L, 0},
{0, 0, TBSTATE_ENABLED, TBSTYLE_SEP, 0L, 0},
{VIEW_LARGEICONS, IDM_LARGEICON, TBSTATE_ENABLED, TBSTYLE_BUTTON,
0L, 0},
{VIEW_SMALLICONS, IDM_SMALLICON, TBSTATE_ENABLED, TBSTYLE_BUTTON,
0L, 0},
{VIEW_LIST, IDM_LISTVIEW, TBSTATE_ENABLED, TBSTYLE_BUTTON,
0L, 0},
{VIEW_DETAILS, IDM_REPORTVIEW, TBSTATE_ENABLED, TBSTYLE_BUTTON,
0L, 0},
};

// Ensure that the common control DLL is loaded.
icex.dwSize = sizeof(INITCOMMONCONTROLSEX);
icex.dwICC  = ICC_BAR_CLASSES;
InitCommonControlsEx(&icex);

// Create the toolbar and add the first three buttons and a separator.
hWndToolbar = CreateToolbarEx (hWndParent,
WS_CHILD | WS_BORDER | WS_VISIBLE | TBSTYLE_TOOLTIPS,
ID_TOOLBAR, 11, (HINSTANCE)HINST_COMMCTRL, IDB_STD_SMALL_COLOR,
(LPCTBBUTTON)&tbButtons, 4, 0, 0, 100, 30, sizeof (TBBUTTON));

// Add the next four buttons
tb.hInst = HINST_COMMCTRL;
tb.nID = IDB_VIEW_SMALL_COLOR;
stdidx = SendMessage (hWndToolbar, TB_ADDBITMAP, 12, (LPARAM)&tb);

for (index = 4; index < NUM_BUTTONS; index++)
tbButtons[index].iBitmap += stdidx;

SendMessage (hWndToolbar, TB_ADDBUTTONS, 4, (LONG) &tbButtons[4]);

return hWndToolbar;

}

/****************************************************************
Flat Toolbar - To create a flat toolbar add TBSTYLE_FLAT.

hWndToolbar = CreateToolbarEx (hWndParent,
WS_CHILD | WS_VISIBLE | TBSTYLE_TOOLTIPS | TBSTYLE_FLAT,
ID_TOOLBAR, 11, (HINSTANCE)HINST_COMMCTRL, IDB_STD_SMALL_COLOR, (LPCTBBUTTON)&tbButtons, 4, 0, 0, 100, 30, sizeof (TBBUTTON));
****************************************************************/
/****************************************************************
Transparent Toolbar - To create a transparent toolbar add
TBSTYLE_TRANSPARENT.

hWndToolbar = CreateToolbarEx (hWndParent,
WS_CHILD | WS_VISIBLE | TBSTYLE_TOOLTIPS | TBSTYLE_FLAT,
ID_TOOLBAR, 11, (HINSTANCE)HINST_COMMCTRL, IDB_STD_SMALL_COLOR, (LPCTBBUTTON)&tbButtons, 4, 0, 0, 100, 30, sizeof (TBBUTTON));
****************************************************************/
/*
</BODY>
</HTML>
*/

Built on: Thursday, October 21, 1999


HELLO.H

/*++

Copyright (c) 1998  Microsoft Corporation
All rights reserved.

Module Name:

Abstract:

    Sample header

--*/
#define ID_TOOLBAR 1

#define IDM_NEW 2
#define IDM_OPEN 3
#define IDM_SAVE 4
#define IDM_LARGEICON 5
#define IDM_SMALLICON 6
#define IDM_LISTVIEW 7
#define IDM_REPORTVIEW 8

#define NUM_BUTTONS 8

/*
</BODY>
</HTML>
*/

Built on: Thursday, October 21, 1999


ToolTip Controls

ToolTip controls are pop-up windows that display text. The text usually describes a tool, which is either a window, such as a child window or control, or an application-defined rectangular area within a window's client area.

The ToolTip controls are described in the following articles.

  • What's New in ToolTip Controls
  • About ToolTip Controls
  • Using ToolTip Controls
  • ToolTip Control Reference


What's New in ToolTip Controls

ToolTip features introduced with version 4.70 of the common controls include:

  • Tracking ToolTips, which are ToolTip windows that you can dynamically position on the screen.
  • Multiline ToolTips, which can display ToolTip text on more than one line.

For more information about these features, see ToolTip Behavior and Appearance.

ToolTip features introduced with version 5.80 of the common controls include:

  • Balloon ToolTips.
  • API support for in-place ToolTips.


About ToolTip Controls

ToolTips are hidden most of the time. They appear automatically, or pop up, when the user pauses the mouse pointer over a tool. The ToolTip appears near the pointer and disappears when the user clicks a mouse button or moves the pointer away from the tool.

The ToolTip control in the following illustration displays Parent Folder when the mouse pointer pauses over the toolbar button.

Standard ToolTip control

This section describes how ToolTip controls work and how you create them.

  • ToolTip Behavior and Appearance
  • Creating ToolTip Controls
  • Activating ToolTip Controls
  • Supporting Tools
  • Displaying Text
  • Messaging and Notification
  • Hit Testing
  • Default Message Processing

ToolTip Behavior and Appearance

ToolTip controls can display a single line of text or multiple lines. Their corners can be rounded or square. They might or might not have a stem that points to the tools like a cartoon balloon. ToolTip text can be stationary or can move with the mouse pointer, called tracking. Stationary text can be displayed adjacent to a tool or it can be displayed over a tool, which is referred to as in-place. Standard ToolTips are stationary, display a single line of text, have square corners, and have no stem pointing to the tool.

Tracking ToolTips, which are supported by version 4.70 of the common controls, change position on the screen dynamically. By rapidly updating the position, these ToolTip controls appear to move smoothly, or "track." These are useful when you want ToolTip text to follow the position of the mouse pointer as it moves. For more information about tracking ToolTips and an example with code that shows how you create them, see Tracking ToolTips.

Multiline ToolTips, which are also supported by version 4.70 of the common controls, display text on more than one line. These are useful for displaying lengthy messages. For more information and an example that shows how to create multiline ToolTips, see Multiline ToolTips.

Balloon ToolTips are displayed in a cartoon-style "balloon," with rounded corners and a stem pointing to the tool. They can be either single-line or multiline. The following illustration shows a multiline balloon ToolTip with the stem and rectangle in their default positions. For more information about balloon ToolTips and an example that shows how you create them, see Creating Balloon ToolTips for Status Bar Icons.

Multiline balloon ToolTip

Sometimes text strings that are long enough to display useful information get clipped because they are too long to be displayed completely in a small window or frame. This diminishes the usefulness of the text strings. In-place ToolTips are used to display text strings for objects that have been clipped, such as the folder names shown below in Microsoft® Windows® Explorer, where My Network Places is displayed in an in-place ToolTip. For an example that shows how to create in-place ToolTips, see Creating In-Place ToolTips.

The cursor must hover over a tool for a period of time before the ToolTip is displayed. The default duration of this timeout is controlled by the user's double click time and is typically about one-half second. To specify a non-default timeout value, send the ToolTip control a TTM_SETDELAYTIME message.

Creating ToolTip Controls

To create a ToolTip control, call CreateWindowEx and specify the TOOLTIPS_CLASS window class. This class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, include the InitCommonControlsEx function in your application. You must explicitly define a ToolTip control as topmost. Otherwise, it might be covered by the parent window. The following code fragment shows how to create a ToolTip control.

HWND hwndTip = CreateWindowEx(NULL, TOOLTIPS_CLASS, NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            CW_USEDEFAULT, CW_USEDEFAULT,
                            hwndParent, NULL, hinstMyDll,
                            NULL);

SetWindowPos(hwndTip, HWND_TOPMOST,0, 0, 0, 0,
             SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

The window procedure for the ToolTip control automatically sets the size, position, and visibility of the control. The height of the ToolTip window is based on the height of the font currently selected into the device context for the ToolTip control. The width varies based on the length of the string currently in the ToolTip window.

Activating ToolTip Controls

A ToolTip control can be either active or inactive. When it is active, the ToolTip text appears when the mouse pointer is on a tool. When it is inactive, the ToolTip text does not appear, even if the pointer is on a tool. The TTM_ACTIVATE message activates and deactivates a ToolTip control.

Supporting Tools

A ToolTip control can support any number of tools. To support a particular tool, you must register the tool with the ToolTip control by sending the control the TTM_ADDTOOL message. The message includes the address of a TOOLINFO structure, which provides information the ToolTip control needs to display text for the tool. The uID member of the TOOLINFO structure is defined by the application. Each time you add a tool, your application provides a unique identifier. The cbSize member of the TOOLINFO structure is required, and must specify the size of the structure.

A ToolTip control supports tools implemented as windows (such as child windows or control windows) and as rectangular areas within a window's client area. When you add a tool implemented as a rectangular area, the hwnd member of the TOOLINFO structure must specify the handle to the window that contains the area, and the rect member must specify the client coordinates of the area's bounding rectangle. In addition, the uId member must specify the application-defined identifier for the tool.

When you add a tool implemented as a window, the uId member of the TOOLINFO structure must contain the window handle to the tool. Also, the uFlags member must specify the TTF_IDISHWND value, which tells the ToolTip control to interpret the uId member as a window handle.

Displaying Text

When you add a tool to a ToolTip control, the lpszText member of the TOOLINFO structure must specify the address of the string to display for the tool. After you add a tool, you can change the text using the TTM_UPDATETIPTEXT message.

If the high-order word of lpszText is zero, the low-order word must be the identifier of a string resource. When the ToolTip control needs the text, the system loads the specified string resource from the application instance identified by the hinst member of the TOOLINFO structure.

If you specify the LPSTR_TEXTCALLBACK value in the lpszText member, the ToolTip control notifies the window specified in the hwnd member of the TOOLINFO structure whenever the ToolTip control needs to display text for the tool. The ToolTip control sends the TTN_GETDISPINFO notification message to the window. The message includes the address of a TOOLTIPTEXT structure, which contains the window handle as well as the application-defined identifier for the tool. The window examines the structure to determine the tool for which text is needed, and it fills the appropriate structure members with information that the ToolTip control needs in order to display the string.

Note The maximum length for standard ToolTip text is 80 characters. For more information, see the NMTTDISPINFO structure. Multiline ToolTip text can be longer.

Many applications create toolbars containing tools that correspond to menu commands. For such tools, it is convenient for the ToolTip control to display the same text as the corresponding menu item. The system automatically strips the ampersand (&) accelerator characters from all strings passed to a ToolTip control, unless the control has the TTS_NOPREFIX style.

To retrieve the text for a tool, use the TTM_GETTEXT message.

Messaging and Notification

ToolTip text is normally displayed when the mouse pointer hovers over an area, typically the rectangle defined by a tool such as a button control. However, Microsoft® Windows® only sends mouse-related messages to the window that contains the pointer, not the ToolTip control itself. Mouse-related information must be relayed to the ToolTip control in order for it to display the ToolTip text at the appropriate time and place.

You can have messages relayed automatically if:

  • The tool is a control or is defined as a rectangle in the tool's TOOLINFO structure.
  • The window associated with the tool is in the same thread as the ToolTip control.

If these two conditions are met, set the TTF_SUBCLASS flag in the uFlags member of the tool's TOOLINFO structure when you add the tool to the ToolTip control with TTM_ADDTOOL. The necessary mouse messages then will be relayed automatically to the ToolTip control.

Setting TTF_SUBCLASS to have mouse messages relayed to the control is sufficient for most purposes. However, it will not work in cases where there is no direct connection between the ToolTip control and the tool's window. For example, if a tool is implemented as a rectangular area in an application-defined window, the window procedure receives the mouse messages. Setting TTF_SUBCLASS is sufficient to ensure that they are passed to the control. However, if a tool is implemented as a system-defined window, mouse messages are sent to that window and are not directly available to the application. In this case, you must either subclass the window or use a message hook to access the mouse messages. You must then explicitly relay mouse messages to the ToolTip control with TTM_RELAYEVENT. For an example of how to use TTM_RELAYEVENT, see Tracking ToolTips.

When a ToolTip control receives a WM_MOUSEMOVE message, it determines whether the mouse pointer is in the bounding rectangle of a tool. If it is, the ToolTip control sets a timer. At the end of the time-out interval, the ToolTip control checks the position of the pointer to see if it has moved. If it hasn't, the ToolTip control retrieves the text for the tool and displays the ToolTip. The ToolTip control continues to show the window until it receives a relayed button-up or button-down message or until a WM_MOUSEMOVE message indicates that the pointer has moved outside the bounding rectangle of the tool.

A ToolTip control actually has three time-out durations associated with it. The initial duration is the length of time that the mouse pointer must remain stationary within the bounding rectangle of a tool before the ToolTip window is displayed. The reshow duration is the length of the delay before subsequent ToolTip windows are displayed when the pointer moves from one tool to another. The pop-up duration is the length of time that the ToolTip window remains displayed before it is hidden. That is, if the pointer remains stationary within the bounding rectangle after the ToolTip window is displayed, the ToolTip window is automatically hidden at the end of the pop-up duration. You can adjust all of the time-out durations by using the TTM_SETDELAYTIME message.

If an application includes a tool implemented as a rectangular area and the size or position of the control changes, the application can use the TTM_NEWTOOLRECT message to report the change to the ToolTip control. An application does not need to report size and position changes for a tool implemented as a window because the ToolTip control uses the tool's window handle to determine if the mouse pointer is on the tool, not the tool's bounding rectangle.

When a ToolTip is about to be displayed, the ToolTip control sends the owner window a TTN_SHOW notification message. The owner window receives a TTN_POP notification when a ToolTip is about to be hidden. Each notification is sent in the context of a WM_NOTIFY message.

Hit Testing

The TTM_HITTEST message allows you to retrieve information that a ToolTip control maintains about the tool occupying a particular point. The message includes a TTHITTESTINFO structure that contains a window handle, the coordinates of a point, and the address of a TOOLINFO structure. The ToolTip control determines whether a tool occupies the point and, if it does, fills TOOLINFO with information about the tool.

Default Message Processing

The following table describes the messages handled by the window procedure for the ToolTip control.

Message | Description
WM_CREATE | Ensures that the ToolTip control has the WS_EX_TOOLWINDOW and WS_POPUP window styles. It also allocates memory and initializes internal variables.
WM_DESTROY | Frees resources allocated for the ToolTip control.
WM_GETFONT | Returns the handle of the font that the ToolTip control will use to draw text.
WM_MOUSEMOVE | Hides the ToolTip window.
WM_PAINT | Draws the ToolTip window.
WM_SETFONT | Sets the handle of the font that the ToolTip control will use to draw text.
WM_TIMER | Hides the ToolTip window if the tool has changed position or if the mouse pointer has moved outside the tool. Otherwise, it shows the ToolTip window.
WM_WININICHANGE | Resets internal variables that are based on system metrics.


Using ToolTip Controls

This section contains examples that demonstrate how to create different types of ToolTips.

  • ToolTips for Rectangular Areas
  • Tracking ToolTips
  • Multiline ToolTips
  • Balloon ToolTips
  • In-Place ToolTips

ToolTips for Rectangular Areas

The following example demonstrates how to create a standard ToolTip control and add a tool to it. The example creates a rectangular area, which consists of a window's entire client area, and then uses the TTM_ADDTOOL message to add a ToolTip control to the rectangular area. The TTF_SUBCLASS flag is set in the uFlags member of the TOOLINFO structure to have mouse messages automatically passed to the ToolTip control.

/* CREATE A TOOLTIP CONTROL OVER THE ENTIRE WINDOW AREA */
void CreateMyTooltip (HWND hwnd)
{
                 // struct specifying control classes to register
    INITCOMMONCONTROLSEX iccex;
    HWND hwndTT;                 // handle to the ToolTip control
          // struct specifying info about tool in ToolTip control
    TOOLINFO ti;
    unsigned int uid = 0;       // for ti initialization
    char strTT[30] = "This is your ToolTip string.";
    LPTSTR lptstr = strTT;
    RECT rect;                  // for client area coordinates

    /* INITIALIZE COMMON CONTROLS */
    iccex.dwICC = ICC_WIN95_CLASSES;
    iccex.dwSize = sizeof(INITCOMMONCONTROLSEX);
    InitCommonControlsEx(&iccex);

    /* CREATE A TOOLTIP WINDOW */
    hwndTT = CreateWindowEx(WS_EX_TOPMOST,
        TOOLTIPS_CLASS,
        NULL,
        WS_POPUP | TTS_NOPREFIX | TTS_ALWAYSTIP,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        CW_USEDEFAULT,
        hwnd,
        NULL,
        ghThisInstance,
        NULL
        );

    SetWindowPos(hwndTT,
        HWND_TOPMOST,
        0,
        0,
        0,
        0,
        SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);

    /* GET COORDINATES OF THE MAIN CLIENT AREA */
    GetClientRect (hwnd, &rect);

    /* INITIALIZE MEMBERS OF THE TOOLINFO STRUCTURE */
    ti.cbSize = sizeof(TOOLINFO);
    ti.uFlags = TTF_SUBCLASS;
    ti.hwnd = hwnd;
    ti.hinst = ghThisInstance;
    ti.uId = uid;
    ti.lpszText = lptstr;
        // ToolTip control will cover the whole window
    ti.rect.left = rect.left;
    ti.rect.top = rect.top;
    ti.rect.right = rect.right;
    ti.rect.bottom = rect.bottom;

    /* SEND AN ADDTOOL MESSAGE TO THE TOOLTIP CONTROL WINDOW */
    SendMessage(hwndTT, TTM_ADDTOOL, 0, (LPARAM) (LPTOOLINFO) &ti);
}

The output window for this sample looks like this.

Tracking ToolTips

Tracking ToolTips change position on the screen dynamically. They are supported by version 4.70 and later of the common controls. To create a tracking ToolTip, use the TTM_ADDTOOL message, including the TTF_TRACK flag in the uFlags member of the accompanying TOOLINFO structure.

Your application must manually activate and deactivate a tracking ToolTip by sending a TTM_TRACKACTIVATE message. Activation or deactivation also shows or hides the ToolTip, respectively. While a tracking ToolTip is active, your application must specify the location of the ToolTip by sending TTM_TRACKPOSITION messages to the ToolTip control. Because the application handles tasks such as positioning the ToolTip, tracking ToolTips do not use the TTF_SUBCLASS flag or the TTM_RELAYEVENT message.

The TTM_TRACKPOSITION message causes the ToolTip control to display the window using one of two placement styles:

  • By default, the ToolTip is displayed next to the corresponding tool in a position the control chooses. The location chosen is relative to the coordinates you provide using this message. In this case, the ToolTip window appears to move beside the corresponding tool.
  • If you include the TTF_ABSOLUTE value in the uFlags member of the TOOLINFO structure, the ToolTip will be displayed at the pixel location specified in the message. In this case, the control does not attempt to change the ToolTip window's location from the coordinates you provide.

Example

The following example demonstrates how to create a ToolTip control and assign a tool to it. The example specifies the main window's entire client area as the tool, but you could specify distinct portions of the client area or specify a different window altogether.

The example uses the TTM_ADDTOOL message to add the tool to the ToolTip control. The uFlags member of the TOOLINFO structure used in the example includes the TTF_ABSOLUTE flag. This flag causes the ToolTip control to display ToolTip text at the exact coordinates the application provides when it sends the TTM_TRACKPOSITION message. Without the TTF_ABSOLUTE flag, the ToolTip control chooses a location to display the ToolTip text based on the coordinates you provide. This causes ToolTip text to appear next to the corresponding tool, but not necessarily at the exact coordinates the application provided.

For additional information about using the TTM_TRACKPOSITION message, see Supporting Tracking ToolTips.

HWND WINAPI CreateTT(HWND hwndOwner)
{
    INITCOMMONCONTROLSEX icex;
    HWND        hwndTT;
    TOOLINFO    ti;

    // Load the ToolTip class from the DLL.
    icex.dwSize = sizeof(icex);
    icex.dwICC  = ICC_BAR_CLASSES;

    if(!InitCommonControlsEx(&icex))
       return NULL;

    // Create the ToolTip control.
    hwndTT = CreateWindow(TOOLTIPS_CLASS, TEXT(""),
                          WS_POPUP,
                          CW_USEDEFAULT, CW_USEDEFAULT,
                          CW_USEDEFAULT, CW_USEDEFAULT,
                          NULL, (HMENU)NULL, g_hinst,
                          NULL);

    // Prepare TOOLINFO structure for use as tracking ToolTip.
    ti.cbSize = sizeof(TOOLINFO);
    ti.uFlags = TTF_IDISHWND | TTF_TRACK | TTF_ABSOLUTE;
    ti.hwnd   = hwndOwner;
    ti.uId    = (UINT)g_hwndMain;
    ti.hinst  = g_hinst;
    ti.lpszText  = LPSTR_TEXTCALLBACK;
    ti.rect.left = ti.rect.top = ti.rect.bottom = ti.rect.right = 0;

    // Add the tool to the control, displaying an error if needed.
    if(!SendMessage(hwndTT,TTM_ADDTOOL,0,(LPARAM)&ti)){
        MessageBox(hwndOwner,"Couldn't create the ToolTip control.",
                   "Error",MB_OK);
        return NULL;
    }

    // Activate (display) the tracking ToolTip. Then, set a global
    // flag value to indicate that the ToolTip is active, so other
    // functions can check to see if it's visible.
    SendMessage(hwndTT,TTM_TRACKACTIVATE,(WPARAM)TRUE,(LPARAM)&ti);
    g_bIsVisible = TRUE;

    return(hwndTT);
}

Supporting Tracking ToolTips

The following example is a simple window process function that supports tracking ToolTips. It requests the current position of the mouse pointer by using the GetCursorPos function and then adds 15 pixels to the x- and y-coordinates, so the ToolTip appears slightly below and to the right of the pointer.

Note that the example relies on the value of a global variable, g_bIsVisible, to determine whether the application should send the TTM_TRACKPOSITION message. For the purpose of this example, g_bIsVisible is a Boolean variable that another function sets to TRUE upon sending the TTM_TRACKACTIVATE message to activate the ToolTip. This way, if the ToolTip is inactive, the additional overhead to calculate and send a message is not incurred.

LRESULT CALLBACK WndProc (HWND hwnd, UINT msg,
                               WPARAM wParam, LPARAM lParam)
{
  switch(msg){
    case WM_MOUSEMOVE:
      if(g_bIsVisible){

#define X_OFFSET 15
#define Y_OFFSET X_OFFSET

        SendMessage(g_hwndTT,
                    TTM_TRACKPOSITION,
                    0,
                    (LPARAM)MAKELPARAM(GET_X_LPARAM(lParam) + X_OFFSET,
                                       GET_Y_LPARAM(lParam) + Y_OFFSET));
      }
      break;

/*
 *
 *  Other standard window messages can be handled here.
 *
 */
  }
  return 0;
}

Multiline ToolTips

Multiline ToolTips allow text to be displayed on more than one line. They are supported by version 4.70 and later of the common controls. Your application creates a multiline ToolTip by responding to a TTN_GETDISPINFO notification message. To force the ToolTip control to use multiple lines, send a TTM_SETMAXTIPWIDTH message, specifying the width of the display rectangle. Text that exceeds this width will wrap to the next line rather than widening the display region. The rectangle height will be increased as needed to accommodate the additional lines. The ToolTip control will wrap the lines automatically, or you can use a carriage return/line feed combination, \r\n, to force line breaks at particular locations.

Note that the text buffer specified by the szText member of the NMTTDISPINFO structure can accommodate only 80 characters. If you need to use a longer string, point the lpszText member of NMTTDISPINFO to a buffer containing the desired text.

The following code fragment is an example of a simple TTN_GETDISPINFO notification handler. It creates a multiline ToolTip by setting the display rectangle to 300 pixels and setting the lpszText member of NMTTDISPINFO to point to a buffer with the desired text.

char szLongMessage[ ] =
"This is a long message for the ToolTip, which will automatically "
"be wrapped when it exceeds the maximum tip width.  "
"Alternatively, you can use a \r\n"
"carriage return/line feed combination\r\n"
"to force line breaks at specific\r\n"
"locations.";

switch (lpnmhdr->code) {
  case TTN_GETDISPINFO:
    lpttd = (LPNMTTDISPINFO)lpnmhdr;
    SendMessage(lpnmhdr->hwndFrom, TTM_SETMAXTIPWIDTH, 0, 300);
    lpttd->lpszText = szLongMessage;
    return 0;

    ...
 //Other notification handlers go here, as needed.
}

Balloon ToolTips

Balloon ToolTips are similar to standard ToolTips, but are displayed in a cartoon-style "balloon" with a stem pointing to the tool. Balloon ToolTips can be either single-line or multiline. They are created and handled in much the same way as standard ToolTips.

The default position of the stem and rectangle is shown below. If the tool is too close to the top of the screen, the ToolTip appears below and to the right of the tool's rectangle. If the tool is too close to the right side of the screen, similar principles apply, but the ToolTip appears to the left of the tool's rectangle.

You can change the default positioning by setting the TTF_CENTERTIP flag in the uFlags member of the ToolTip's TOOLINFO structure. In that case, the stem normally will point to the center of the lower edge of the tool's rectangle, and the text rectangle will be displayed directly below the tool. The stem will attach to the text rectangle at the center of the upper edge. If the tool is too close to the bottom of the screen, the text rectangle will be centered above the tool, and the stem will attach to the center of the lower edge.

If you want to specify where the stem points, set the TTF_TRACK flag in the uFlags member of the ToolTip's TOOLINFO structure. You then specify the coordinate by sending a TTM_TRACKPOSITION message, with the x- and y-coordinates in the lParam value. If TTF_CENTERTIP is also set, the stem still points to the position specified by the TTM_TRACKPOSITION message.

The following code fragment illustrates how to implement a centered balloon ToolTip.

hwndToolTips = CreateWindow(TOOLTIPS_CLASS,
                            NULL,
                            WS_POPUP | TTS_NOPREFIX | TTS_BALLOON,
                            0, 0,
                            0, 0,
                            NULL, NULL,
                            g_hinst,
                            NULL);
if (hwndTooltip)
{
// Do the standard ToolTip coding.
    TOOLINFO ti;

    ti.cbSize = sizeof(ti);
    ti.uFlags = TTF_TRANSPARENT | TTF_CENTERTIP;
    ti.hwnd = hwnd;
    ti.uId = 0;
    ti.hinst = NULL;
    ti.lpszText = LPSTR_TEXTCALLBACK;

    GetClientRect(hwnd, &ti.rect);
    SendMessage(hwndToolTips, TTM_ADDTOOL, 0, (LPARAM) &ti );
}

Balloon ToolTips for Status Bar Icons

A nonintrusive way to display an explanatory message for a status bar icon is to implement a balloon ToolTip with its stem pointing to the icon. The ToolTip will disappear when clicked, but you can also specify a time-out value. The ToolTip will look similar to the following illustration.

Balloon ToolTip for a status bar icon

For a detailed discussion of the status bar, see the Taskbar documentation.

The following code fragment illustrates how to add a balloon ToolTip to a status bar icon.

To display a balloon ToolTip, you need to set the NIF_INFO flag in the NOTIFYICONDATA structure, and use the szInfo and uTimeout members to specify the ToolTip text and time-out duration.

#define ARRAYSIZE(a) (sizeof(a)/sizeof(a[0]))

NOTIFYICONDATA IconData = {0};

IconData.cbSize = SIZEOF(IconData);
IconData.hWnd = hwndNI;
IconData.uFlags = NIF_INFO;

lstrcpyn(IconData.szInfo, TEXT("Your message text goes here."),
         ARRAYSIZE(IconData.szInfo));
IconData.uTimeout = 15000; // in milliseconds

Shell_NotifyIcon(NIM_MODIFY, &IconData);

In-Place ToolTips

In-place ToolTips are used to display text strings for objects that have been clipped, such as the folder names shown below in Microsoft® Windows® Explorer. In this illustration, My Network Places is displayed in an in-place ToolTip.

The difference between ordinary and in-place ToolTips is positioning. By default, when the mouse pointer hovers over a region that has a ToolTip associated with it, the ToolTip is displayed adjacent to the region. However, ToolTips are windows, and they can be positioned anywhere you choose by calling SetWindowPos. Creating an in-place ToolTip is a matter of positioning the ToolTip window so that it overlays the text string.

Positioning an In-Place ToolTip

You need to keep track of three rectangles when positioning an in-place ToolTip:

  • The rectangle that surrounds the complete label text.
  • The rectangle that surrounds the ToolTip text. The ToolTip text is identical to the complete label text, and normally is the same size and font. The two text rectangles will thus usually be the same size.
  • The ToolTip's window rectangle. This rectangle is somewhat larger than the ToolTip text rectangle that it encloses.

The three rectangles are shown schematically in the following illustration. The hidden portion of the label text is indicated by a gray background.

To create an in-place ToolTip, you must position the ToolTip text rectangle so that it overlays the label text rectangle. The procedure for aligning the two rectangles is relatively straightforward:

  1. Define the label text rectangle.
  2. Position the ToolTip window so that the ToolTip text rectangle overlays the label text rectangle

In practice, it is usually sufficient to align the upper-left corner of the two text rectangles. Attempting to resize the ToolTip text rectangle to exactly match the label text rectangle could cause problems with the ToolTip display.

The problem with this simple scheme is that you can't position the ToolTip text rectangle directly. Instead, you must position the ToolTip window rectangle just far enough above and to the left of the label text rectangle so that the corners of the two text rectangles coincide. In other words, you need to know the offset between the ToolTip window rectangle and its enclosed text rectangle. In general, there is no simple way to determine this offset.

Using TTM_ADJUSTRECT to Position a ToolTip

Common controls version 5.80 simplifies the use of in-place ToolTips by the addition of a new message, TTM_ADJUSTRECT. Send this message with the coordinates of the label text rectangle that you want the ToolTip to overlay, and it will return the coordinates of an appropriately positioned ToolTip window rectangle.

The following code fragment illustrates how to use TTM_ADJUSTRECT in a TTN_SHOW handler to display an in-place ToolTip. Your application indicates that the label text is truncated by setting the private fMyStringIsTruncated variable to TRUE. The handler calls an application-defined function, GetMyItemRect, to retrieve the label text rectangle. This rectangle is passed to the ToolTip control with TTM_ADJUSTRECT, which returns the corresponding window rectangle. SetWindowPosition is then called to position the ToolTip over the label.

case TTN_SHOW:

if (fMyStringIsTruncated) {
    RECT rc;

    GetMyItemRect(&rc);
    SendMessage(hwndToolTip, TTM_ADJUSTRECT, TRUE, (LPARAM)&rc);
    SetWindowPos(hwndToolTip,
                 NULL,
                 rc.left, rc.top,
                 0, 0,
                 SWP_NOSIZE|SWP_NOZORDER|SWP_NOACTIVATE);
}

This example does not change the size of the ToolTip, just its position. The two text rectangles will be aligned at their upper-left corners, but not necessarily with the same dimensions. In practice, the difference is usually small, and this approach is recommended for most purposes. While you can, in principle, use SetWindowPos to resize as well as reposition the ToolTip, doing so might have unpredictable consequences.


ToolTip Styles

ToolTip controls support a variety of control styles in addition to standard window styles. A ToolTip control always has the WS_POPUP and WS_EX_TOOLWINDOW window styles, regardless of whether you specify them when creating the control.

The following control styles are used with ToolTip controls:
TTS_ALWAYSTIP
Indicates that the ToolTip control appears when the cursor is on a tool, even if the ToolTip control's owner window is inactive. Without this style, the ToolTip appears only when the tool's owner window is active.
TTS_BALLOON
Version 5.80. Indicates that the ToolTip control has the appearance of a cartoon "balloon," with rounded corners and a stem pointing to the item.
TTS_NOANIMATE
Version 5.80. Disables sliding ToolTip animation on Microsoft® Windows® 98 and Microsoft® Windows 2000 systems. This style is ignored on earlier systems.
TTS_NOFADE
Version 5.80. Disables fading ToolTip animation on Windows 2000 systems. This style is ignored on earlier Windows NT systems, and on Windows 95 and Windows 98.
TTS_NOPREFIX
Prevents the system from stripping the ampersand (&) character from a string. Without this style, the system automatically strips ampersand characters. This allows an application to use the same string as both a menu item and as text in a ToolTip control.


TTM_ACTIVATE

Activates or deactivates a ToolTip control.

TTM_ACTIVATE
    wParam = (WPARAM) (BOOL) fActivate;
    lParam = 0;

Parameters

fActivate
Activation flag. If this parameter is TRUE, the ToolTip control is activated. If it is FALSE, the ToolTip control is deactivated.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_ADDTOOL

Registers a tool with a ToolTip control.

TTM_ADDTOOL
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure containing information that the ToolTip control needs to display text for the tool. The cbSize member of this structure must be filled in before sending this message.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_ADJUSTRECT

Calculates a ToolTip control's text display rectangle from its window rectangle, or the ToolTip window rectangle needed to display a specified text display rectangle.

TTM_ADJUSTRECT
    wParam = (WPARAM) (BOOL) fLarger;
    lParam = (LPARAM) (LPRECT) prc;

Parameters

fLarger
Value that specifies which operation to perform. If TRUE, prc is used to specify a text-display rectangle and it receives the corresponding window rectangle. If FALSE, prc is used to specify a window rectangle and it receives the corresponding text display rectangle.
prc
RECT structure to hold either a ToolTip window rectangle or a text display rectangle.

Return Values

Returns a non-zero value if the rectangle is successfully adjusted, and returns zero if an error occurs.

Example

This code fragment illustrates the use of the TTM_ADJUSTRECT message to position a ToolTip control to display the full text of a control's string in place of a truncated string. The application-defined GetMyItemRect function returns the text rectangle that will be needed to display the ToolTip text directly over the truncated string. The details of how this function is implemented will depend on the particular control. TTM_ADJUSTRECT is used to send this text rectangle to the ToolTip control. It returns an appropriately sized and positioned window rectangle that is then used to position the ToolTip window.

case TTN_SHOW:

if (MyStringIsTruncated) {
    RECT rc;

    GetMyItemRect(&rc);
    SendMessage(hwndToolTip, TTM_ADJUSTRECT, TRUE, (LPARAM)&rc);
    SetWindowPos(hwndToolTip,
                 NULL,
                 rc.left, rc.top,
                 0, 0,
                 SWP_NOSIZE|SWP_NOZORDER|SWP_NOACTIVATE);
}

Remarks

This message is particularly useful when you want to use a ToolTip control to display the full text of a string that is usually truncated. It is commonly used with listview and treeview controls. You typically send this message in response to a TTN_SHOW notification message so that you can position the ToolTip control properly.

The ToolTip's window rectangle is somewhat larger than the text display rectangle that bounds the ToolTip string. The window origin is also offset up and to the left from the origin of the text display rectangle. To position the text display rectangle, you must calculate the corresponding window rectangle and use that rectangle to position the ToolTip. TTM_ADJUSTRECT handles this calculation for you.

If you set fLarger to TRUE, TTM_ADJUSTRECT takes the size and position of the desired ToolTip text display rectangle, and passes back the size and position of the ToolTip window needed to display the text in the specified position. If you set fLarger to FALSE, you can specify a ToolTip window rectangle and TTM_ADJUSTRECT will return the size and position of its text rectangle.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in comctl32.h.


TTM_DELTOOL

Removes a tool from a ToolTip control.

TTM_DELTOOL
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure. The hwnd and uId members identify the tool to remove, and the cbSize member must specify the size of the structure. All other members are ignored.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_ENUMTOOLS

Retrieves the information that a ToolTip control maintains about the current tool—that is, the tool for which the ToolTip is currently displaying text.

TTM_ENUMTOOLS
    wParam = (WPARAM) (UINT) iTool;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

iTool
Zero-based index of the tool for which to retrieve information.
lpti
Address of a TOOLINFO structure that receives information about the tool. Before sending this message, the cbSize member must specify the size of the structure.

Return Values

Returns TRUE if any tools are enumerated, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_GETBUBBLESIZE

Returns the width and height of a ToolTip control.

TTM_GETBUBBLESIZE
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) pTtm;

Parameters

pTtm
Pointer to the ToolTip's TOOLINFO structure.

Return Values

Returns the width of the ToolTip in the low word and the height in the high word if successful. Otherwise, it returns FALSE.

Remarks

If the TTF_TRACK and TTF_ABSOLUTE flags are set in the uFlags member of the ToolTip's TOOLINFO structure, this message can be used to help position the ToolTip accurately.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in comctl32.h.


TTM_GETCURRENTTOOL

Retrieves the information for the current tool in a ToolTip control.

TTM_GETCURRENTTOOL
    wParam = 0;
    lParam = (LPARAM)(LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure that receives information about the current tool. If this value is NULL, the return value indicates the existence of the current tool without actually retrieving the tool information. If this value is not NULL, the cbSize member of the TOOLINFO structure must be filled in before sending this message.

Return Values

Returns nonzero if successful, or zero otherwise. If lpti is NULL, returns nonzero if a current tool exists, or zero otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_GETDELAYTIME

Retrieves the initial, pop-up, and reshow durations currently set for a ToolTip control.

TTM_GETDELAYTIME
    wParam = (DWORD) dwDuration;
    lParam = 0;

Parameters

dwDuration
Flag that specifies which duration value will be retrieved. This parameter can have one of the following values:
TTDT_AUTOPOP | Retrieve the length of time the ToolTip window remains visible if the pointer is stationary within a tool's bounding rectangle.
TTDT_INITIAL | Retrieve the length of time the pointer must remain stationary within a tool's bounding rectangle before the ToolTip window appears.
TTDT_RESHOW | Retrieve the length of time it takes for subsequent ToolTip windows to appear as the pointer moves from one tool to another.

Return Values

Returns an INT value with the specified duration in milliseconds.

See Also

TTM_SETDELAYTIME

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_GETMARGIN

Retrieves the top, left, bottom, and right margins set for a ToolTip window. A margin is the distance, in pixels, between the ToolTip window border and the text contained within the ToolTip window.

TTM_GETMARGIN
    wParam = 0;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

lprc
Address of a RECT structure that will receive the margin information.

The members of the RECT structure do not define a bounding rectangle. For the purpose of this message, the structure members are interpreted as follows:
top | Distance between top border and top of ToolTip text, in pixels.
left | Distance between left border and left end of ToolTip text, in pixels.
bottom | Distance between bottom border and bottom of ToolTip text, in pixels.
right | Distance between right border and right end of ToolTip text, in pixels.

Return Values

The return value for this message is not used.

Remarks

All four margins default to zero when you create the ToolTip control.

See Also

TTM_SETMARGIN

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_GETMAXTIPWIDTH

Retrieves the maximum width for a ToolTip window.

TTM_GETMAXTIPWIDTH
    wParam = 0;
    lParam = 0;

Return Values

Returns an INT value that represents the maximum ToolTip width, in pixels. If no maximum width was set previously, the message returns -1.

Remarks

The maximum ToolTip width value does not indicate a ToolTip window's actual width. Rather, if a ToolTip string exceeds the maximum width, the control breaks the text into multiple lines, using spaces to determine line breaks. If the text cannot be segmented into multiple lines, it will be displayed on a single line. The length of this line may exceed the maximum ToolTip width.

See Also

TTM_SETMAXTIPWIDTH

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_GETTEXT

Retrieves the information a ToolTip control maintains about a tool.

TTM_GETTEXT
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure.
The cbSize member of this structure must be filled in before sending this message. Set the hwnd and uId members to identify the tool for which to retrieve information. Set the lpszText member to point to a buffer that receives the text. There currently is no way to specify the size of the buffer or to determine the required buffer size.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_GETTIPBKCOLOR

Retrieves the background color in a ToolTip window.

TTM_GETTIPBKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that represents the background color.

See Also

TTM_SETTIPBKCOLOR

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_GETTIPTEXTCOLOR

Retrieves the text color in a ToolTip window.

TTM_GETTIPTEXTCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that represents the text color.

See Also

TTM_SETTIPTEXTCOLOR

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_GETTOOLCOUNT

Retrieves a count of the tools maintained by a ToolTip control.

TTM_GETTOOLCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns a count of tools.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_GETTOOLINFO

Retrieves the information that a ToolTip control maintains about a tool.

TTM_GETTOOLINFO
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure. When sending the message, the hwnd and uId members identify a tool, and the cbSize member must specify the size of the structure. If the ToolTip control includes the tool, the structure receives information about the tool.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_HITTEST

Tests a point to determine whether it is within the bounding rectangle of the specified tool and, if it is, retrieves information about the tool.

TTM_HITTEST
    wParam = 0;
    lParam = (LPARAM) (LPHITTESTINFO) lphti;

Parameters

lphti
Address of a TTHITTESTINFO structure. When sending the message, the hwnd member must specify the handle to a tool and the pt member must specify the coordinates of a point. If the return value is TRUE, the ti member (a TOOLINFO structure) receives information about the tool that occupies the point. The cbSize member of the ti structure must be filled in before sending this message.

Return Values

Returns TRUE if the tool occupies the specified point, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_NEWTOOLRECT

Sets a new bounding rectangle for a tool.

TTM_NEWTOOLRECT
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure. The hwnd and uId members identify a tool, and the rect member specifies the new bounding rectangle. The cbSize member of this structure must be filled in before sending this message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_POP

Removes a displayed ToolTip window from view.

TTM_POP
    wParam = 0;
    lParam = 0;

Return Values

The return value for this message is not used.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_RELAYEVENT

Passes a mouse message to a ToolTip control for processing.

TTM_RELAYEVENT
    wParam = 0;
    lParam = (LPARAM) (LPMSG) lpmsg;

Parameters

lpmsg
Address of an MSG structure that contains the message to relay.

Return Values

No return value.

Remarks

A ToolTip control processes only the following messages passed to it by the TTM_RELAYEVENT message:

  • WM_LBUTTONDOWN
  • WM_LBUTTONUP
  • WM_MBUTTONDOWN
  • WM_MBUTTONUP
  • WM_MOUSEMOVE
  • WM_RBUTTONDOWN
  • WM_RBUTTONUP

All other messages are ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_SETDELAYTIME

Sets the initial, pop-up, and reshow durations for a ToolTip control.

TTM_SETDELAYTIME
    wParam = (WPARAM)(DWORD) dwDuration;
    lParam = (LPARAM)(INT) MAKELONG(iTime,0);

Parameters

dwDuration
Flag that specifies the duration value to set. This parameter can be one of the following values:
TTDT_AUTOPOP | Set the length of time a ToolTip window remains visible if the pointer is stationary within a tool's bounding rectangle. To return the autopop delay time to its default value, set iTime to -1.
TTDT_INITIAL | Set the length of time a pointer must remain stationary within a tool's bounding rectangle before the ToolTip window appears. To return the initial delay time to its default value, set iTime to -1.
TTDT_RESHOW | Set the length of time it takes for subsequent ToolTip windows to appear as the pointer moves from one tool to another. To return the reshow delay time to its default value, set iTime to -1.
TTDT_AUTOMATIC | Set all three delay times to default proportions. The autopop time will be ten times the initial time and the reshow time will be one fifth the initial time. If this flag is set, use a positive value of iTime to specify the initial time, in milliseconds. Set iTime to a negative value to return all three delay times to their default values.
iTime
Delay time, in milliseconds.

Return Values

The return value for this message is not used.

Remarks

The default delay times are based on the double-click time. For the default double-click time of 500 ms, the initial, autopop, and reshow delay times are 500ms, 5000ms, and 100ms respectively. The following code fragment uses the GetDoubleClickTime function to determine the three delay times for any system.

initial = GetDoubleClickTime();
autopop = GetDoubleClickTime() * 10;
reshow = GetDoubleClickTime() / 5;

See Also

TTM_GETDELAYTIME

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_SETMARGIN

Sets the top, left, bottom, and right margins for a ToolTip window. A margin is the distance, in pixels, between the ToolTip window border and the text contained within the ToolTip window.

TTM_SETMARGIN
    wParam = 0;
    lParam = (LPARAM)(LPRECT) lprc;

Parameters

lprc
Address of a RECT structure that contains the margin information to be set.

The members of the RECT structure do not define a bounding rectangle. For the purpose of this message, the structure members are interpreted as follows:
top | Distance between top border and top of ToolTip text, in pixels.
left | Distance between left border and left end of ToolTip text, in pixels.
bottom | Distance between bottom border and bottom of ToolTip text, in pixels.
right | Distance between right border and right end of ToolTip text, in pixels.

Return Values

The return value for this message is not used.

See Also

TTM_GETMARGIN

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_SETMAXTIPWIDTH

Sets the maximum width for a ToolTip window.

TTM_SETMAXTIPWIDTH
    wParam = 0;
    lParam = (LPARAM)(INT) iWidth;

Parameters

iWidth
Maximum ToolTip window width to be set.

Return Values

Returns an INT value that represents the previous maximum ToolTip width.

Remarks

The maximum ToolTip width value does not indicate a ToolTip window's actual width. Rather, if a ToolTip string exceeds the maximum width, the control breaks the text into multiple lines, using spaces to determine line breaks. If the text cannot be segmented into multiple lines, it will be displayed on a single line. The length of this line may exceed the maximum ToolTip width.

See Also

TTM_GETMAXTIPWIDTH

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_SETTIPBKCOLOR

Sets the background color in a ToolTip window.

TTM_SETTIPBKCOLOR
    wParam = (WPARAM)(COLORREF) clr;
    lParam = 0;

Parameters

clr
New background color.

Return Values

The return value for this message is not used.

See Also

TTM_GETTIPBKCOLOR

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_SETTIPTEXTCOLOR

Sets the text color in a ToolTip window.

TTM_SETTIPTEXTCOLOR
    wParam = (WPARAM)(COLORREF) clr;
    lParam = 0;

Parameters

clr
New text color.

Return Values

The return value for this message is not used.

See Also

TTM_GETTIPTEXTCOLOR

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_SETTITLE

Adds a standard icon and title string to a ToolTip.

TTM_SETTITLE
wParam = icon;
lParam = (LPCTSTR) pszTitle;

Parameters

icon
Set wParam to one of the following values to specify the icon to be displayed.
0 | No icon.
1 | Info icon.
2 | Warning icon
3 | Error Icon
pszTitle
A pointer to the title string. You must assign a value to pszTitle.

Return Values

Returns TRUE if successful, FALSE if not

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in comctl32.h.


TTM_SETTOOLINFO

Sets the information that a ToolTip control maintains for a tool.

TTM_SETTOOLINFO
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure that specifies the information to set. The cbSize member of this structure must be filled in before sending this message.

Return Values

No return value.

Remarks

Some internal properties of a tool are established when the tool is created, and are not recomputed when a TTM_SETTOOLINFO message is sent. If you simply assign values to a TOOLINFO structure and pass it to the ToolTip control with a TTM_SETTOOLINFO message, these properties may be lost. Instead, your application should first request the tool's current TOOLINFO structure by sending the ToolTip control a TTM_GETTOOLINFO message. Then, modify the members of this structure as needed and pass it back to the ToolTip control with TTM_SETTOOLINFO.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_TRACKACTIVATE

Activates or deactivates a tracking ToolTip.

TTM_TRACKACTIVATE
    wParam = (WPARAM)(BOOL) bActivate;
    lParam = (LPARAM)(LPTOOLINFO) lpti;

Parameters

bActivate
Value specifying whether tracking is being activated or deactivated. This value can be one of the following:
TRUE | Activate tracking.
FALSE | Deactivate tracking.
lpti
Address of a TOOLINFO structure that identifies the tool to which this message applies. The hwnd and uId members identify the tool, and the cbSize member specifies the size of the structure. All other members are ignored.

Return Values

The return value for this message is not used.

See Also

Tracking ToolTips, TTM_TRACKPOSITION

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_TRACKPOSITION

Sets the position of a tracking ToolTip.

TTM_TRACKPOSITION
    wParam = 0;
    lParam = (LPARAM)(DWORD) MAKELONG(xPos, yPos);

Parameters

xPos and yPos
The x- and y-coordinates of the point at which the tracking ToolTip will be displayed, in screen coordinates.

Return Values

The return value for this message is not used.

Remarks

The ToolTip control chooses where to display the ToolTip window based on the coordinates you provide with this message. This causes the ToolTip window to appear beside the tool to which it corresponds. To have ToolTip windows displayed at specific coordinates, include the TTF_ABSOLUTE flag in the uFlags member of the TOOLINFO structure when adding the tool.

See Also

Tracking ToolTips, TTM_TRACKACTIVATE

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTM_UPDATE

Forces the current tool to be redrawn.

TTM_UPDATE
    wParam = 0;
    lParam = 0;

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TTM_UPDATETIPTEXT

Sets the ToolTip text for a tool.

TTM_UPDATETIPTEXT
    wParam = 0;
    lParam = (LPARAM) (LPTOOLINFO) lpti;

Parameters

lpti
Address of a TOOLINFO structure. The hinst and lpszText members must specify the instance handle and the address of the text. The hwnd and uId members identify the tool to update. The cbSize member of this structure must be filled in before sending this message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTM_WINDOWFROMPOINT

Allows a subclass procedure to cause a ToolTip to display text for a window other than the one beneath the mouse cursor.

TTM_WINDOWFROMPOINT
    wParam = 0;
    lParam = (POINT FAR *) lppt;

Parameters

lppt
Address of a POINT structure that defines the point to be checked.

Return Values

The return value is the handle to the window that contains the point, or NULL if no window exists at the specified point.

Remarks

This message is intended to be processed by an application that subclasses a ToolTip. It is not intended to be sent by an application. A ToolTip sends this message to itself before displaying the text for a window. By changing the coordinates of the point specified by lppt, the subclass procedure can cause the ToolTip to display text for a window other than the one beneath the mouse cursor.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (ToolTip)

Sent by a ToolTip control to notify its parent windows about drawing operations. This notification message is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMTTCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Pointer to an NMTTCUSTOMDRAW structure that contains information about the drawing operation.

Return Values

The value that your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:
CDRF_DODEFAULT
The control will draw itself. It will not send any additional NM_CUSTOMDRAW notification messages for this paint cycle.
CDRF_NOTIFYITEMDRAW
The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE
The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE
The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT
The control will notify the parent after painting an item.
CDRF_NOTIFYSUBITEMDRAW
Version 4.71. The control will notify the parent when a list-view subitem is being drawn.

When dwDrawStage equals CDDS_ITEMPREPAINT:
CDRF_NEWFONT
Your application specified a new font for the item. The control will use the new font. For more information about changing fonts, see Changing fonts and colors.
CDRF_SKIPDEFAULT
Your application drew the item manually. The control will not draw the item.

See Also

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTN_GETDISPINFO

Sent by a ToolTip control to retrieve information needed to display a ToolTip window. This notification supersedes the TTN_NEEDTEXT notification. This notification is sent in the form of a WM_NOTIFY message.

TTN_GETDISPINFO
    lpnmtdi = (LPNMTTDISPINFO)lParam;

#define TTN_NEEDTEXT TTN_GETDISPINFO

Parameters

lpnmtdi
Address of an NMTTDISPINFO structure that identifies the tool that needs text and receives the requested information.

Return Values

The return value for this notification is not used.

Remarks

Fill the structure's appropriate fields to return the requested information to the ToolTip control. If your message handler sets the uFlags field of the NMTTDISPINFO structure to TTF_DI_SETITEM, the ToolTip control stores the information and will not request it again.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TTN_POP

Notifies the owner window that a ToolTip is about to be hidden. This notification message is sent in the form of a WM_NOTIFY message.

TTN_POP
idTT = (int) wParam;
pnmh = (LPNMHDR) lParam;

Parameters

idTT
Identifier of the ToolTip control.
pnmh
Address of an NMHDR structure.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTN_SHOW

Notifies the owner window that a ToolTip control is about to be displayed. This notification message is sent in the form of a WM_NOTIFY message.

TTN_SHOW
    idTT = (int) wParam;
    pnmh = (LPNMHDR) lParam;

Parameters

idTT
Identifier of the ToolTip control.
pnmh
Pointer to an NMHDR structure.

Return Values

Version 4.70. To display the ToolTip in its default location, return zero. To customize the ToolTip position, reposition the ToolTip window with the SetWindowPos function and return TRUE.

Note: For versions earlier than 4.70, there is no return value.

Remarks

A ToolTip's window rectangle is somewhat larger than its text display rectangle, and its origin is offset up and to the left. If you need to accurately position the text display rectangle of a ToolTip, the TTM_ADJUSTRECT message converts a text display rectangle into the corresponding ToolTip window rectangle and vice versa.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMTTCUSTOMDRAW

Contains information specific to an NM_CUSTOMDRAW notification message sent by a ToolTip control.

typedef struct tagNMTTCUSTOMDRAW {
    NMCUSTOMDRAW nmcd;
    UINT         uDrawFlags;
} NMTTCUSTOMDRAW, FAR * LPNMTTCUSTOMDRAW;

Members

nmcd
NMCUSTOMDRAW structure that contains general custom draw information.
uDrawFlags
UINT value specifying how ToolTip text will be formatted when it is displayed. An application may change this field to alter the way text is drawn. This value is passed to the DrawText function internally. All values for the uFormat parameter of DrawText are valid.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMTTDISPINFO

Contains information used in handling the TTN_GETDISPINFO notification message. This structure supersedes the TOOLTIPTEXT structure.

typedef struct tagNMTTDISPINFO {
    NMHDR      hdr;
    LPTSTR     lpszText;
    char       szText[80];
    HINSTANCE  hinst;
    UINT       uFlags;
#if (_WIN32_IE >= 0x0300)
    LPARAM     lParam;
#endif
} NMTTDISPINFO, FAR *LPNMTTDISPINFO;

#define TOOLTIPTEXT NMTTDISPINFO

Members

hdr
NMHDR structure that contains additional information about the notification message.
lpszText
Address of a null-terminated string that will be displayed as the ToolTip text. If hinst specifies an instance handle, this member must be the identifier of a string resource.
szText
Buffer that receives the ToolTip text. An application can copy the text to this buffer instead of specifying a string address or string resource. For ToolTip text that exceeds 80 characters, see comments in the remarks section of this document.
hinst
Handle to the instance that contains a string resource to be used as the ToolTip text. If lpszText is the address of the ToolTip text string, this member must be NULL.
uFlags
Flags that indicates how to interpret the idFrom member of the included NMHDR structure.
TTF_IDISHWND
If this flag is set, idFrom is the tool's handle. Otherwise, it is the tool's identifier.
TTF_RTLREADING
Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Normally, ToolTip text is read in same direction as the the text in its parent window. To have a ToolTip read in the opposite direction from its parent window, add the TTF_RTLREADING flag to the uFlags member when processing the notification.
TTF_DI_SETITEM
Version 4.70. If you add this flag to uFlags while processing the notification, the ToolTip control will retain the supplied information and not request it again.
lParam
Version 4.70. Application-defined data associated with the tool.

Remarks

You need to point the lpszText array to your own private buffer when the text used in the ToolTip exceeds 80 characters in length. The system automatically strips the ampersand (&) accelerator characters from all strings passed to a ToolTip control, unless the control has the TTS_NOPREFIX style.

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TOOLINFO

The TOOLINFO structure contains information about a tool in a ToolTip control.

typedef struct tagTOOLINFO{
    UINT      cbSize;
    UINT      uFlags;
    HWND      hwnd;
    UINT_PTR  uId;
    RECT      rect;
    HINSTANCE hinst;
    LPTSTR    lpszText;
#if (_WIN32_IE >= 0x0300)
    LPARAM lParam;
#endif
} TOOLINFO, NEAR *PTOOLINFO, FAR *LPTOOLINFO;

Members

cbSize
Size of this structure, in bytes. This member must be specified.
uFlags
Flags that control the ToolTip display. This member can be a combination of the following values:
TTF_ABSOLUTE
Version 4.70. Positions the ToolTip window at the same coordinates provided by TTM_TRACKPOSITION. This flag must be used with the TTF_TRACK flag.
TTF_CENTERTIP
Centers the ToolTip window below the tool specified by the uId member.
TTF_IDISHWND
Indicates that the uId member is the window handle to the tool. If this flag is not set, uId is the tool's identifier.
TTF_RTLREADING
Indicates that the ToolTip text will be displayed in the opposite direction to the text in the parent window.
TTF_SUBCLASS
Indicates that the ToolTip control should subclass the tool's window to intercept messages, such as WM_MOUSEMOVE. If this flag is not set, you must use the TTM_RELAYEVENT message to forward messages to the ToolTip control. For a list of messages that a ToolTip control processes, see TTM_RELAYEVENT.
TTF_TRACK
Version 4.70. Positions the ToolTip window next to the tool to which it corresponds and moves the window according to coordinates supplied by the TTM_TRACKPOSITION messages. You must activate this type of tool using the TTM_TRACKACTIVATE message.
TTF_TRANSPARENT
Version 4.70. Causes the ToolTip control to forward mouse event messages to the parent window. This is limited to mouse events that occur within the bounds of the ToolTip window.
hwnd
Handle to the window that contains the tool. If lpszText includes the LPSTR_TEXTCALLBACK value, this member identifies the window that receives the TTN_GETDISPINFO notification messages.
uId
Application-defined identifier of the tool. If uFlags includes the TTF_IDISHWND flag, uId must specify the window handle to the tool.
rect
Tool's bounding rectangle coordinates. The coordinates are relative to the upper-left corner of the client area of the window identified by hwnd. If uFlags includes the TTF_IDISHWND flag, this member is ignored.
hinst
Handle to the instance that contains the string resource for the tool. If lpszText specifies the identifier of a string resource, this member is used.
lpszText
Pointer to the buffer that contains the text for the tool, or identifier of the string resource that contains the text. This member is sometimes used to return values. If you need to examine the returned value, lpszText must point to a valid buffer of sufficient size. Otherwise, it can be set to NULL. If lpszText is set to LPSTR_TEXTCALLBACK, the control sends the TTN_NEEDTEXT notification message to the owner window to retrieve the text.
lParam
Version 4.70. A 32-bit application-defined value that is associated with the tool.

Remarks

Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Normally, ToolTip text is displayed in the same direction as the the text in its parent window. If TTF_RTLREADING is set, ToolTip text will read in the opposite direction from the text in the parent window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TTHITTESTINFO

Contains information that a ToolTip control uses to determine whether a point is in the bounding rectangle of the specified tool. If the point is in the rectangle, the structure receives information about the tool.

typedef struct _TT_HITTESTINFO {
    HWND hwnd;
    POINT pt;
    TOOLINFO ti;
} TTHITTESTINFO, FAR * LPHITTESTINFO;

Members

hwnd
Handle to the tool or window with the specified tool.
pt
Client coordinates of the point to test.
ti
TOOLINFO structure. If the point specified by pt is in the tool specified by hwnd, this structure receives information about the tool. The cbSize member of this structure must be filled in before sending this message.

Remarks

This structure is used with the TTM_HITTEST message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Trackbar Controls

A trackbar is a window that contains a slider and optional tick marks. When the user moves the slider, using either the mouse or the direction keys, the trackbar sends notification messages to indicate the change.

  • About Trackbar Controls
  • Using Trackbar Controls
  • Trackbar Control Updates in Internet Explorer
  • Trackbar Control Reference

About Trackbar Controls

Trackbars are useful when you want the user to select a discrete value or a set of consecutive values in a range. For example, you might use a trackbar to allow the user to set the repeat rate of the keyboard by moving the slider to a given tick mark. The following illustration shows a typical trackbar.

A typical trackbar.

The slider in a trackbar moves in increments that you specify when you create it. The values in this range are referred to as logical units. For example, if you specify that the trackbar should have logical units that range from zero to five, the slider can occupy only six positions: a position at the left side of the trackbar and one position for each increment in the range. Typically, each of these positions is identified by a tick mark.

You create a trackbar by using the CreateWindowEx function, specifying the TRACKBAR_CLASS window class. After you have created a trackbar, you can use trackbar messages to set and retrieve many of its properties. Changes that you can make include setting the minimum and maximum positions for the slider, drawing tick marks, setting a selection range, and repositioning the slider.

Trackbar Messages

The logical units of a trackbar are the set of contiguous values that the trackbar can represent. They are usually defined by specifying the range of possible values with a TBM_SETRANGE message when the trackbar is first created. Applications can dynamically alter the range by using the TBM_SETRANGEMAX and TBM_SETRANGEMIN messages. An application that allows the range to be changed dynamically retrieves the final range settings when the user has finished working with the trackbar. To retrieve these settings, use the TBM_GETRANGEMAX and TBM_GETRANGEMIN messages.

An application can send messages to the trackbar to retrieve information about the window and to change its characteristics. To retrieve the position of the slider (that is, the value the user has chosen), use the TBM_GETPOS message. To set the position of the slider, use the TBM_SETPOS message.

A trackbar automatically displays tick marks at its beginning and end, unless you specify the TBS_NOTICKS style. You can use the TBS_AUTOTICKS style to automatically display additional tick marks at regular intervals along the trackbar. By default, a TBS_AUTOTICKS trackbar displays a tick mark at each increment of the trackbar's range. To specify a different interval for the automatic tick marks, send the TBM_SETTICFREQ message to the trackbar. For example, you could use this message to display only 10 tick marks in a range of 1 through 100.

To set the position of a single tick mark, send the TBM_SETTIC message. A trackbar maintains an array of DWORD values that stores the position of each tick mark. The array does not include the first and last tick marks that the trackbar creates automatically. You can specify an index in this array when you send the TBM_GETTIC message to retrieve the position of the corresponding tick mark. Alternatively, you can send the TBM_GETPTICS message to retrieve a pointer to the array. The number of elements in the array is equal to two less than the tick count returned by the TBM_GETNUMTICS message. This is because the count returned by TBM_GETNUMTICS includes the first and last tick marks that are not included in the array. To retrieve the physical position of a tick mark, in client coordinates of the trackbar's window, send the TBM_GETTICPOS message. The TBM_CLEARTICS message removes all but the first and last of a trackbar's tick marks.

A trackbar's line size determines how far the slider moves in response to keyboard input from the arrow keys, such as the RIGHT ARROW or DOWN ARROW key. To retrieve or set the line size, send the TBM_GETLINESIZE and TBM_SETLINESIZE messages. The trackbar also sends the TB_LINEUP and TB_LINEDOWN notification messages to its parent window when the user presses the arrow keys.

A trackbar's page size determines how far the slider moves in response to keyboard input, such as the PAGE UP or PAGE DOWN key, or mouse input, such as clicks in the trackbar channel. To retrieve or set the page size, send the TBM_GETPAGESIZE and TBM_SETPAGESIZE messages. The trackbar also sends the TB_PAGEUP and TB_PAGEDOWN notification messages to its parent window when it receives keyboard or mouse input that scrolls the page. For more information, see Trackbar Notification Messages.

An application can send messages to retrieve the dimensions of a trackbar. The TBM_GETTHUMBRECT message retrieves the bounding rectangle for the slider. The TBM_GETTHUMBLENGTH message retrieves the length of the slider. The TBM_GETCHANNELRECT message retrieves the bounding rectangle for the trackbar's channel, which is the area over which the slider moves. It contains the highlight when a range is selected. If a trackbar has the TBS_FIXEDLENGTH style, you can send the TBM_SETTHUMBLENGTH message to change the length of the slider.

If you create a trackbar with the TBS_ENABLESELRANGE style, you can specify a "selection range," which restricts the user to a specified portion of the total range. The logical units do not change, but only a subset of them are available for use. The trackbar highlights the available range and displays triangular tick marks at the start and end. Typically, an application handles the trackbar's notification messages and sets the trackbar's selection range according to the user's input.

You retrieve or set the selection range by sending messages to the trackbar. Use the TBM_SETSEL message to set the starting and ending positions of a selection. To set just the starting position or just the ending position of a selection, send a TBM_SETSELSTART or TBM_SETSELEND message. To retrieve the starting or ending positions of a selection range, send a TBM_GETSELSTART or TBM_GETSELEND message. To clear a selection range and restore the trackbar to its original range, send the TBM_CLEARSEL message.

Trackbar Notification Messages

A trackbar notifies its parent window of user actions by sending the parent a WM_HSCROLL or WM_VSCROLL message. A trackbar with the TBS_HORZ style sends WM_HSCROLL messages. A trackbar with the TBS_VERT style sends WM_VSCROLL messages. The low-order word of the wParam parameter of WM_HSCROLL or WM_VSCROLL contains the notification code. For the TB_THUMBPOSITION and TB_THUMBTRACK notifications, the high-order word of the wParam parameter specifies the position of the slider. For all other notifications, the high-order word is zero; send the TBM_GETPOS message to determine the slider position. The lParam parameter is the handle to the trackbar.

The system sends the TB_BOTTOM, TB_LINEDOWN, TB_LINEUP, and TB_TOP notification messages only when the user interacts with a trackbar by using the keyboard. The TB_THUMBPOSITION and TB_THUMBTRACK notification messages are only sent when the user is using the mouse. The TB_ENDTRACK, TB_PAGEDOWN, and TB_PAGEUP notification messages are sent in both cases. The following table lists the trackbar notification messages and the events (virtual key codes or mouse events) that cause the notifications to be sent.

Notification message | Reason sent
TB_BOTTOM | VK_END
TB_ENDTRACK | WM_KEYUP (the user released a key that sent a relevant virtual key code)
TB_LINEDOWN | VK_RIGHT or VK_DOWN
TB_LINEUP | VK_LEFT or VK_UP
TB_PAGEDOWN | VK_NEXT (the user clicked the channel below or to the right of the slider)
TB_PAGEUP | VK_PRIOR (the user clicked the channel above or to the left of the slider)
TB_THUMBPOSITION | WM_LBUTTONUP following a TB_THUMBTRACK notification message
TB_THUMBTRACK | Slider movement (the user dragged the slider)
TB_TOP | VK_HOME

Default Trackbar Message Processing

This section describes the window message processing performed by a trackbar.

Message | Processing performed
WM_CAPTURECHANGED | Kills the timer if one was set during WM_LBUTTONDOWN processing and sends the TB_THUMBPOSITION notification message, if necessary. It always sends the TB_ENDTRACK notification message.
WM_CREATE | Performs additional initialization, such as setting the line size, page size, and tick mark frequency to default values.
WM_DESTROY | Frees resources.
WM_ENABLE | Repaints the trackbar window.
WM_ERASEBKGND | Erases the window background, using the current background color for the trackbar.
WM_GETDLGCODE | Returns the DLGC_WANTARROWS value.
WM_KEYDOWN | Processes the direction keys and sends the TB_TOP, TB_BOTTOM, TB_PAGEUP, TB_PAGEDOWN, TB_LINEUP, and TB_LINEDOWN notification messages, as appropriate.
WM_KEYUP | Sends the TB_ENDTRACK notification message if the key was one of the direction keys.
WM_KILLFOCUS | Repaints the trackbar window.
WM_LBUTTONDOWN | Sets the focus and the mouse capture to the trackbar. When necessary, it sets a timer that determines how quickly the slider moves toward the mouse cursor when the user holds down the mouse button in the window.
WM_LBUTTONUP | Releases the mouse capture and kills the timer if one was set during WM_LBUTTONDOWN processing. It sends the TB_THUMBPOSITION notification message, if necessary. It always sends the TB_ENDTRACK notification message.
WM_MOUSEMOVE | Moves the slider and sends the TB_THUMBTRACK notification message when tracking the mouse (see WM_TIMER).
WM_PAINT | Paints the trackbar. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETFOCUS | Repaints the trackbar window.
WM_SIZE | Sets the dimensions of the trackbar, removing the slider if there is not enough room to display it.
WM_TIMER | Retrieves the mouse position and updates the position of the slider. (It is received only when the user is dragging the slider.)
WM_WININICHANGE | Initializes slider dimensions.

Using Trackbar Controls

This section provides examples that demonstrate how to create a trackbar and process trackbar notification messages.

Creating a Trackbar

The following example shows how to create a trackbar with the TBS_AUTOTICKS and TBS_ENABLESELRANGE styles. When the trackbar is created, both its range and its selection range are initialized. The page size is also set at this time.

// CreateTrackbar - creates and initializes a trackbar.
//
// Global variable
//     g_hinst - instance handle
HWND WINAPI CreateTrackbar(
    HWND hwndDlg,  // handle of dialog box (parent window)
    UINT iMin,     // minimum value in trackbar range
    UINT iMax,     // maximum value in trackbar range
    UINT iSelMin,  // minimum value in trackbar selection
    UINT iSelMax)  // maximum value in trackbar selection
{

    InitCommonControls(); // loads common control's DLL

    hwndTrack = CreateWindowEx(
        0,                             // no extended styles
        TRACKBAR_CLASS,                // class name
        "Trackbar Control",            // title (caption)
        WS_CHILD | WS_VISIBLE |
        TBS_AUTOTICKS | TBS_ENABLESELRANGE,  // style
        10, 10,                        // position
        200, 30,                       // size
        hwndDlg,                       // parent window
        ID_TRACKBAR,             // control identifier
        g_hinst,                       // instance
        NULL                           // no WM_CREATE parameter
        );

    SendMessage(hwndTrack, TBM_SETRANGE,
        (WPARAM) TRUE,                   // redraw flag
        (LPARAM) MAKELONG(iMin, iMax));  // min. & max. positions
    SendMessage(hwndTrack, TBM_SETPAGESIZE,
        0, (LPARAM) 4);                  // new page size

    SendMessage(hwndTrack, TBM_SETSEL,
        (WPARAM) FALSE,                  // redraw flag
        (LPARAM) MAKELONG(iSelMin, iSelMax);
    SendMessage(hwndTrack, TBM_SETPOS,
        (WPARAM) TRUE,                   // redraw flag
        (LPARAM) iSelMin);

    SetFocus(hwndTrack);

    return hwndTrack;
}

Processing Trackbar Notification Messages

The following example is a function that is called whenever a WM_HSCROLL message is received by the dialog box containing the trackbar. The trackbar has the TBS_ENABLESELRANGE style. The position of the slider is compared against the selection range, and the slider is moved to the starting or ending position of the selection range, when necessary.

A dialog containing a trackbar with the TBS_VERT style could use this function when it receives a WM_VSCROLL message.

// TBNotifications - handles trackbar notifications received
// in the wParam parameter of WM_HSCROLL. This function simply
// ensures that the slider remains within the selection range.

VOID WINAPI TBNotifications(
    WPARAM wParam,  // wParam of WM_HSCROLL message
    HWND hwndTrack, // handle of trackbar window
    UINT iSelMin,   // minimum value of trackbar selection
    UINT iSelMax)   // maximum value of trackbar selection
    {
    DWORD dwPos;    // current position of slider

    switch (LOWORD(wParam)) {
        case TB_ENDTRACK:
            dwPos = SendMessage(hwndTrack, TBM_GETPOS, 0, 0);
            if (dwPos > iSelMax)
                SendMessage(hwndTrack, TBM_SETPOS,
                    (WPARAM) TRUE,       // redraw flag
                    (LPARAM) iSelMax);
            else if (dwPos < iSelMin)
                SendMessage(hwndTrack, TBM_SETPOS,
                    (WPARAM) TRUE,       // redraw flag
                    (LPARAM) iSelMin);
            break;

        default:
            break;

        }
}

Trackbar Control Updates in Internet Explorer

Trackbar controls in Microsoft® Internet Explorer support the following new features.

Buddy Windows
Trackbar controls now provide support for up to two buddy windows. Trackbar buddy windows are automatically positioned by the control to appear centered at the ends of the trackbar control. To assign an existing window to a trackbar, use the TBM_SETBUDDY message. To retrieve the handle to a given buddy window, send the TBM_GETBUDDY message.
ToolTips
Trackbar controls now support ToolTips. A trackbar creates a default ToolTip control when created with the TBS_TOOLTIPS style. However, you can assign a new ToolTip control to a trackbar by sending the TBM_SETTOOLTIPS message. To retrieve the handle to an assigned ToolTip control, use the TBM_GETTOOLTIPS message.


Trackbar Control Styles

This section contains information about the styles used with trackbar controls.

TBS_AUTOTICKS
The trackbar control has a tick mark for each increment in its range of values.
TBS_BOTH
The trackbar control displays tick marks on both sides of the control. This will be both top and bottom when used with TBS_HORZ or both left and right if used with TBS_VERT.
TBS_BOTTOM
The trackbar control displays tick marks below the control. This style is valid only with TBS_HORZ.
TBS_ENABLESELRANGE
The trackbar control displays a selection range only. The tick marks at the starting and ending positions of a selection range are displayed as triangles (instead of vertical dashes), and the selection range is highlighted.
TBS_FIXEDLENGTH
The trackbar control allows the size of the slider to be changed with the TBM_SETTHUMBLENGTH message.
TBS_HORZ
The trackbar control is oriented horizontally. This is the default orientation.
TBS_LEFT
The trackbar control displays tick marks to the left of the control. This style is valid only with TBS_VERT.
TBS_NOTHUMB
The trackbar control does not display a slider.
TBS_NOTICKS
The trackbar control does not display any tick marks.
TBS_REVERSED
Version 5.80. This style bit is used for "reversed" trackbars, where a smaller number indicates "higher" and a larger number indicates "lower." It has no effect on the control; it is simply a label that can be checked to determine whether a trackbar is normal or reversed.
TBS_RIGHT
The trackbar control displays tick marks to the right of the control. This style is valid only with TBS_VERT.
TBS_TOOLTIPS
Version 4.70. The trackbar control supports ToolTips. When a trackbar control is created using this style, it automatically creates a default ToolTip control that displays the slider's current position. You can change where the ToolTips are displayed by using the TBM_SETTIPSIDE message.
TBS_TOP
The trackbar control displays tick marks above the control. This style is valid only with TBS_HORZ.
TBS_VERT
The trackbar control is oriented vertically.


Custom Draw Values

Trackbar controls use the following values to identify a control's parts. One of these values is specified in the dwItemSpec member of the NMCUSTOMDRAW structure.
TBCD_CHANNEL | Identifies the channel that the trackbar control's thumb marker slides along. This is the part of the control that the user moves.
TBCD_THUMB | Identifies the trackbar control's thumb marker.
TBCD_TICS | Identifies the tick marks that are displayed along the trackbar control's edge.


TBM_CLEARSEL

Clears the current selection range in a trackbar.

TBM_CLEARSEL
    wParam = (WPARAM) (BOOL) fRedraw;
    lParam = 0;

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the selection is cleared.

Return Values

No return value.

Remarks

A trackbar can have a selection range only if you specified the TBS_ENABLESELRANGE style when you created it.

See Also

TBM_SETSEL, TBM_SETSELEND, TBM_SETSELSTART

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_CLEARTICS

Removes the current tick marks from a trackbar. This message does not remove the first and last tick marks, which are created automatically by the trackbar.

TBM_CLEARTICS
    wParam = (WPARAM) (BOOL) fRedraw;
    lParam = 0;

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the tick marks are cleared. If this parameter is FALSE, the message clears the tick marks but does not redraw the trackbar.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETBUDDY

Retrieves the handle to a trackbar control buddy window at a given location. The specified location is relative to the control's orientation (horizontal or vertical).

TBM_GETBUDDY
    wParam = (WPARAM)(BOOL) fLocation;
    lParam = 0;

Parameters

fLocation
Value indicating which buddy window handle will be retrieved, by relative location. This value can be one of the following:
TRUE | Retrieves the handle to the buddy to the left of the trackbar. If the trackbar control uses the TBS_VERT style, the message will retrieve the buddy above the trackbar.
FALSE | Retrieves the handle to the buddy to the right of the trackbar. If the trackbar control uses the TBS_VERT style, the message will retrieve the buddy below the trackbar.

Return Values

Returns the handle to the buddy window at the location specified by fLocation, or NULL if no buddy window exists at that location.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBM_GETCHANNELRECT

Retrieves the size and position of the bounding rectangle for a trackbar's channel. (The channel is the area over which the slider moves. It contains the highlight when a range is selected.)

TBM_GETCHANNELRECT
    wParam = 0;
    lParam = (LPARAM) (LPRECT) lprc;

Parameters

lprc
Address of a RECT structure. The message fills this structure with the channel's bounding rectangle, in client coordinates of the trackbar's window.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETLINESIZE

Retrieves the number of logical positions the trackbar's slider moves in response to keyboard input from the arrow keys, such as the RIGHT ARROW or DOWN ARROW keys. The logical positions are the integer increments in the trackbar's range of minimum to maximum slider positions.

TBM_GETLINESIZE
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the line size for the trackbar.

Remarks

The default setting for the line size is 1.

The trackbar also sends the TB_LINEUP and TB_LINEDOWN notification messages to its parent window when the user presses the arrow keys.

See Also

TBM_SETLINESIZE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETNUMTICS

Retrieves the number of tick marks in a trackbar.

TBM_GETNUMTICS
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of tick marks.

Remarks

The TBM_GETNUMTICS message counts all of the tick marks, including the first and last tick marks created by the trackbar.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETPAGESIZE

Retrieves the number of logical positions the trackbar's slider moves in response to keyboard input, such as the PAGE UP or PAGE DOWN keys, or mouse input, such as clicks in the trackbar's channel. The logical positions are the integer increments in the trackbar's range of minimum to maximum slider positions.

TBM_GETPAGESIZE
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the page size for the trackbar.

Remarks

The trackbar also sends the TB_PAGEUP and TB_PAGEDOWN notification messages to its parent window when it receives keyboard or mouse input that scrolls the page.

See Also

TBM_SETPAGESIZE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETPOS

Retrieves the current logical position of the slider in a trackbar. The logical positions are the integer values in the trackbar's range of minimum to maximum slider positions.

TBM_GETPOS
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the current logical position of the trackbar's slider.

See Also

TBM_SETPOS

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETPTICS

Retrieves the address of an array that contains the positions of the tick marks for a trackbar.

TBM_GETPTICS
    wParam = 0;
    lParam = 0;

Return Values

Returns the address of an array of DWORD values. The elements of the array specify the logical positions of the trackbar's tick marks, not including the first and last tick marks created by the trackbar. The logical positions can be any of the integer values in the trackbar's range of minimum to maximum slider positions.

Remarks

The number of elements in the array is two less than the tick count returned by the TBM_GETNUMTICS message. Note that the values in the array may include duplicate positions and may not be in sequential order. The returned pointer is valid until you change the trackbar's tick marks.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETRANGEMAX

Retrieves the maximum position for the slider in a trackbar.

TBM_GETRANGEMAX
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the maximum position in the trackbar's range of minimum to maximum slider positions.

See Also

TBM_GETRANGEMIN, TBM_SETRANGE, TBM_SETRANGEMAX

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETRANGEMIN

Retrieves the minimum position for the slider in a trackbar.

TBM_GETRANGEMIN
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the minimum position in the trackbar's range of minimum to maximum slider positions.

See Also

TBM_GETRANGEMAX, TBM_SETRANGE, TBM_SETRANGEMAX

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETSELEND

Retrieves the ending position of the current selection range in a trackbar.

TBM_GETSELEND
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the ending position of the current selection range.

Remarks

A trackbar can have a selection range only if you specified the TBS_ENABLESELRANGE style when you created it.

See Also

TBM_GETSELSTART, TBM_SETSEL, TBM_SETSELEND, TBM_SETSELSTART

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETSELSTART

Retrieves the starting position of the current selection range in a trackbar.

TBM_GETSELSTART
    wParam = 0;
    lParam = 0;

Return Values

Returns a 32-bit value that specifies the starting position of the current selection range.

Remarks

A trackbar can have a selection range only if you specified the TBS_ENABLESELRANGE style when you created it.

See Also

TBM_GETSELEND, TBM_SETSEL, TBM_SETSELEND, TBM_SETSELSTART

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETTHUMBLENGTH

Retrieves the length of the slider in a trackbar.

TBM_GETTHUMBLENGTH
    wParam = 0;
    lParam = 0;

Return Values

Returns the length, in pixels, of the slider.

See Also

TBM_GETTHUMBRECT, TBM_SETTHUMBLENGTH

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETTHUMBRECT

Retrieves the size and position of the bounding rectangle for the slider in a trackbar.

TBM_GETTHUMBRECT
    wParam = 0;
    lParam = (LPARAM) (LPRECT) lprc;

Parameters

lprc
Address of a RECT structure. The message fills this structure with the bounding rectangle of the trackbar's slider, in client coordinates of the trackbar's window.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETTIC

Retrieves the logical position of a tick mark in a trackbar. The logical position can be any of the integer values in the trackbar's range of minimum to maximum slider positions.

TBM_GETTIC
    wParam = (WPARAM) (WORD) iTic;
    lParam = 0;

Parameters

iTic
Zero-based index identifying a tick mark. Valid indexes are in the range from zero to two less than the tick count returned by the TBM_GETNUMTICS message.

Return Values

Returns the logical position of the specified tick mark, or -1 if iTic does not specify a valid index.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETTICPOS

Retrieves the current physical position of a tick mark in a trackbar.

TBM_GETTICPOS
    wParam = (WPARAM) (WORD) iTic;
    lParam = 0;

Parameters

iTic
Zero-based index identifying a tick mark. Valid indexes are in the range from zero to two less than the tick count returned by the TBM_GETNUMTICS message.

Return Values

Returns the distance, in client coordinates, from the left or top of the trackbar's client area to the specified tick mark. The return value is the x-coordinate of the tick mark for a horizontal trackbar or the y-coordinate for a vertical trackbar. If iTic is not a valid index, the return value is -1.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_GETTOOLTIPS

Retrieves the handle to the ToolTip control assigned to the trackbar, if any.

TBM_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the ToolTip control assigned to the trackbar, or NULL if ToolTips are not in use. If the trackbar control does not use the TBS_TOOLTIPS style, the return value is NULL.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control.

TBM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

TBM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETBUDDY

Assigns a window as the buddy window for a trackbar control. Trackbar buddy windows are automatically displayed in a location relative to the control's orientation (horizontal or vertical).

TBM_SETBUDDY
    wParam = (WPARAM)(BOOL) fLocation;
    lParam = (LPARAM)(HWND) hwndBuddy;

Parameters

fLocation
Value specifying the location at which to display the buddy window. This value can be one of the following:
TRUE | The buddy will appear to the left of the trackbar if the trackbar control uses the TBS_HORZ style. If the trackbar uses the TBS_VERT style, the buddy appears above the trackbar control.
FALSE | The buddy will appear to the right of the trackbar if the trackbar control uses the TBS_HORZ style. If the trackbar uses the TBS_VERT style, the buddy appears below the trackbar control.
hwndBuddy
Handle to the window that will be set as the trackbar control's buddy.

Return Values

Returns the handle to the window that was previously assigned to the control at that location.

Remarks

Note Trackbar controls support up to two buddy windows. This can be useful when you must display text or images at each end of the control.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBM_SETLINESIZE

Sets the number of logical positions the trackbar's slider moves in response to keyboard input from the arrow keys, such as the RIGHT ARROW or DOWN ARROW keys. The logical positions are the integer increments in the trackbar's range of minimum to maximum slider positions.

TBM_SETLINESIZE
    wParam = 0;
    lParam = (LONG) lLineSize;

Parameters

lLineSize
New line size.

Return Values

Returns a 32-bit value that specifies the previous line size.

Remarks

The default setting for the line size is 1.

The trackbar also sends the TB_LINEUP and TB_LINEDOWN notification messages to its parent window when the user presses the arrow keys.

See Also

TBM_GETLINESIZE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETPAGESIZE

Sets the number of logical positions the trackbar's slider moves in response to keyboard input, such as the PAGE UP or PAGE DOWN keys, or mouse input, such as clicks in the trackbar's channel. The logical positions are the integer increments in the trackbar's range of minimum to maximum slider positions.

TBM_SETPAGESIZE
    wParam = 0;
    lParam = (LONG) lPageSize;

Parameters

lPageSize
New page size.

Return Values

Returns a 32-bit value that specifies the previous page size.

Remarks

The trackbar also sends the TB_PAGEUP and TB_PAGEDOWN notification messages to its parent window when it receives keyboard or mouse input that scrolls the page.

See Also

TBM_GETPAGESIZE

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETPOS

Sets the current logical position of the slider in a trackbar.

TBM_SETPOS
    wParam = (WPARAM) (BOOL) fPosition;
    lParam = (LPARAM) (LONG) lPosition;

Parameters

fPosition
Redraw flag. If this parameter is TRUE, the message redraws the control with the slider at the position given by lPosition. If this parameter is FALSE, the message does not redraw the slider at the new position. Note that the message sets the value of the slider position (as returned by the TBM_GETPOS message) regardless of the fPosition parameter.
lPosition
New logical position of the slider. Valid logical positions are the integer values in the trackbar's range of minimum to maximum slider positions. If this value is outside the control's maximum and minimum range, the position is set to the maximum or minimum value.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETRANGE

Sets the range of minimum and maximum logical positions for the slider in a trackbar.

TBM_SETRANGE
    wParam = (WPARAM) (BOOL) fRedraw;
    lParam = (LPARAM) MAKELONG(lMinimum, lMaximum);

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the range is set. If this parameter is FALSE, the message sets the range but does not redraw the trackbar.
lMinimum
Minimum position for the slider.
lMaximum
Maximum position for the slider.

Return Values

No return value.

Remarks

If the current slider position is outside the new range, the TBM_SETRANGE message sets the slider position to the new maximum or minimum value.

See Also

TBM_SETRANGEMAX, TBM_SETRANGEMIN

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETRANGEMAX

Sets the maximum logical position for the slider in a trackbar.

TBM_SETRANGEMAX
    wParam = (WPARAM) fRedraw;
    lParam = (LPARAM) lMaximum;

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the trackbar is redrawn after the range is set. If this parameter is FALSE, the message sets the range but does not redraw the trackbar.
lMaximum
Maximum position for the slider.

Return Values

No return value.

Remarks

If the current slider position is greater than the new maximum, the TBM_SETRANGEMAX message sets the slider position to the new maximum value.

See Also

TBM_SETRANGE, TBM_SETRANGEMIN

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETRANGEMIN

Sets the minimum logical position for the slider in a trackbar.

TBM_SETRANGEMIN
    wParam = (WPARAM) fRedraw;
    lParam = (LPARAM) lMinimum;

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the message redraws the trackbar after the range is set. If this parameter is FALSE, the message sets the range but does not redraw the trackbar.
lMinimum
Minimum position for the slider.

Return Values

No return value.

Remarks

If the current slider position is less than the new minimum, the TBM_SETRANGEMIN message sets the slider position to the new minimum value.

See Also

TBM_SETRANGE, TBM_SETRANGEMAX

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETSEL

Sets the starting and ending positions for the available selection range in a trackbar.

TBM_SETSEL
    wParam = (WPARAM) (BOOL) fRedraw;
    lParam = (LPARAM) MAKELONG(lMinimum, lMaximum);

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the message redraws the trackbar after the selection range is set. If this parameter is FALSE, the message sets the selection range but does not redraw the trackbar.
lMinimum
Starting logical position for the selection range.
lMaximum
Ending logical position for the selection range.

Return Values

No return value.

Remarks

This message is ignored if the trackbar does not have the TBS_ENABLESELRANGE style.

TBM_SETSEL allow you to restrict the pointer to only a portion of the range available to the progress bar.

See also TBM_GETSELEND, TBM_GETSELSTART, TBM_SETSELEND, TBM_SETSELSTART

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETSELEND

Sets the ending logical position of the current selection range in a trackbar. This message is ignored if the trackbar does not have the TBS_ENABLESELRANGE style.

TBM_SETSELEND
    wParam = (WPARAM) (BOOL) fRedraw;
    lParam = (LPARAM) (LONG) lEnd;

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the message redraws the trackbar after the selection range is set. If this parameter is FALSE, the message sets the selection range but does not redraw the trackbar.
lEnd
Ending logical position of the selection range.

Return Values

No return value.

See Also

TBM_GETSELEND, TBM_GETSELSTART, TBM_SETSEL, TBM_SETSELSTART

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETSELSTART

Sets the starting logical position of the current selection range in a trackbar. This message is ignored if the trackbar does not have the TBS_ENABLESELRANGE style.

TBM_SETSELSTART
    wParam = (WPARAM) (BOOL) fRedraw;
    lParam = (LPARAM) (LONG) lStart;

Parameters

fRedraw
Redraw flag. If this parameter is TRUE, the message redraws the trackbar after the selection range is set. If this parameter is FALSE, the message sets the selection range but does not redraw the trackbar.
lStart
Starting position of the selection range.

Return Values

No return value.

See Also

TBM_GETSELEND, TBM_GETSELSTART, TBM_SETSEL, TBM_SETSELEND

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETTHUMBLENGTH

Sets the length of the slider in a trackbar. This message is ignored if the trackbar does not have the TBS_FIXEDLENGTH style.

TBM_SETTHUMBLENGTH
    wParam = (WPARAM) (UINT) iLength;
    lParam = 0;

Parameters

iLength
Length, in pixels, of the slider.

Return Values

No return value.

See Also

TBM_GETTHUMBLENGTH

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETTIC

Sets a tick mark in a trackbar at the specified logical position.

TBM_SETTIC
    wParam = 0;
    lParam = (LPARAM) (LONG) lPosition;

Parameters

lPosition
Position of the tick mark. This parameter can be any of the integer values in the trackbar's range of minimum to maximum slider positions.

Return Values

Returns TRUE if the tick mark is set, or FALSE otherwise.

Remarks

A trackbar creates its own first and last tick marks. Do not use this message to set the first and last tick marks.

See Also

TBM_GETPTICS, TBM_GETTIC

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETTICFREQ

Sets the interval frequency for tick marks in a trackbar. For example, if the frequency is set to two, a tick mark is displayed for every other increment in the trackbar's range. The default setting for the frequency is one; that is, every increment in the range is associated with a tick mark.

TBM_SETTICFREQ
    wParam = (WPARAM) wFreq;
    lParam = (LPARAM) 0;

Parameters

wFreq
Frequency of the tick marks.

Return Values

No return value.

Remarks

The trackbar must have the TBS_AUTOTICKS style to use this message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TBM_SETTIPSIDE

Positions a ToolTip control used by a trackbar control. Trackbar controls that use the TBS_TOOLTIPS style display ToolTips.

TBM_SETTIPSIDE
    wParam = (WPARAM)(int) fLocation;
    lParam = 0;

Parameters

fLocation
Value representing the location at which to display the ToolTip control. This value can be one of the following:
TBTS_TOP | The ToolTip control will be positioned above the trackbar. This flag is for use with horizontal trackbars.
TBTS_LEFT | The ToolTip control will be positioned to the left of the trackbar. This flag is for use with vertical trackbars.
TBTS_BOTTOM | The ToolTip control will be positioned below the trackbar. This flag is for use with horizontal trackbars.
TBTS_RIGHT | The ToolTip control will be positioned to the right of the trackbar. This flag is for use with vertical trackbars.

Return Values

Returns a value that represents the ToolTip control's previous location. The return value equals one of the possible values for fLocation.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBM_SETTOOLTIPS

Assigns a ToolTip control to a trackbar control.

TBM_SETTOOLTIPS
    wParam = (WPARAM)(HWND) hwndTT;
    lParam = 0;

Parameters

hwndTT
Handle to an existing ToolTip control.

Return Values

The return value for this message is not used.

Remarks

When a trackbar control is created with the TBS_TOOLTIPS style, it creates a default ToolTip control that appears next to the slider, displaying the slider's current position.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TBM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

TBM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

TBM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (trackbar)

Sent by a trackbar control to notify its parent windows about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Address of an NMCUSTOMDRAW structure that contains information about the drawing operation. The dwItemSpec member of this structure will contain one of the Custom Draw Values that indicates which part of the control is being drawn. Trackbar controls insert the following values into the dwItemSpec member of this structure to identify the portion of the control being drawn:
TBCD_CHANNEL | Identifies the channel that the trackbar control's thumb marker slides along.
TBCD_THUMB | Identifies the trackbar control's thumb marker. This is the portion of the control that the user moves.
TBCD_TICS | Identifies the increment tick marks that appear along the edge of the trackbar control.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:
CDRF_DODEFAULT
The control will draw itself. It will not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW
The control will notify the parent of any item-related drawing operations. It will send NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE
The control will notify the parent when an item will be erased. It will send NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE
The control will notify the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT
The control will notify the parent after painting an item.
CDRF_NOTIFYSUBITEMDRAW
Version 4.71. The control will notify the parent when a list-view subitem is being drawn.

When dwDrawStage equals CDDS_ITEMPREPAINT:
CDRF_NEWFONT
Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing fonts and colors.
CDRF_SKIPDEFAULT
Your application drew the item manually. The control will not draw the item.

See Also

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (trackbar)

Notifies a trackbar control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


Tree-View Controls

A tree-view control is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of subitems associated with it. By clicking an item, the user can expand or collapse the associated list of subitems.

  • About Tree-View Controls
  • Using Tree-View Controls
  • Tree-View Control Updates in Internet Explorer
  • Tree-View Control Reference

About Tree-View Controls

You create a tree-view control by using the CreateWindowEx function, specifying the WC_TREEVIEW window class. The class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, include the InitCommonControls function in your application. The following illustration shows a tree-view control that displays a table of contents.

Tree-view control that displays a table of contents.

After creating a tree-view control, you add, remove, arrange, or otherwise manipulate items by sending messages to the control. Each message has one or more corresponding macros that you can use instead of sending the message explicitly.

Tree-View Styles

Tree-view styles govern aspects of a tree-view control's appearance. You set the initial styles when you create the tree-view control. You can retrieve and change the styles after creating the tree-view control by using the GetWindowLong and SetWindowLong functions.

The TVS_HASLINES style enhances the graphic representation of a tree-view control's hierarchy by drawing lines that link child items to their parent item. This style does not link items at the root of the hierarchy. To do so, you need to combine the TVS_HASLINES and TVS_LINESATROOT styles.

The user can expand or collapse a parent item's list of child items by double-clicking the parent item. A tree-view control that has the TVS_HASBUTTONS style adds a button to the left side of each parent item. The user can click the button once instead of double-clicking the parent item to expand or collapse the child. TVS_HASBUTTONS does not add buttons to items at the root of the hierarchy. To do so, you must combine TVS_HASLINES, TVS_LINESATROOT, and TVS_HASBUTTONS.

The TVS_EDITLABELS style makes it possible for the user to edit the labels of tree-view items. For more information about editing labels, see Tree-View Label Editing.

The TVS_SHOWSELALWAYS style causes a selected item to remain selected when the tree-view control loses focus.

The TVS_CHECKBOXES style creates checkboxes next to each item. If you want to use the checkbox style, you must set the TVS_CHECKBOXES style (with SetWindowLong) after you create the treeview control and before you populate the tree. Otherwise, the checkboxes might appear unchecked, depending on timing issues.

Parent and Child Items

Any item in a tree-view control can have a list of subitems—called child items—associated with it. An item that has one or more child items is called a parent item. A child item is displayed below its parent item and is indented to indicate that it is subordinate to the parent. An item that has no parent appears at the top of the hierarchy and is called a root item.

To add an item to a tree-view control, send the TVM_INSERTITEM message to the control. The message returns a handle to the HTREEITEM type, which uniquely identifies the item. When adding an item, you must specify the handle to the new item's parent item. If you specify NULL or the TVI_ROOT value instead of a parent item handle in the TVINSERTSTRUCT structure, the item is added as a root item.

At any given time, the state of a parent item's list of child items can be either expanded or collapsed. When the state is expanded, the child items are displayed below the parent item. When it is collapsed, the child items are not displayed. The list automatically toggles between the expanded and collapsed states when the user double-clicks the parent item or, if the parent has the TVS_HASBUTTONS style, when the user clicks the button associated with the parent item. An application can expand or collapse the child items by using the TVM_EXPAND message.

A tree-view control sends the parent window a TVN_ITEMEXPANDING notification message when a parent item's list of child items is about to be expanded or collapsed. The notification gives an application the opportunity to prevent the change or to set any attributes of the parent item that depend on the state of the list of child items. After changing the state of the list, the tree-view control sends the parent window a TVN_ITEMEXPANDED notification message.

When a list of child items is expanded, it is indented relative to the parent item. You can set the amount of indentation by using the TVM_SETINDENT message or retrieve the current amount by using the TVM_GETINDENT message.

A tree-view control uses memory allocated from the heap of the process that creates the tree-view control. The maximum number of items in a tree view is based on the amount of memory available in the heap.

Item Labels

You typically specify the text of an item's label when adding the item to the tree-view control. The TVM_INSERTITEM message includes a TVITEM structure that defines the item's properties, including a string containing the text of the label.

A tree-view control allocates memory for storing each item; the text of the item labels takes up a significant portion of this memory. If your application maintains a copy of the strings in the tree-view control, you can decrease the memory requirements of the control by specifying the LPSTR_TEXTCALLBACK value in the pszText member of TVITEM instead of passing actual strings to the tree view. Using LPSTR_TEXTCALLBACK causes the tree-view control to retrieve the text of an item's label from the parent window whenever the item needs to be redrawn. To retrieve the text, the tree-view control sends a TVN_GETDISPINFO notification message, which includes the address of an NMTVDISPINFO structure. The parent window must fill the appropriate members of the included structure.

Tree-View Label Editing

The user can directly edit the labels of items in a tree-view control that has the TVS_EDITLABELS style. The user begins editing by clicking the label of the item that has the focus. An application begins editing by using the TVM_EDITLABEL message. The tree-view control notifies the parent window when editing begins and when it is canceled or completed. When editing is completed, the parent window is responsible for updating the item's label, if appropriate.

When label editing begins, a tree-view control sends its parent window a TVN_BEGINLABELEDIT notification message. By processing this notification, an application can allow editing of some labels and prevent editing of others. Returning zero allows editing, and returning nonzero prevents it.

When label editing is canceled or completed, a tree-view control sends its parent window a TVN_ENDLABELEDIT notification message. The lParam parameter is the address of an NMTVDISPINFO structure. The item member is a TVITEM structure that identifies the item and includes the edited text. The parent window is responsible for updating the item's label if it wishes to keep the new label. The pszText member of TVITEM is zero if editing is canceled.

During label editing, typically in response to the TVN_BEGINLABELEDIT notification message, you can retrieve the handle to the edit control used for label editing by using the TVM_GETEDITCONTROL message. You can send the edit control an EM_SETLIMITTEXT message to limit the amount of text a user can enter or subclass the edit control to intercept and discard invalid characters. Note, however, that the edit control is displayed only after TVN_BEGINLABELEDIT is sent.

Tree-View Item Position

An item's initial position is set when the item is added to the tree-view control by using the TVM_INSERTITEM message. The message includes a TVINSERTSTRUCT structure that specifies the handle to the parent item and the handle to the item after which the new item is to be inserted. The second handle must identify either a child item of the given parent or one of these values: TVI_FIRST, TVI_LAST, or TVI_SORT.

When TVI_FIRST or TVI_LAST is specified, the tree-view control places the new item at the beginning or end of the given parent item's list of child items. When TVI_SORT is specified, the tree-view control inserts the new item into the list of child items in alphabetical order based on the text of the item labels.

You can put a parent item's list of child items in alphabetical order by using the TVM_SORTCHILDREN message. The message includes a parameter that specifies whether all levels of child items descending from the given parent item are also sorted in alphabetical order.

The TVM_SORTCHILDRENCB message allows you to sort child items based on criteria that you define. When you use this message, you specify an application-defined callback function that the tree-view control can call whenever the relative order of two child items needs to be decided. The callback function receives two 32-bit application-defined values for the items being compared and a third 32-bit value that you specify when sending TVM_SORTCHILDRENCB.

Tree-View Item States Overview

Each item in a tree-view control has a current state. The state information for each item includes a set of bit flags as well as image list indexes that indicate the item's state image and overlay image. The bit flags indicate whether the item is selected, disabled, expanded, and so on. For the most part, a tree-view control automatically sets an item's state to reflect user actions, such as selection of an item. However, you can also set an item's state by using the TVM_SETITEM message, and you can retrieve the current state of an item by using the TVM_GETITEM message. For a complete list of item states, see Tree-View Control Item States.

An item's current state is specified by the state member of the TVITEM structure. A tree-view control might change an item's state to reflect a user action, such as selecting the item or setting the focus to the item. In addition, an application might change an item's state to disable or hide the item or to specify an overlay image or state image.

When you specify or change an item's state, the stateMask member of TVITEM specifies which state bits to set, and the state member contains the new values for those bits.

To set an item's overlay image, stateMask must include the TVIS_OVERLAYMASK value, and state must include the one-based index of the overlay image shifted left 8 bits by using the INDEXTOOVERLAYMASK macro. The index can be zero to specify no overlay image.

A state image is displayed next to an item's icon to indicate an application-defined state. State images are contained in a state image list that is specified by sending a TVM_SETIMAGELIST message. To set an item's state image, include the TVIS_STATEIMAGEMASK value in the stateMask member of the TVITEM structure. Bits 12 through 15 of the structure's state member specify the index in the state image list of the image to be drawn.

To set the state image index, use INDEXTOSTATEIMAGEMASK. This macro takes an index, and sets bits 12 through 15 appropriately. To indicate that the item has no state image, set the index to zero. This convention means that image zero in the state image list cannot be used as a state image. To isolate bits 12 through 15 of the state member, use the TVIS_STATEIMAGEMASK mask. For more information about overlay and state images, see Tree-View Image Lists.

Item Selection

A tree-view control notifies the parent window when the selection changes from one item to another by sending the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Both notifications include a value that specifies whether the change is the result of a mouse click or a keystroke. The notifications also include information about the item that is gaining the selection and the item that is losing the selection. You can use this information to set item attributes that depend on the selection state of the item. Returning TRUE in response to TVN_SELCHANGING prevents the selection from changing, and returning FALSE allows the change.

An application can change the selection by sending the TVM_SELECTITEM message.

Item Information

Tree-view controls support a number of messages that retrieve information about items in the control.

The TVM_GETITEM message can retrieve an item's handle and attributes. An item's attributes include its current state, the indexes in the control's image list of the item's selected and nonselected bitmapped images, a flag that indicates whether the item has child items, the address of the item's label string, and the item's application-defined 32-bit value.

The TVM_GETNEXTITEM message retrieves the tree-view item that bears the specified relationship to the current item. The message can retrieve an item's parent, the next or previous visible item, the first child item, and so on.

The TVM_GETITEMRECT message retrieves the bounding rectangle for a tree-view item. The TVM_GETCOUNT and TVM_GETVISIBLECOUNT messages retrieve a count of the items in a tree-view control and a count of the items that can be fully visible in the tree-view control's window, respectively. You can ensure that a particular item is visible by using the TVM_ENSUREVISIBLE message.

Tree-View Image Lists

Each item in a tree-view control can have four bitmapped images associated with it:

  • An image, such as an open folder, displayed when the item is selected.
  • An image, such as a closed folder, displayed when the item is not selected.
  • An overlay image that is drawn transparently over the selected or nonselected image.
  • A state image, which is an additional image displayed to the left of the selected or nonselected image. You can use state images, such as checked and cleared check boxes, to indicate application-defined item states.

By default, a tree-view control does not display item images. To display item images, you must create image lists and associate them with the control. For more information about image lists, see Image Lists.

A tree-view control can have two image lists: a normal image list and a state image list. A normal image list stores the selected, nonselected, and overlay images. A state image list stores state images. Use the ImageList_Create function to create an image list, and use other image list functions to add bitmaps to the image list. Then, to associate the image list with the tree-view control, use the TVM_SETIMAGELIST message. The TVM_GETIMAGELIST message retrieves a handle to one of a tree-view control's image lists. This message is useful if you need to add more images to the list.

In addition to the selected and nonselected images, a tree-view control's normal image list can contain up to four overlay images. Overlay images are identified by a one-based index and are designed to be drawn transparently over the selected and nonselected images. To assign an overlay mask index to an image in the normal image list, call the ImageList_SetOverlayImage function.

By default, all items display the first image in the normal image list for both the selected and nonselected states. Also, by default, items do not display overlay images or state images. You can change these default behaviors for an item by sending the TVM_INSERTITEM or TVM_SETITEM message. These messages use the TVITEM structure to specify image list indexes for an item.

To specify an item's selected and nonselected images, set the TVIF_SELECTEDIMAGE and TVIF_IMAGE bits in the mask member of the TVITEM structure and specify indexes from the control's normal image list in the iSelectImage and iImage members. Alternatively, you can specify the I_IMAGECALLBACK value in iSelectImage and iImage instead of specifying indexes. This causes the control to query its parent window for an image list index each time the item is about to be redrawn. The control sends the TVN_GETDISPINFO notification message to retrieve the index.

To associate an overlay image with an item, use the INDEXTOOVERLAYMASK macro to specify an overlay mask index in the state member of the item's TVITEM structure. You must also set the TVIS_OVERLAYMASK bits in the stateMask member. Overlay mask indexes are one-based; an index of zero indicates that no overlay image was specified.

State images are stored in a separate state image list and identified by their index. To specify the state image list, send a TVM_SETIMAGELIST message. Unlike the list-view control, which uses a one-based index to identify state images, tree-view control state images are identified by a zero-based index. However, an index of zero indicates that the item does not have a state image. Consequently, image zero cannot be used as a state image. For further discussion of item states and state images, see Tree-View Item States Overview.

Drag-and-Drop Operations

A tree-view control notifies the parent window when the user starts to drag an item. The parent window receives a TVN_BEGINDRAG notification message when the user begins dragging an item with the left mouse button and a TVN_BEGINRDRAG notification message when the user begins dragging with the right button. You can prevent a tree-view control from sending these notifications by giving the tree-view control the TVS_DISABLEDRAGDROP style.

You obtain an image to display during a drag operation by using the TVM_CREATEDRAGIMAGE message. The tree-view control creates a dragging bitmap based on the label of the item being dragged. Then the tree-view control creates an image list, adds the bitmap to it, and returns the handle to the image list.

You must provide the code that actually drags the item. This typically involves using the dragging capabilities of the image list functions and processing the WM_MOUSEMOVE and WM_LBUTTONUP (or WM_RBUTTONUP) messages sent to the parent window after the drag operation has begun. For more information, see Dragging a Tree-View Item.

If items in a tree-view control are to be the targets of drag-and-drop operations, you need to know when the mouse pointer is on a target item. You can find out by using the TVM_HITTEST message. You specify the address of a TVHITTESTINFO structure that contains the current coordinates of the mouse pointer. When the SendMessage function returns, the structure contains a flag indicating the location of the mouse pointer relative to the tree-view control. If the pointer is over an item in the tree-view control, the structure contains the handle to the item as well.

You can indicate that an item is the target of a drag-and-drop operation by using the TVM_SETITEM message to set the state to the TVIS_DROPHILITED value. An item that has this state is drawn in the style used to indicate a drag-and-drop target.

About Tree-View Control Notification Messages

A tree-view control sends the following notification messages to its parent window in the form of WM_NOTIFY messages.

Notification | Description
TVN_BEGINDRAG | Signals the start of a drag-and-drop operation.
TVN_BEGINLABELEDIT | Signals the start of in-place label editing.
TVN_BEGINRDRAG | Signals that the right mouse button has started a drag-and-drop operation.
TVN_DELETEITEM | Signals the deletion of a specific item.
TVN_ENDLABELEDIT | Signals the end of label editing.
TVN_GETDISPINFO | Requests information that the tree-view control requires to display an item.
TVN_ITEMEXPANDED | Signals that a parent item's list of child items was expanded or collapsed.
TVN_ITEMEXPANDING | Signals that a parent item's list of child items is about to be expanded or collapsed.
TVN_KEYDOWN | Signals a keyboard event.
TVN_SELCHANGED | Signals that the selection has changed from one item to another.
TVN_SELCHANGING | Signals that the selection is about to be changed from one item to another.
TVN_SETDISPINFO | Notifies a parent window that it must update the information it maintains for an item.

Default Tree-View Control Message Processing

This section describes the window message processing performed by a tree-view control. Messages specific to tree-view controls are discussed in other sections of this document, so they are not included here.

Message | Processing performed
WM_COMMAND | Processes the EN_UPDATE and EN_KILLFOCUS edit control notification messages and forwards all other edit control notifications to the parent window. There is no return value.
WM_CREATE | Allocates memory and initializes internal data structures. It returns zero if successful, or -1 otherwise.
WM_DESTROY | Frees all system resources associated with the control. It returns zero.
WM_ENABLE | Enables or disables the control.
WM_ERASEBKGND | Erases the window background using the current background color for the tree-view control. It returns TRUE.
WM_GETDLGCODE | Returns a combination of the DLGC_WANTARROWS and DLGC_WANTCHARS values.
WM_GETFONT | Returns the handle to the current label font.
WM_HSCROLL | Scrolls the tree-view control. It returns TRUE if scrolling occurs, or FALSE otherwise.
WM_KEYDOWN | Sends the TVN_KEYDOWN notification message to the parent window for all keys. Sends the NM_RETURN notification message when the user presses the ENTER key. It moves the caret when the user presses the direction keys or the PAGE UP, PAGE DOWN, HOME, END, or BACKSPACE key. It scrolls the tree-view control when the user presses the CTRL key in combination with those keys. It returns TRUE if a key is processed, or FALSE otherwise.
WM_KILLFOCUS | Repaints the focused item, if any, and sends an NM_KILLFOCUS notification message to the parent window.
WM_LBUTTONDBLCLK | Cancels label editing and, if an item was double-clicked, sends the NM_DBLCLK notification message to the parent window. If the parent window returns 0, the tree-view control toggles the expanded state of the item, sending the parent window the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages. There is no return value.
WM_LBUTTONDOWN | Toggles the expanded state if the user clicked the button associated with a parent item. If the user clicked an item label, the tree-view control selects and sets the focus to the item. If the user moves the mouse before releasing the mouse button, the tree-view control begins a drag-and-drop operation. There is no return value.
WM_PAINT | Paints the invalid region of the tree-view control. It returns zero. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_RBUTTONDOWN | Checks to see if an item was clicked and a drag operation was begun. If the operation has begun, it sends a TVN_BEGINRDRAG notification message to the parent window and highlights the drop target. Otherwise, it sends an NM_RCLICK notification message to the parent window. There is no return value.
WM_SETFOCUS | Repaints the focused item, if any, and sends an NM_SETFOCUS notification message to the parent window.
WM_SETFONT | Saves the specified font handle and repaints the tree-view control using the new font.
WM_SETREDRAW | Sets or clears the redraw flag. The tree-view control is redrawn after the redraw flag is set. It returns zero.
WM_SIZE | Recomputes internal variables that depend on the size of the tree-view control's client area. It returns TRUE.
WM_STYLECHANGED | Cancels label editing and redraws the tree-view control using the new styles. It returns zero.
WM_SYSCOLORCHANGE | Redraws the tree-view control using the new color if the redraw flag is set. There is no return value.
WM_TIMER | Begins editing an item label. If the user clicks the label of the focused item, the tree-view control sets a timer instead of entering edit mode immediately. The timer makes it possible for the tree view to avoid entering edit mode if the user double-clicks the label. It returns zero.
WM_VSCROLL | Scrolls the tree-view control. It returns TRUE if scrolling occurs, or FALSE otherwise.

Using Tree-View Controls

This section contains examples that demonstrate the following tasks:

  • Creating a tree-view control
  • Initializing the image list
  • Adding tree-view items
  • Dragging a tree-view item

Creating a Tree-View Control

To create a tree-view control, use the >CreateWindowEx function, specifying the WC_TREEVIEW value for the window class. The tree-view window class is registered in the application's address space when the common control dynamic-link library (DLL) is loaded. To ensure that the DLL is loaded, use the InitCommonControls function.

Note When you create a tree-view control, you can also send it a WM_SETFONT message to set the font to be used for the text in the tree view. You should send this message prior to inserting any items. By default, a tree view uses the icon title font. Although you can customize the font on a per-item basis (by using custom draw), the tree-view control uses the dimensions of the font specified by the WM_SETFONT message to determine spacing and layout.

The following example creates a tree-view control that is sized to fit the client area of the parent window. It also uses application-defined functions to associate an image list with the control and add items to the control.

// CreateATreeView - creates a tree-view control.
// Returns the handle to the new control if successful,
// or NULL otherwise.
// hwndParent - handle to the control's parent window.
// lpszFileName - name of the file to parse for tree-view items.

HWND CreateATreeView(HWND hwndParent, LPSTR lpszFileName)
{
    RECT rcClient;  // dimensions of client area
    HWND hwndTV;    // handle to tree-view control

    // Ensure that the common control DLL is loaded.
    InitCommonControls();

    // Get the dimensions of the parent window's client area, and create
    // the tree-view control.
    GetClientRect(hwndParent, &rcClient);
    hwndTV = CreateWindowEx(0, WC_TREEVIEW, "Tree View",
        WS_VISIBLE | WS_CHILD | WS_BORDER | TVS_HASLINES,
        0, 0, rcClient.right, rcClient.bottom,
        hwndParent, (HMENU) ID_TREEVIEW, g_hinst, NULL);

    // Initialize the image list, and add items to the control.
    // InitTreeViewImageLists and InitTreeViewItems are application-
    // defined functions.
    if (!InitTreeViewImageLists(hwndTV) ||
            !InitTreeViewItems(hwndTV, lpszFileName)) {
        DestroyWindow(hwndTV);
        return FALSE;
    }
    return hwndTV;
}

Initializing the Image List

Every item in a tree-view control can have two images associated with it. An item displays one image when it is selected and the other when it is not. To include images with tree-view items, first use the image list functions to create an image list and add images to it. Then associate the image list with the tree-view control by using the TVM_SETIMAGELIST message.

The following example creates an image list, adds three bitmaps to the list, and associates the image list with a tree-view control.

// InitTreeViewImageLists - creates an image list, adds three bitmaps
// to it, and associates the image list with a tree-view control.
// Returns TRUE if successful, or FALSE otherwise.
// hwndTV - handle to the tree-view control.
//
// Global variables and constants
// g_nOpen, g_nClosed, and g_nDocument - integer variables for
// indexes of the images.
// CX_BITMAP and CY_BITMAP - width and height of an icon.
// NUM_BITMAPS - number of bitmaps to add to the image list.

BOOL InitTreeViewImageLists(HWND hwndTV)
{
    HIMAGELIST himl;  // handle to image list
    HBITMAP hbmp;     // handle to bitmap

    // Create the image list.
    if ((himl = ImageList_Create(CX_BITMAP, CY_BITMAP,
        FALSE, NUM_BITMAPS, 0)) == NULL)
        return FALSE;

    // Add the open file, closed file, and document bitmaps.
    hbmp = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_OPEN_FILE));
    g_nOpen = ImageList_Add(himl, hbmp, (HBITMAP) NULL);
    DeleteObject(hbmp);

    hbmp = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_CLOSED_FILE));
    g_nClosed = ImageList_Add(himl, hbmp, (HBITMAP) NULL);
    DeleteObject(hbmp);

    hbmp = LoadBitmap(g_hinst, MAKEINTRESOURCE(IDB_DOCUMENT));
    g_nDocument = ImageList_Add(himl, hbmp, (HBITMAP) NULL);
    DeleteObject(hbmp);

    // Fail if not all of the images were added.
    if (ImageList_GetImageCount(himl) < 3)
        return FALSE;

    // Associate the image list with the tree-view control.
    TreeView_SetImageList(hwndTV, himl, TVSIL_NORMAL);

    return TRUE;
}

Adding Tree-View Items

You add an item to a tree-view control by sending the TVM_INSERTITEM message to the control. The message includes the address of a TVINSERTSTRUCT structure, specifying the parent item, the item after which the new item is inserted, and a TVITEM structure that defines the attributes of the item. The attributes include the item's label, its selected and nonselected images, and a 32-bit application-defined value.

The example in this section demonstrates how to create a table of contents based on the information in a text file. The example includes two functions. The first function searches a file for headings. When it finds one, it extracts the text of the heading and the value that indicates the level of the heading and then passes them to the second function.

The second function adds an item to a tree-view control, using the heading text as the item's label and the heading level to determine the parent item for the new item. A level one heading is added to the root of the tree-view control, a level two heading is added as a child item of the previous level one item, and so on. The function assigns an image to an item based on whether it has any child items. If an item has child items, it gets an image representing a closed folder. Otherwise, it gets an image representing a document. An item uses the same image for both the selected and nonselected states.

// InitTreeViewItems - extracts headings from the specified file and
// passes them to a function that adds them to a tree-view control.
// Returns TRUE if successful, or FALSE otherwise.
// hwndTV - handle to the tree-view control.
// lpszFileName - name of file with headings.

BOOL InitTreeViewItems(HWND hwndTV, LPSTR lpszFileName)
{
    HANDLE hf;            // handle to file
    char szItemText[128]; // label text of tree-view item
    int nLevel;           // heading level

    // Open the file to parse.
    if ((hf = CreateFile(lpszFileName, GENERIC_READ,
            FILE_SHARE_READ, (LPSECURITY_ATTRIBUTES) NULL,
            OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL,
            (HANDLE) NULL)) == (HANDLE) INVALID_HANDLE_VALUE)
        return FALSE;

    // Call private function to parse the file looking for headings.
    while ( GetNextHeadingAndLevelFromFile(hf, szItemText, &nLevel) )
         // Add the item to the tree-view control.
         AddItemToTree(hwndTV, szItemText, nLevel);

    return TRUE;
}

// AddItemToTree - adds items to a tree-view control.
// Returns the handle to the newly added item.
// hwndTV - handle to the tree-view control.
// lpszItem - text of the item to add.
// nLevel - level at which to add the item.

HTREEITEM AddItemToTree(HWND hwndTV, LPSTR lpszItem, int nLevel)
{
    TVITEM tvi;
    TVINSERTSTRUCT tvins;
    static HTREEITEM hPrev = (HTREEITEM) TVI_FIRST;
    static HTREEITEM hPrevRootItem = NULL;
    static HTREEITEM hPrevLev2Item = NULL;
    HTREEITEM hti;

    tvi.mask = TVIF_TEXT | TVIF_IMAGE
        | TVIF_SELECTEDIMAGE | TVIF_PARAM;

    // Set the text of the item.
    tvi.pszText = lpszItem;
    tvi.cchTextMax = lstrlen(lpszItem);

    // Assume the item is not a parent item, so give it a
    // document image.
    tvi.iImage = g_nDocument;
    tvi.iSelectedImage = g_nDocument;

    // Save the heading level in the item's application-defined
    // data area.
    tvi.lParam = (LPARAM) nLevel;

    tvins.item = tvi;
    tvins.hInsertAfter = hPrev;

    // Set the parent item based on the specified level.
    if (nLevel == 1)
        tvins.hParent = TVI_ROOT;
    else if (nLevel == 2)
        tvins.hParent = hPrevRootItem;
    else
        tvins.hParent = hPrevLev2Item;

    // Add the item to the tree-view control.
    hPrev = (HTREEITEM) SendMessage(hwndTV, TVM_INSERTITEM, 0,
         (LPARAM) (LPTVINSERTSTRUCT) &tvins);

    // Save the handle to the item.
    if (nLevel == 1)
        hPrevRootItem = hPrev;
    else if (nLevel == 2)
        hPrevLev2Item = hPrev;

    // The new item is a child item. Give the parent item a
    // closed folder bitmap to indicate it now has child items.
    if (nLevel > 1) {
        hti = TreeView_GetParent(hwndTV, hPrev);
        tvi.mask = TVIF_IMAGE | TVIF_SELECTEDIMAGE;
        tvi.hItem = hti;
        tvi.iImage = g_nClosed;
        tvi.iSelectedImage = g_nClosed;
        TreeView_SetItem(hwndTV, &tvi);
    }

    return hPrev;
}

Dragging a Tree-View Item

Dragging a tree-view item typically involves processing the TVN_BEGINDRAG (or TVN_BEGINRDRAG) notification message, the WM_MOUSEMOVE message, and the WM_LBUTTONUP (or WM_RBUTTONUP) message. It also involves using the image list functions to draw the item as it is being dragged.

The remainder of this section provides an example that demonstrates how to drag a tree-view item. The example consists of three functions. The first function begins the drag operation, the second drags the image, and the third ends the drag operation.

Beginning the tree-view drag operation

A tree-view control sends the parent window a TVN_BEGINDRAG (or TVN_BEGINRDRAG) notification message whenever the user starts to drag an item. The parent window receives the notification in the form of a WM_NOTIFY message whose lParam parameter is the address of an NMTREEVIEW structure. The members of this structure include the screen coordinates of the mouse pointer and a TVITEM structure that contains information about the item to be dragged.

The following example shows how to process the WM_NOTIFY message to obtain TVN_BEGINDRAG.

case WM_NOTIFY:
     switch (((LPNMHDR) lParam)->code) {
        case TVN_BEGINDRAG:
         Main_OnBeginDrag(   // application-defined function
                         hwndTV, (LPNMTREEVIEW) lParam);
             break;

        // Handle other notifications here.

       }
     break;

Beginning the drag operation involves using the ImageList_BeginDrag function. The function's parameters include the handle to the image list containing the image to use during the drag operation and the index of the image. You can either provide your own image list and image, or you can have the tree-view control create them for you by using the TVM_CREATEDRAGIMAGE message.

Because the drag image replaces the mouse pointer for the duration of the drag operation, ImageList_BeginDrag requires you to specify a hot spot within the image. The coordinates of the hot spot are relative to the upper left corner of the image. ImageList_BeginDrag also requires you to specify the initial location of the drag image. An application typically sets the initial location so that the hot spot of the drag image corresponds to that of the mouse pointer at the time the user began the drag operation.

The following function demonstrates how to begin dragging a tree-view item. It uses the drag image provided by the tree-view control and obtains the bounding rectangle of the item to determine the appropriate point for the hot spot. (The dimensions of the bounding rectangle are the same as those of the image.) Note that the bounding rectangle does not account for the indentation of child items. For this reason, the function adds the amount of indentation to the x-coordinate of the hot spot.

The function captures mouse input, causing mouse messages to be sent to the parent window. The parent window needs the subsequent WM_MOUSEMOVE messages to determine where to drag the image and the WM_LBUTTONUP message to determine when to end the drag operation.

// Main_OnBeginDrag - begins dragging an item in a tree-view control.
// hwndTV - handle to the image list.
// lpnmtv - address of information about the item being dragged.

void Main_OnBeginDrag(HWND hwndTV, LPNMTREEVIEW lpnmtv)
{
    HIMAGELIST himl;    // handle to image list
    RECT rcItem;        // bounding rectangle of item
    DWORD dwLevel;      // heading level of item
    DWORD dwIndent;     // amount that child items are indented

    // Tell the tree-view control to create an image to use
    // for dragging.
    himl = TreeView_CreateDragImage(hwndTV, lpnmtv->itemNew.hItem);

    // Get the bounding rectangle of the item being dragged.
    TreeView_GetItemRect(hwndTV, lpnmtv->itemNew.hItem, &rcItem, TRUE);

    // Get the heading level and the amount that the child items are
    // indented.
    dwLevel = lpnmtv->itemNew.lParam;
    dwIndent = (DWORD) SendMessage(hwndTV, TVM_GETINDENT, 0, 0);

    // Start the drag operation.
    ImageList_BeginDrag(himl, 0, 0, 0);

    // Hide the mouse pointer, and direct mouse input to the
    // parent window.
    ShowCursor(FALSE);
    SetCapture(GetParent(hwndTV));
    g_fDragging = TRUE;
    return;
}

Dragging the tree-view item

You drag a tree-view item by calling the ImageList_DragMove function when the parent window receives a WM_MOUSEMOVE message, as the following example shows. The example also demonstrates how to perform hit testing during the drag operation to determine whether to highlight other items in the tree view as targets of a drag-and-drop operation.

// Main_OnMouseMove - drags an item in a tree-view control,
// highlighting the item that is the target.
// hwndParent - handle to the parent window.
// hwndTV - handle to the tree-view control.
// xCur and yCur - x- and y-coordinates of the mouse pointer.

void Main_OnMouseMove(HWND hwndParent, HWND hwndTV, LONG xCur, LONG yCur)
{
    HTREEITEM htiTarget;  // handle to target item
    TVHITTESTINFO tvht;  // hit test information

    if (g_fDragging) {

        // Drag the item to the current position of the mouse pointer.
        ImageList_DragMove(xCur, yCur);

        // Find out if the pointer is on the item. If it is,
        // highlight the item as a drop target.
        tvht.pt.x = xCur;
        tvht.pt.y = yCur;
        if ((htiTarget = TreeView_HitTest(hwndTV, &tvht)) != NULL) {
            TreeView_SelectDropTarget(hwndTV, htiTarget);
        }
    }
    return;
}

Ending the tree-view drag operation

The following example shows how to end a drag operation. The ImageList_EndDrag function is called when the parent window receives a WM_LBUTTONUP message.

// Main_OnLButtonUp - stops dragging a tree-view item, releases the
// mouse capture, and shows the mouse pointer.
//
// Global variable g_fDragging - indicates whether
// a drag operation is underway.

void Main_OnLButtonUp(void)
{
    if (g_fDragging) {
        ImageList_EndDrag();
        ReleaseCapture();
        ShowCursor(TRUE);
        g_fDragging = FALSE;
    }
    return;
}

Working with state image indexes

There is often confusion about how to set and retrieve the state image index in a tree-view control. The following examples demonstrate the proper method for setting and retrieving the state image index. The examples assume that there are only two state image indexes in the tree-view control, unchecked and checked. If your application contains more than two, these functions will need to be modified to handle that case.

The following example function illustrates how to set an item's check state.

BOOL TreeView_SetCheckState(HWND hwndTreeView, HTREEITEM hItem, BOOL fCheck)
{
    TVITEM tvItem;

    tvItem.mask = TVIF_HANDLE | TVIF_STATE;
    tvItem.hItem = hItem;
    tvItem.stateMask = TVIS_STATEIMAGEMASK;

    /*Image 1 in the tree-view check box image list is the
    unchecked box. Image 2 is the checked box.*/

    tvItem.state = INDEXTOSTATEIMAGEMASK((fCheck ? 2 : 1));

    return TreeView_SetItem(hwndTreeView, &tvItem);
}

The following example function illustrates how to retrieve an item's check state.

BOOL TreeView_GetCheckState(HWND hwndTreeView, HTREEITEM hItem)
{
    TVITEM tvItem;

    // Prepare to receive the desired information.
    tvItem.mask = TVIF_HANDLE | TVIF_STATE;
    tvItem.hItem = hItem;
    tvItem.stateMask = TVIS_STATEIMAGEMASK;

    // Request the information.
    TreeView_GetItem(hwndTreeView, &tvItem);

    // Return zero if it's not checked, or nonzero otherwise.
    return ((BOOL)(tvItem.state >> 12) -1);
}

Tree-View Control Updates in Internet Explorer

Tree-view controls in Microsoft® Internet Explorer support the following new features.

ToolTips
Tree-view controls now automatically display ToolTips when an item is not entirely within the view area.
New Item State
Tree-view controls now support a new item state for parent items, TVIS_EXPANDPARTIAL. When a parent item is set to this state, the child items are displayed and the parent's plus sign remains visible. The TVM_EXPAND message and the TreeView_Expand macro have been updated to support this feature.
Single-Click Expansion
The TVS_SINGLEEXPAND style causes a tree-view item to be expanded when it becomes selected and to be closed when it becomes unselected.
Adjustable Maximum Scroll Time
The TVM_SETSCROLLTIME message allows you to set the maximum amount of time that a scroll operation can take. The TVM_GETSCROLLTIME message allows you to retrieve the maximum scroll time.


Tree-View Control Window Styles

The following window styles are used when creating tree-view controls.

TVS_CHECKBOXES
Version 4.70. Enables check boxes for items in a tree-view control. A check box is displayed only if an image is associated with the item. When set to this style, the control effectively uses DrawFrameControl to create and set a state image list containing two images. State image 1 is the unchecked box and state image 2 is the checked box. Setting the state image to zero removes the check box altogether. For more information, see Working with state image indexes.

Version 5.80. Displays a check box even if no image is associated with the item.

Note Once a tree-view control is created with this style, the style cannot be removed. Instead, you must destroy the control and create a new one in its place. Destroying the tree-view control does not destroy the check box state image list. You must destroy it explicitly. Get the handle to the state image list by sending the tree-view control a TVM_GETIMAGELIST message. Then destroy the image list with ImageList_Destroy.

If you want to use this style, you must set the TVS_CHECKBOXES style with SetWindowLong after you create the treeview control, and before you populate the tree. Otherwise, the checkboxes might appear unchecked, depending on timing issues.

TVS_DISABLEDRAGDROP
Prevents the tree-view control from sending TVN_BEGINDRAG notification messages.
TVS_EDITLABELS
Allows the user to edit the labels of tree-view items.
TVS_FULLROWSELECT
Version 4.71. Enables full-row selection in the tree view. The entire row of the selected item is highlighted, and clicking anywhere on an item's row causes it to be selected. This style cannot be used in conjunction with the TVS_HASLINES style.
TVS_HASBUTTONS
Displays plus (+) and minus (-) buttons next to parent items. The user clicks the buttons to expand or collapse a parent item's list of child items. To include buttons with items at the root of the tree view, TVS_LINESATROOT must also be specified.
TVS_HASLINES
Uses lines to show the hierarchy of items.
TVS_INFOTIP
Version 4.71. Obtains ToolTip information by sending the TVN_GETINFOTIP notification.
TVS_LINESATROOT
Uses lines to link items at the root of the tree-view control. This value is ignored if TVS_HASLINES is not also specified.
TVS_NOHSCROLL
Version 5.80. Disables horizontal scrolling in the control. The control will not display any horizontal scroll bars.
TVS_NONEVENHEIGHT
Version 4.71 Sets the height of the items to an odd height with the TVM_SETITEMHEIGHT message. By default, the height of items must be an even value.
TVS_NOSCROLL
Version 4.71. Disables both horizontal and vertical scrolling in the control. The control will not display any scroll bars.
TVS_NOTOOLTIPS
Version 4.70. Disables ToolTips.
TVS_RTLREADING
Version 4.70. Causes text to be displayed from right-to-left (RTL). Usually, windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read RTL. Typically, tree-view text is displayed in the same direction as the text in its parent window. If TVS_RTLREADING is set, tree-view text reads in the opposite direction from the text in the parent window.
TVS_SHOWSELALWAYS
Causes a selected item to remain selected when the tree-view control loses focus.
TVS_SINGLEEXPAND
Version 4.71. Causes the item being selected to expand and the item being unselected to collapse upon selection in the tree view. If the mouse is used to single-click the selected item and that item is closed, it will be expanded. If the user holds down the CTRL key while selecting an item, the item being unselected will not be collapsed.

Version 5.80. Causes the item being selected to expand and the item being unselected to collapse upon selection in the tree view. If the user holds down the CTRL key while selecting an item, the item being unselected will not be collapsed.

TVS_TRACKSELECT
Version 4.70. Enables hot tracking in a tree-view control.


Tree-View Control Item States

The following item state flags are used to indicate the state of an item in a tree-view control.
TVIS_BOLD | The item is bold.
TVIS_CUT | The item is selected as part of a cut-and-paste operation.
TVIS_DROPHILITED | The item is selected as a drag-and-drop target.
TVIS_EXPANDED | The item's list of child items is currently expanded; that is, the child items are visible. This value applies only to parent items.
TVIS_EXPANDEDONCE | The item's list of child items has been expanded at least once. The TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages are not generated for parent items that have this state set in response to a TVM_EXPAND message. Using TVE_COLLAPSE and TVE_COLLAPSERESET with TVM_EXPAND will cause this state to be reset. This value applies only to parent items.
TVIS_EXPANDPARTIAL | Version 4.70. A partially expanded tree-view item. In this state, some, but not all, of the child items are visible and the parent item's plus symbol is displayed.
TVIS_SELECTED | The item is selected. Its appearance depends on whether it has the focus. The item will be drawn using the system colors for selection.

When you set or retrieve an item's overlay image index or state image index, you must specify the following masks in the stateMask member of the TVITEM structure. These values can also be used to mask off the state bits that are not of interest.
TVIS_OVERLAYMASK | Mask for the bits used to specify the item's overlay image index.
TVIS_STATEIMAGEMASK | Mask for the bits used to specify the item's state image index.
TVIS_USERMASK | Same as TVIS_STATEIMAGEMASK.


TVM_CREATEDRAGIMAGE

Creates a dragging bitmap for the specified item in a tree-view control. The message also creates an image list for the bitmap and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can send this message explicitly or by using the TreeView_CreateDragImage macro.

TVM_CREATEDRAGIMAGE
    wParam = 0;
    lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem
Handle to the item that receives the new dragging bitmap.

Return Values

Returns the handle to the image list to which the dragging bitmap was added if successful, or NULL otherwise.

Remarks

If you create a tree-view control without an associated image list, you cannot use the TVM_CREATEDRAGIMAGE message to create the image to display during a drag operation. You must implement your own method of creating a drag cursor.

Your application is responsible for destroying the image list when it is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_DELETEITEM

Removes an item and all its children from a tree-view control. You can send this message explicitly or by using the TreeView_DeleteItem macro.

TVM_DELETEITEM
    wParam = 0;
    lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem
HTREEITEM handle to the item to delete. If hitem is set to TVI_ROOT, all items are deleted. You can also use the TreeView_DeleteAllItems macro to delete all items.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Once an item is deleted, its handle is invalid and cannot be used.

The parent window receives a TVN_DELETEITEM notification message when each item is removed.

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_EDITLABEL

Begins in-place editing of the specified item's text, replacing the text of the item with a single-line edit control containing the text. This message implicitly selects and focuses the specified item. You can send this message explicitly or by using the TreeView_EditLabel macro.

TVM_EDITLABEL
    wParam = 0;
    lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem
Handle to the item to edit.

Return Values

Returns the handle to the edit control used to edit the item text if successful, or NULL otherwise.

Remarks

This message sends a TVN_BEGINLABELEDIT notification message to the parent of the tree-view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_ENDEDITLABELNOW

Ends the editing of a tree-view item's label. You can send this message explicitly or by using the TreeView_EndEditLabelNow macro.

TVM_ENDEDITLABELNOW
    wParam = (WPARAM) (BOOL) fCancel;
    lParam = 0;

Parameters

fCancel
Variable that indicates whether the editing is canceled without being saved to the label. If this parameter is TRUE, the system cancels editing without saving the changes. Otherwise, the system saves the changes to the label.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

This message causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree-view control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_ENSUREVISIBLE

Ensures that a tree-view item is visible, expanding the parent item or scrolling the tree-view control, if necessary. You can send this message explicitly or by using the TreeView_EnsureVisible macro.

TVM_ENSUREVISIBLE
    wParam = 0;
    lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

hitem
Handle to the item.

Return Values

Returns nonzero if the system scrolled the items in the tree-view control and no items were expanded. Otherwise, the message returns zero.

Remarks

If the TVM_ENSUREVISIBLE message expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_EXPAND

The TVM_EXPAND message expands or collapses the list of child items associated with the specified parent item, if any. You can send this message explicitly or by using the TreeView_Expand macro.

TVM_EXPAND
    wParam = (WPARAM) (UINT) flag;
    lParam = (LPARAM) (HTREEITEM) hItem;

Parameters

flag
Action flag. This parameter can be one or more of the following values:
TVE_COLLAPSE | Collapses the list.
TVE_COLLAPSERESET | Collapses the list and removes the child items. The TVIS_EXPANDEDONCE state flag is reset. This flag must be used with the TVE_COLLAPSE flag.
TVE_EXPAND | Expands the list.
TVE_EXPANDPARTIAL | Version 4.70. Partially expands the list. In this state the child items are visible and the parent item's plus sign (+), indicating that it can be expanded, is displayed. This flag must be used in combination with the TVE_EXPAND flag.
TVE_TOGGLE | Collapses the list if it is expanded or expands it if it is collapsed.
hItem
Handle to the parent item to expand or collapse.

Return Values

Returns nonzero if the operation was successful, or zero otherwise.

Remarks

Expanding a node that is already expanded, or collapsing a node that is already collapsed is considered a successful operation and TVM_EXPAND will return a non-zero value. Attempting to expand or collapse a node that has no children is considered a failure and TVM_EXPAND will return zero.

When an item is first expanded , a TVM_EXPAND message generates TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages and the item's TVIS_EXPANDEDONCE state flag is set. As long as this state flag remains set, subsequent TVM_EXPAND messages will not generate TVN_ITEMEXPANDING or TVN_ITEMEXPANDED notifications. To reset the TVIS_EXPANDEDONCE state flag, you must send a TVM_EXPAND message with the TVE_COLLAPSE and TVE_COLLAPSERESET flags set. Attempting to explicitly set TVIS_EXPANDEDONCE will result in unpredictable behavior.

The expand operation may fail if the owner of the treeview control denies the operation in response to a TVN_ITEMEXPANDING notification.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in Commctrl.h.


TVM_GETBKCOLOR

Retrieves the current background color of the control. You can send this message explicitly or by using the TreeView_GetBkColor macro.

TVM_GETBKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that represents the current background color. If this value is -1, the control is using the system color for the background color.

See Also

TVM_SETBKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_GETCOUNT

Retrieves a count of the items in a tree-view control. You can send this message explicitly or by using the TreeView_GetCount macro.

TVM_GETCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the count of items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETEDITCONTROL

Retrieves the handle to the edit control being used to edit a tree-view item's text. You can send this message explicitly or by using the TreeView_GetEditControl macro.

TVM_GETEDITCONTROL
    wParam = 0;
    lParam = 0;

Parameters

None.

Return Values

Returns the handle to the edit control if successful, or NULL otherwise.

Remarks

When label editing begins, an edit control is created, but not positioned or displayed. Before it is displayed, the tree-view control sends its parent window an TVN_BEGINLABELEDIT notification message.

To customize label editing, implement a handler for TVN_BEGINLABELEDIT and have it send a TVM_GETEDITCONTROL message to the tree-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETIMAGELIST

Retrieves the handle to the normal or state image list associated with a tree-view control. You can send this message explicitly or by using the TreeView_GetImageList macro.

TVM_GETIMAGELIST
    wParam = (WPARAM) iImage;
    lParam = 0;

Parameters

iImage
Type of image list to retrieve. This parameter can be one of the following values:
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree-view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.

Return Values

Returns an HIMAGELIST handle to the specified image list.

See Also

TVM_SETIMAGELIST

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETINDENT

Retrieves the amount, in pixels, that child items are indented relative to their parent items. You can send this message explicitly or by using the TreeView_GetIndent macro.

TVM_GETINDENT
    wParam = 0;
    lParam = 0;

Return Values

Returns the amount of indentation.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETINSERTMARKCOLOR

Retrieves the color used to draw the insertion mark for the tree view. You can send this message explicitly or by using the TreeView_GetInsertMarkColor macro.

TVM_GETINSERTMARKCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that contains the current insertion mark color.

See Also

TVM_SETINSERTMARKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_GETISEARCHSTRING

Retrieves the incremental search string for a tree-view control. The tree-view control uses the incremental search string to select an item based on characters typed by the user. You can send this message explicitly or by using the TreeView_GetISearchString macro.

TVM_GETISEARCHSTRING
    wParam = 0;
    lParam = (LPARAM) (LPSTR) lpsz;

Parameters

lpsz
Address of the buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string.

Remarks

If the tree-view control is not in incremental search mode, the return value is zero.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETITEM

Retrieves some or all of a tree-view item's attributes. You can send this message explicitly or by using the TreeView_GetItem macro.

TVM_GETITEM
    wParam = 0;
    lParam = (LPARAM) (LPTVITEM) pitem;

-- Version 4.71 and later --

    wParam = 0;
    lParam = (LPARAM) (LPTVITEMEX) pitem;

Parameters

pitem
Address of a TVITEM structure that specifies the information to retrieve and receives information about the item. With version 4.71 and later, you can use a TVITEMEX structure instead.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the message is sent, the hItem member of the TVITEM or TVITEMEX structure identifies the item to retrieve information about, and the mask member specifies the attributes to retrieve.

If the TVIF_TEXT flag is set in the mask member of the TVITEM or TVITEMEX structure, the pszText member must point to a valid buffer and the cchTextMax member must be set to the number of characters in that buffer. The returned text will not necessarily be stored in the original buffer passed by the application. It is possible that pszText will point to text in a new buffer rather than place it in the old buffer.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TVM_GETITEMHEIGHT

Retrieves the current height of the each tree-view item. You can send this message explicitly or by using the TreeView_GetItemHeight macro.

TVM_GETITEMHEIGHT
    wParam = 0;
    lParam = 0;

Return Values

Returns the height of each item, in pixels.

See Also

TVM_SETITEMHEIGHT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_GETITEMRECT

Retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible. You can send this message explicitly or by using the TreeView_GetItemRect macro.

TVM_GETITEMRECT
    wParam = (WPARAM) (BOOL) fItemRect;
    lParam = (LPARAM) (LPRECT) prc;

Parameters

fItemRect
Value specifying the portion of the item for which to retrieve the bounding rectangle. If this parameter is TRUE, the bounding rectangle includes only the text of the item. Otherwise, it includes the entire line that the item occupies in the tree-view control.
prc
Address of a RECT structure that, when sending the message, contains the handle of the item to retrieve the rectangle for. See the example below for more information on how to place the item handle in this parameter. After returning from the message, this parameter contains the bounding rectangle. The coordinates are relative to the upper-left corner of the tree-view control.

Return Values

If the item is visible and the bounding rectangle was successfully retrieved, the return value is TRUE. Otherwise, the message returns FALSE and does not retrieve the bounding rectangle.

Remarks

When sending this message, the prc parameter contains the handle of the item that the rectangle is being retrieved for. The handle is placed in prc as shown in the following example:

RECT rc;
*(HTREEITEM*)&rc = hTreeItem;
SendMessage(hwndTreeView, TVM_GETITEMRECT, FALSE, (LPARAM)&rc);

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETITEMSTATE

Retrieves some or all of a tree-view item's state attributes. You can send this message explicitly or by using the TreeView_GetItemState macro.

TVM_GETITEMSTATE
    wParam = (WPARAM)(HTREEITEM) hItem;
    lParam = (LPARAM) (UINT) stateMask;

Parameters

hItem
Handle to the item.
stateMask
Mask used to specify the states to query for. It is equivalent to the stateMask member of TVITEMEX.

Return Values

Returns a UINT value with the appropriate state bits set to TRUE. Only those bits that are are specified by StateMask and that are TRUE will be set. This value is equivalent to the state member of TVITEMEX.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TVM_GETLINECOLOR

The TVM_GETLINECOLOR message gets the current line color.

TVM_GETLINECOLOR
    wParam = 0;
    lParam = 0;

Parameters

None

Return Values

Returns the current line color, or the CLR_DEFAULT value if none has been specified.

Remarks

This message only retrieves line colors. To retrieve the colors of the '+' and '-' inside the buttons, use the TVM_GETTEXTCOLOR message.

See Also

TVM_SETLINECOLOR

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TVM_GETNEXTITEM

Retrieves the tree-view item that bears the specified relationship to a specified item. You can send this message explicitly, by using the TreeView_GetNextItem macro.

TVM_GETNEXTITEM
    wParam = (WPARAM) (UINT) flag;
    lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

flag
Flag specifying the item to retrieve. This parameter can be one of the following values:
TVGN_CARET | Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD | Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE | Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilight macro to send this message.
TVGN_FIRSTVISIBLE | Retrieves the first item that is visible in the tree-view window. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_LASTVISIBLE | Version 4.71. Retrieves the last expanded item in the tree. This does not retrieve the last item visible in the tree-view window. You can use the TreeView_GetLastVisible macro to send this message.
TVGN_NEXT | Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE | Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT | Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS | Retrieves the previous sibling item. You can use the TreeView_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE | Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT | Retrieves the topmost or very first item of the tree-view control. You can use the TreeView_GetRoot macro to send this message.
hitem
Handle to an item.

Return Values

Returns the handle to the item if successful. For most cases, the message returns a NULL value to indicate an error. See the Remarks section for details

Remarks

This message will return NULL if the item being retrieved is the root node of the tree. For example, if you use this message with with the TVGN_PARENT flag on a first-level child of the tree view's root node, the message will return NULL.

You can also use one of these related macros:

TreeView_GetChild
TreeView_GetDropHilight
TreeView_GetFirstVisible
TreeView_GetLastVisible
TreeView_GetNextSibling
TreeView_GetNextVisible
TreeView_GetParent
TreeView_GetPrevSibling
TreeView_GetPrevVisible
TreeView_GetRoot
TreeView_GetSelection

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETSCROLLTIME

Retrieves the maximum scroll time for the tree-view control. You can send this message explicitly or by using the TreeView_GetScrollTime macro.

TVM_GETSCROLLTIME
    wParam = 0;
    lParam = 0;

Return Values

Returns the maximum scroll time, in milliseconds.

Remarks

The maximum scroll time is the longest amount of time that a scroll operation can take. The scrolling will be adjusted so that the scroll will take place within the maximum scroll time. A scroll operation may take less time than the maximum.

See Also

TVM_SETSCROLLTIME

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETTEXTCOLOR

Retrieves the current text color of the control. You can send this message explicitly or by using the TreeView_GetTextColor macro.

TVM_GETTEXTCOLOR
    wParam = 0;
    lParam = 0;

Return Values

Returns a COLORREF value that represents the current text color. If this value is -1, the control is using the system color for the text color.

See Also

TVM_SETTEXTCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_GETTOOLTIPS

Retrieves the handle to the child ToolTip control used by a tree-view control. You can send this message explicitly or by using the TreeView_GetToolTips macro.

TVM_GETTOOLTIPS
    wParam = 0;
    lParam = 0;

Return Values

Returns the handle to the child ToolTip control, or NULL if the control is not using ToolTips.

Remarks

When created, tree-view controls automatically create a child ToolTip control. To cause a tree-view control not to use ToolTips, create the control with the TVS_NOTOOLTIPS style.

See Also

TVM_SETTOOLTIPS

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TVM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the TreeView_GetUnicodeFormat macro.

TVM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

TVM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_GETVISIBLECOUNT

Obtains the number of items that can be fully visible in the client window of a tree-view control. You can send this message explicitly or by using the TreeView_GetVisibleCount macro.

TVM_GETVISIBLECOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of items that can be fully visible in the client window of the tree-view control.

Remarks

The number of items that can be fully visible may be greater than the number of items in the control. The control calculates this value by dividing the height of the client window by the height of an item.

Note that the return value is the number of items that can be fully visible. If you can see all of 20 items and part of one more item, the return value is 20.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_HITTEST

Determines the location of the specified point relative to the client area of a tree-view control. You can send this message explicitly or by using the TreeView_HitTest macro.

TVM_HITTEST
    wParam = 0;
    lParam = (LPARAM) (LPTVHITTESTINFO) lpht;

Parameters

lpht
Address of a TVHITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit test value that indicates the location of the specified point. For a list of hit test values, see the description of the TVHITTESTINFO structure.

Return Values

Returns the handle to the tree-view item that occupies the specified point, or NULL if no item occupies the point.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_INSERTITEM

Inserts a new item in a tree-view control. You can send this message explicitly or by using the TreeView_InsertItem macro.

TVM_INSERTITEM
    wParam = 0;
    lParam = (LPARAM) (LPTVINSERTSTRUCT) lpis;

Parameters

lpis
Address of a TVINSERTSTRUCT structure that specifies the attributes of the tree-view item.

Return Values

Returns the handle to the new item if successful, or NULL otherwise.

See Also

TVN_ENDLABELEDIT

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SELECTITEM

Selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can send this message explicitly or by using the TreeView_Select, TreeView_SelectItem, or TreeView_SelectDropTarget macro.

TVM_SELECTITEM
    wParam = (WPARAM) flag;
    lParam = (LPARAM) (HTREEITEM) hitem;

Parameters

flag
Action flag. This parameter can be one of the following values:
TVGN_CARET | Sets the selection to the specified item. The tree-view control's parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages.
TVGN_DROPHILITE | Redraws the specified item in the style used to indicate the target of a drag-and-drop operation.
TVGN_FIRSTVISIBLE | Ensures that the specified item is visible, and, if possible, displays it at the top of the control's window. Tree-view controls display as many items as will fit in the window. If the specified item is near the bottom of the control's hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.
hitem
Handle to an item. If hitem is NULL, the control is set to have no selected item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the control's parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_CARET value. Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_DROPHILITE value. Using TreeView_SelectSetFirstVisible is equivalent to sending the TVM_SELECTITEM message with flag set to the TVGN_FIRSTVISIBLE value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SETBKCOLOR

Sets the background color of the control. You can send this message explicitly or by using the TreeView_SetBkColor macro.

TVM_SETBKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF) clrBk;

Parameters

clrBk
COLORREF value that contains the new background color. If this value is -1, the control will revert to using the system color for the background color.

Return Values

Returns a COLORREF value that represents the previous background color. If this value is -1, the control was using the system color for the background color.

See Also

TVM_GETBKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_SETIMAGELIST

Sets the normal or state image list for a tree-view control and redraws the control using the new images. You can send this message explicitly or by using the TreeView_SetImageList macro.

TVM_SETIMAGELIST
    wParam = (WPARAM) iImage;
    lParam = (LPARAM) (HIMAGELIST) himl;

Parameters

iImage
Type of image list to set. This parameter can be one of the following values:
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree-view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.
himl
Handle to the image list. If himl is NULL, the message removes the specified image list from the tree-view control.

Return Values

Returns the handle to the previous image list, if any, or NULL otherwise.

Remarks

The tree-view control will not destroy the image list specified with this message. Your application must destroy the image list when it is no longer needed.

See Also

TVM_GETIMAGELIST

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SETINDENT

Sets the width of indentation for a tree-view control and redraws the control to reflect the new width. You can send this message explicitly or by using the TreeView_SetIndent macro.

TVM_SETINDENT
    wParam = (WPARAM) (INT) indent;
    lParam = 0;

Parameters

indent
Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Values

No return value.

Remarks

The system-defined minimum indent value is typically five pixels, but it is not fixed. To retrieve the exact value of the minimum indent on a particular system, send a TVM_SETINDENT message with indent set to zero. Then send a TVM_GETINDENT message to retrieve the minimum indent value.

See Also

TreeView_SetIndent

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TVM_SETINSERTMARK

Sets the insertion mark in a tree-view control. You can send this message explicitly or by using the TreeView_SetInsertMark macro.

TVM_SETINSERTMARK
    wParam = (WPARAM)(BOOL) fAfter;
    lParam = (LPARAM)(HTREEITEM) htiInsert;

Parameters

fAfter
BOOL value that specifies if the insertion mark is placed before or after the specified item. If this argument is nonzero, the insertion mark will be placed after the item. If this argument is zero, the insertion mark will be placed before the item.
htiInsert
HTREEITEM that specifies at which item the insertion mark will be placed. If this argument is NULL, the insertion mark is removed.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_SETINSERTMARKCOLOR

Sets the color used to draw the insertion mark for the tree view. You can send this message explicitly or by using the TreeView_SetInsertMarkColor macro.

TVM_SETINSERTMARKCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF)clrInsertMark;

Parameters

clrInsertMark
COLORREF value that contains the new insertion mark color.

Return Values

Returns a COLORREF value that contains the previous insertion mark color.

See Also

TVM_GETINSERTMARKCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_SETITEM

The TVM_SETITEM message sets some or all of a tree-view item's attributes. You can send this message explicitly or by using the TreeView_SetItem macro.

TVM_SETITEM
    wParam = 0;
    lParam = (LPARAM) (const LPTVITEM) pitem;

-- Version 4.71 and later --

    wParam = 0;
    lParam = (LPARAM) (const LPTVITEMEX) pitem;

Parameters

pitem
Pointer to a TVITEM structure that contains the new item attributes. With version 4.71 and later, you can use a TVITEMEX structure instead.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The hItem member of the TVITEM or TVITEMEX structure identifies the item, and the mask member specifies which attributes to set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SETITEMHEIGHT

Sets the height of the tree-view items. You can send this message explicitly or by using the TreeView_SetItemHeight macro.

TVM_SETITEMHEIGHT
    wParam = (WPARAM)(SHORT) cyItem;
    lParam = 0;

Parameters

cyItem
New height of every item in the tree view, in pixels. Heights less than 1 will be set to 1. If this argument is not even and the tree-view control does not have the TVS_NONEVENHEIGHT style, this value will be rounded down to the nearest even value. If this argument is -1, the control will revert to using its default item height.

Return Values

Returns the previous height of the items, in pixels.

Remarks

The tree-view control uses this value for the height of all items. To modify the height of individual items, see the description of the iIntegral member of the TVITEMEX structure.

See Also

TVM_GETITEMHEIGHT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_SETLINECOLOR

The TVM_SETLINECOLOR message sets the current line color.

TVM_SETLINECOLOR
    wParam = 0;
    lParam = (LPARAM) (COLOREF) clr;

Parameters

clr
New line color. Use the CLR_DEFAULT value to restore the system default colors.

Return Values

Returns the previous line color.

Remarks

This message only changes line colors. To change the colors of the '+' and '-' inside the buttons, use the TVM_SETTEXTCOLOR message.

See Also

TVM_GETLINECOLOR

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TVM_SETSCROLLTIME

Sets the maximum scroll time for the tree-view control. You can send this message explicitly or by using the TreeView_SetScrollTime macro.

TVM_SETSCROLLTIME
    wParam = (WPARAM)(UINT)uScrollTime;
    lParam = 0;

Parameters

uScrollTime
New maximum scroll time, in milliseconds.

Return Values

Returns the previous maximum scroll time, in milliseconds.

Remarks

The maximum scroll time is the longest amount of time that a scroll operation can take. Scrolling will be adjusted so that the scroll will take place within the maximum scroll time. A scroll operation may take less time than the maximum.

See Also

TVM_GETSCROLLTIME

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SETTEXTCOLOR

Sets the text color of the control. You can send this message explicitly or by using the TreeView_SetTextColor macro.

TVM_SETTEXTCOLOR
    wParam = 0;
    lParam = (LPARAM)(COLORREF) clrText;

Parameters

clrText
COLORREF value that contains the new text color. If this argument is -1, the control will revert to using the system color for the text color.

Return Values

Returns a COLORREF value that represents the previous text color. If this value is -1, the control was using the system color for the text color.

See Also

TVM_GETTEXTCOLOR

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVM_SETTOOLTIPS

Sets a tree-view control's child ToolTip control. You can send this message explicitly or by using the TreeView_SetToolTips macro.

TVM_SETTOOLTIPS
    wParam = (WPARAM)(HWND) hwndTooltip;
    lParam = 0;

Parameters

hwndTooltip
Handle to a ToolTip control.

Return Values

Returns the handle to ToolTip control previously set for the tree-view control, or NULL if ToolTips were not previously used.

Remarks

When created, tree-view controls automatically create a child ToolTip control. To prevent a tree-view control from using ToolTips, create the control with the TVS_NOTOOLTIPS style.

See Also

TVM_GETTOOLTIPS

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TVM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the TreeView_SetUnicodeFormat macro.

TVM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

TVM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SORTCHILDREN

Sorts the child items of the specified parent item in a tree-view control. You can send this message explicitly or by using the TreeView_SortChildren macro.

TVM_SORTCHILDREN
    wParam = (WPARAM)(BOOL) fRecurse;
    lParam = (LPARAM)(HTREEITEM) hitem;

Parameters

fRecurse
Value that specifies whether the sorting is recursive. Set fRecurse to TRUE to sort all levels of child items below the parent item. Otherwise, only the parent's immediate children are sorted.
hitem
Handle to the parent item whose child items are to be sorted.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVM_SORTCHILDRENCB

Sorts tree-view items using an application-defined callback function that compares the items. You can send this message explicitly or by using the TreeView_SortChildrenCB macro.

TVM_SORTCHILDRENCB
    wParam = (WPARAM)(BOOL) fRecurse;
    lParam = (LPARAM) (LPTVSORTCB) psort;

Parameters

fRecurse
Reserved. Must be zero.
psort
Address of a TVSORTCB structure. The lpfnCompare member is the address of the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TVSORTCB.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_CreateDragImage

Creates a dragging bitmap for the specified item in a tree-view control. The macro also creates an image list for the bitmap and adds the bitmap to the image list. An application can display the image when dragging the item by using the image list functions. You can use this macro or send the TVM_CREATEDRAGIMAGE message explicitly.

HIMAGELIST TreeView_CreateDragImage(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to the item that receives the new dragging bitmap.

Return Values

Returns the handle to the image list to which the dragging bitmap was added if successful, or NULL otherwise.

Remarks

If you create a tree-view control without an associated image list, you cannot use the TreeView_CreateDragImage macro to create the image to display during a drag operation. You must implement your own method of creating a drag cursor.

Your application is responsible for destroying the image list when it is no longer needed.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_DeleteAllItems

Deletes all items from a tree-view control.

BOOL TreeView_DeleteAllItems(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Once an item is deleted from a tree-view control, its HTREEITEM handle is invalid and cannot be used.

The parent window receives a TVN_DELETEITEM notification message when each item is removed.

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message.

You can also delete all items with the TreeView_DeleteItem macro or the TVM_DELETEITEM message by setting lParam to TVI_ROOT.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_DeleteItem

Removes an item and all its children from a tree-view control. You can also send the TVM_DELETEITEM message explicitly.

BOOL TreeView_DeleteItem(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
HTREEITEM handle to the item to delete. If hitem is set to TVI_ROOT, all items are deleted from the tree-view control. You can also use the TreeView_DeleteAllItems macro to delete all items.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Once an item is deleted, its handle is invalid and cannot be used.

The parent window receives a TVN_DELETEITEM notification message when each item is removed.

If the item label is being edited, the edit operation is canceled and the parent window receives the TVN_ENDLABELEDIT notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_EditLabel

Begins in-place editing of the specified item's text, replacing the text of the item with a single-line edit control containing the text. This macro implicitly selects and focuses the specified item. You can use this macro or send the TVM_EDITLABEL message explicitly.

HWND TreeView_EditLabel(
   HWND hwndTV,
   HTREEITEM hitem
   );

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to the item to edit.

Return Values

Returns the handle to the edit control used to edit the item text if successful, or NULL otherwise.

Remarks

This macro sends a TVN_BEGINLABELEDIT notification message to the parent of the tree-view control.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can safely subclass the edit control, but do not destroy it.

The control must have the focus before you call this macro. Focus can be set using the SetFocus function.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_EndEditLabelNow

Ends the editing of a tree-view item's label. You can use this macro or send the TVM_ENDEDITLABELNOW message explicitly.

BOOL TreeView_EndEditLabelNow(
    HWND hwndTV,
    BOOL fCancel
   );

Parameters

hwndTV
Handle to the tree-view control.
fCancel
Variable that indicates whether the editing is canceled without being saved to the label. If this parameter is TRUE, the system cancels editing without saving the changes. Otherwise, the system saves the changes to the label.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

This macro causes the TVN_ENDLABELEDIT notification message to be sent to the parent window of the tree-view control.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_EnsureVisible

Ensures that a tree-view item is visible, expanding the parent item or scrolling the tree-view control, if necessary. You can use this macro or send the TVM_ENSUREVISIBLE message explicitly.

BOOL TreeView_EnsureVisible(
   HWND hwndTV,
   HTREEITEM hitem
   );

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to the item.

Return Values

Returns nonzero if the system scrolled the items in the tree-view control and no items were expanded. Otherwise, the message returns zero.

Remarks

If the TreeView_EnsureVisible macro expands the parent item, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_Expand

The TreeView_Expand macro expands or collapses the list of child items associated with the specified parent item, if any. You can use this macro or send the TVM_EXPAND message explicitly.

BOOL TreeView_Expand(
    HWND hwndTV,
    HTREEITEM hItem,
    UINT flag
);

Parameters

hwndTV
Handle to a tree-view control.
hItem
Handle to the parent item that will be expanded or collapsed.
flag
Action flag. For a list of possible values, see the description of the flag parameter in TVM_EXPAND.

Return Values

Returns nonzero if the operation was successful, or zero otherwise.

Remarks

Expanding a node that is already expanded, or collapsing a node that is already collapsed is considered a successful operation and TVM_EXPAND will return a non-zero value. Attempting to expand or collapse a node that has no children is considered a failure and TVM_EXPAND will return zero.

When an item is first expanded , a TVM_EXPAND message generates TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages and the item's TVIS_EXPANDEDONCE state flag is set. As long as this state flag remains set, subsequent TVM_EXPAND messages will not generate TVN_ITEMEXPANDING or TVN_ITEMEXPANDED notifications. To reset the TVIS_EXPANDEDONCE state flag, send a TVM_EXPAND message with the TVE_COLLAPSE and TVE_COLLAPSERESET flags set.

The expand operation may fail if the owner of the treeview control denies the operation in response to a TVN_ITEMEXPANDING notification.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetBkColor

Retrieves the current background color of the control. You can use this macro or send the TVM_GETBKCOLOR message explicitly.

COLORREF TreeView_GetBkColor(
    HWND hwndTV
);

Parameters

hwndTV
Handle to a tree-view control.

Return Values

Returns a COLORREF value that represents the current background color. If this value is -1, the control is using the system color for the background color.

See Also

TreeView_SetBkColor

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_GetCheckState

Gets the check state of the specified item. You can also use the TVM_GETITEMSTATE message directly.

UINT TreeView_GetCheckState(
    HWND		hwndTV,
    HTREEITEM	hItem
    );

Parameters

hwndTV
Handle to the tree-view control.
hItem
Handle to the item.

Return Values

Returns:
Checked | 1
Unchecked | 0
No Check Box Image | -1

Remarks

A tree-view control can have two image lists. The normal image list stores the selected, nonselected, and overlay images. Check boxes are stored in the state image list and displayed to the left of the corresponding normal image. State images are specified by a one-based index. An index of zero indicates that there is no state image. See Tree-View Image Lists for a discussion of how to handle tree-view images.

If you want to define your own state images, this macro assumes that the checked and unchecked images have the same indexes as the standard image list: 1 for unchecked and 2 for checked.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TreeView_GetChild

Retrieves the first child item of the specified tree-view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CHILD flag.

HTREEITEM TreeView_GetChild(
    HWND hwndTV,
    HTREEITEM hitem,
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to a tree-view item.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent, TreeView_GetPrevSibling

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetCount

Retrieves a count of the items in a tree-view control. You can use this macro or send the TVM_GETCOUNT message explicitly.

UINT TreeView_GetCount(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the count of items.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetDropHilight

Retrieves the tree-view item that is the target of a drag-and-drop operation. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_DROPHILITE flag.

HTREEITEM TreeView_GetDropHilight(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetEditControl

Retrieves the handle to the edit control being used to edit a tree-view item's text. You can use this macro or send the TVM_GETEDITCONTROL message explicitly.

HWND TreeView_GetEditControl(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the handle to the edit control if successful, or NULL otherwise.

Remarks

When label editing begins, an edit control is created but not positioned or displayed. Before it is displayed, the tree-view control sends its parent window a TVN_BEGINLABELEDIT notification message.

To customize label editing, implement a handler for TVN_BEGINLABELEDIT and have it use TreeView_GetEditControl to send a TVM_GETEDITCONTROL message to the tree-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TreeView_GetFirstVisible

Retrieves the first visible item in a tree-view control window. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_FIRSTVISIBLE flag.

HTREEITEM TreeView_GetFirstVisible(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetNextVisible, TreeView_GetPrevVisible, TreeView_GetLastVisible, TVM_GETITEMRECT

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetImageList

Retrieves the handle to the normal or state image list associated with a tree-view control. You can use this macro or send the TVM_GETIMAGELIST message explicitly.

HIMAGELIST TreeView_GetImageList(
    HWND hwndTV,
    INT iImage
);

Parameters

hwndTV
Handle to the tree-view control.
iImage
Type of image list to retrieve. This parameter can be one of the following values:
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree-view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.

Return Values

Returns an HIMAGELIST handle to the specified image list.

See Also

TreeView_SetImageList

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetIndent

Retrieves the amount, in pixels, that child items are indented relative to their parent items. You can use this macro or send the TVM_GETINDENT message explicitly.

UINT TreeView_GetIndent(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the amount of indentation.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetInsertMarkColor

Retrieves the color used to draw the insertion mark for the tree view. You can use this macro or send the TVM_GETINSERTMARKCOLOR message explicitly.

COLORREF TreeView_GetInsertMarkColor(
     HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns a COLORREF value that contains the current insertion mark color.

See Also

TreeView_SetInsertMarkColor

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_GetISearchString

Retrieves the incremental search string for a tree-view control. The tree-view control uses the incremental search string to select an item based on characters typed by the user. You can use this macro or send the TVM_GETISEARCHSTRING message explicitly.

BOOL TreeView_GetISearchString(
   HWND hwndTV,
   LPTSTR lpsz
);

Parameters

hwndTV
Handle to the tree-view control.
lpsz
Address of the buffer that receives the incremental search string.

Return Values

Returns the number of characters in the incremental search string.

Remarks

If the tree-view control is not in incremental search mode, the return value is zero.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetItem

Retrieves some or all of a tree-view item's attributes. You can use this macro or send the TVM_GETITEM message explicitly.

BOOL TreeView_GetItem(
   HWND hwndTV,
   LPTVITEM pitem
   );

-- Version 4.71 or later --

BOOL TreeView_GetItem(
   HWND hwndTV,
   LPTVITEMEX pitem
   );

Parameters

hwndTV
Handle to the tree-view control.
pitem
Pointer to a TVITEM structure that specifies the information to retrieve and receives information about the item. With version 4.71 and later, you can use a TVITEMEX structure instead.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the TVM_GETITEM message is sent, the hItem member of the TVITEM or TVITEMEX structure identifies the item to retrieve information about, and the mask member specifies the attributes to retrieve.

If the TVIF_TEXT flag is set in the mask member of the TVITEM or TVITEMEX structure, the pszText member must point to a valid buffer and the cchTextMax member must be set to the number of characters in that buffer. The returned text will not necessarily be stored in the original buffer passed by the application. It is possible that pszText will point to text in a new buffer rather than place it in the old buffer.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TreeView_GetItemHeight

Retrieves the current height of the tree-view items. You can use this macro or send the TVM_GETITEMHEIGHT message explicitly.

int TreeView_GetItemHeight(
    HWND hwndTV
);

Parameters

hwndTV
Handle to a tree-view control.

Return Values

Returns the height of the items, in pixels.

See Also

TreeView_SetItemHeight

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_GetItemRect

Retrieves the bounding rectangle for a tree-view item and indicates whether the item is visible. You can use this macro or send the TVM_GETITEMRECT message explicitly.

BOOL TreeView_GetItemRect(
   HWND hwndTV,
   HTREEITEM hitem,
   LPRECT prc,
   BOOL fItemRect
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to the tree-view item.
prc
Address of a RECT structure that receives the bounding rectangle. The coordinates are relative to the upper-left corner of the tree-view control.
fItemRect
Value specifying the portion of the item for which to retrieve the bounding rectangle. If this parameter is TRUE, the bounding rectangle includes only the text of the item. Otherwise, it includes the entire line that the item occupies in the tree-view control.

Return Values

If the item is visible and the bounding rectangle is successfully retrieved, the return value is TRUE. Otherwise, the TVM_GETITEMRECT message returns FALSE and does not retrieve the bounding rectangle.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetItemState

Retrieves some or all of a tree-view item's state attributes. You can use this macro or send the TVM_GETITEMSTATE message explicitly.

UINT TreeView_GetItemState(
    HWND		hwndTV,
    HTREEITEM	hItem,
    UINT		stateMask
   );

Parameters

hwndTV
A handle to the tree-view control.
hItem
A handle to the item.
stateMask
A mask used to specify the states to query for. It is equivalent to the stateMask member of TVITEMEX.

Return Values

Returns a UINT value that is equivalent to the state member of TVITEMEX. The state bits that are both true and were specified in StateMask will be set.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TreeView_GetLastVisible

Retrieves the last expanded item in a tree-view control. This does not retrieve the last item visible in the tree-view window. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_LASTVISIBLE flag.

HTREEITEM TreeView_GetLastVisible(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetFirstVisible, TreeView_GetNextVisible, TreeView_GetPrevVisible, TVM_GETITEMRECT

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_GetLineColor

Gets the current line color. You can also use the TVM_GETLINECOLOR message directly.

COLOREF TreeView_GetLineColor(
    HWND hwndTV
    );

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the current line color, or the CLR_DEFAULT value if none has been specified.

Remarks

This message only retrieves line colors. To retrieve the colors of the plus sign (+) and minus sign (-) inside the buttons, use the TreeView_GetTextColor macro.

See Also

TVM_GETLINECOLOR

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TreeView_GetNextItem

Retrieves the tree-view item that bears the specified relationship to a specified item. You can use this macro, use one of the TreeView_Get macros described below, or send the TVM_GETNEXTITEM message explicitly.

HTREEITEM TreeView_GetNextItem(
    HWND hwndTV,
    HTREEITEM hitem,
    UINT flag
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item.
flag
Flag specifying the item to retrieve. This parameter can be one of the following values:
TVGN_CARET | Retrieves the currently selected item. You can use the TreeView_GetSelection macro to send this message.
TVGN_CHILD | Retrieves the first child item of the item specified by the hitem parameter. You can use the TreeView_GetChild macro to send this message.
TVGN_DROPHILITE | Retrieves the item that is the target of a drag-and-drop operation. You can use the TreeView_GetDropHilight macro to send this message.
TVGN_FIRSTVISIBLE | Retrieves the first visible item. You can use the TreeView_GetFirstVisible macro to send this message.
TVGN_NEXT | Retrieves the next sibling item. You can use the TreeView_GetNextSibling macro to send this message.
TVGN_NEXTVISIBLE | Retrieves the next visible item that follows the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetNextVisible macro to send this message.
TVGN_PARENT | Retrieves the parent of the specified item. You can use the TreeView_GetParent macro to send this message.
TVGN_PREVIOUS | Retrieves the previous sibling item. You can use the TreeView_GetPrevSibling macro to send this message.
TVGN_PREVIOUSVISIBLE | Retrieves the first visible item that precedes the specified item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible. You can use the TreeView_GetPrevVisible macro to send this message.
TVGN_ROOT | Retrieves the topmost or very first item of the tree-view control. You can use the TreeView_GetRoot macro to send this message.

Return Values

Returns the handle to the item if successful. For most cases, the message returns a NULL value to indicate an error. See the Remarks section for details

Remarks

This macro will return NULL if the item being retrieved is the root node of the tree. For example, if you use this macro with with the TVGN_PARENT flag on a first-level child of the tree view's root node, the macro will return NULL.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetNextSibling

Retrieves the next sibling item of a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXT flag.

HTREEITEM TreeView_GetNextSibling(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetParent, TreeView_GetPrevSibling

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetNextVisible

Retrieves the next visible item that follows a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_NEXTVISIBLE flag.

HTREEITEM TreeView_GetNextVisible(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetPrevVisible

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetParent

Retrieves the parent item of the specified tree-view item. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PARENT flag.

HTREEITEM TreeView_GetParent(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item.

Return Values

Returns the handle to the item if successful. For most cases, the message returns a NULL value to indicate an error. See the Remarks section for details

Remarks

This macro will return NULL if the parent of the specified item is the root node of the tree.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetPrevSibling

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetPrevSibling

Retrieves the previous sibling item of a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUS flag.

HTREEITEM TreeView_GetPrevSibling(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetChild, TreeView_GetNextItem, TreeView_GetNextSibling, TreeView_GetParent

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetPrevVisible

Retrieves the first visible item that precedes a specified item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_PREVIOUSVISIBLE flag.

HTREEITEM TreeView_GetPrevVisible(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item. The specified item must be visible. Use the TVM_GETITEMRECT message to determine whether an item is visible.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetFirstVisible, TreeView_GetNextItem, TreeView_GetNextVisible

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetRoot

Retrieves the topmost or very first item of the tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_ROOT flag.

HTREEITEM TreeView_GetRoot(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetNextItem

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetScrollTime

Retrieves the maximum scroll time for the tree-view control. You can use this macro or send the TVM_GETSCROLLTIME message explicitly.

UINT TreeView_GetScrollTime(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the maximum scroll time, in milliseconds.

Remarks

The maximum scroll time is the longest amount of time that a scroll operation can take. Scrolling will be adjusted so that the scroll will take place within the maximum scroll time. A scroll operation may take less time than the maximum.

See Also

TreeView_SetScrollTime

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetSelection

Retrieves the currently selected item in a tree-view control. You can use this macro, or you can explicitly send the TVM_GETNEXTITEM message with the TVGN_CARET flag.

HTREEITEM TreeView_GetSelection(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the handle to the item if successful, or NULL otherwise.

See Also

TreeView_GetNextItem

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetTextColor

Retrieves the current text color of the control. You can use this macro or send the TVM_GETTEXTCOLOR message explicitly.

COLORREF TreeView_GetTextColor(
    HWND hwndTV
);

Parameters

hwndTV
Handle to a tree-view control.

Return Values

Returns a COLORREF value that represents the current text color. If this value is -1, the control is using the system color for the text color.

See Also

TreeView_SetTextColor

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_GetToolTips

Retrieves the handle to the child ToolTip control used by a tree-view control. You can use this macro or send the TVM_GETTOOLTIPS message explicitly.

HWND TreeView_GetToolTips(
    HWND hwndTV
);

Parameters

hwndTV
Handle to a tree-view control.

Return Values

Returns the handle to the child ToolTip control, or NULL if the control is not using ToolTips.

Remarks

When created, tree-view controls automatically create a child ToolTip control. To prevent a tree-view control from using ToolTips, create the control with the TVS_NOTOOLTIPS style.

See Also

TreeView_SetToolTips

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TreeView_GetUnicodeFormat

Retrieves the UNICODE character format flag for the control. You can use this macro or send the TVM_GETUNICODEFORMAT message explicitly.

BOOL TreeView_GetUnicodeFormat(
    HWND hwnd
);

Parameters

hwnd
Handle to the control.

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

See Also

TreeView_SetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_GetVisibleCount

Obtains the number of items that can be fully visible in the client window of a tree-view control. You can use this macro or send the TVM_GETVISIBLECOUNT message explicitly.

UINT TreeView_GetVisibleCount(
    HWND hwndTV
);

Parameters

hwndTV
Handle to the tree-view control.

Return Values

Returns the number of items that can be fully visible in the client window of the tree-view control.

Remarks

The number of items that can be fully visible may be greater than the number of items in the control. The control calculates this value by dividing the height of the client window by the height of an item.

Note that the return value is the number of items that can be fully visible. If you can see all of 20 items and part of one more item, the return value is 20.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_HitTest

Determines the location of the specified point relative to the client area of a tree-view control. You can use this macro or send the TVM_HITTEST message explicitly.

HTREEITEM TreeView_HitTest(
    HWND hwndTV,
    LPTVHITTESTINFO lpht
);

Parameters

hwndTV
Handle to the tree-view control.
lpht
Address of a TVHITTESTINFO structure. When the message is sent, the pt member specifies the coordinates of the point to test. When the message returns, the hItem member is the handle to the item at the specified point or NULL if no item occupies the point. Also, when the message returns, the flags member is a hit test value that indicates the location of the specified point. For a list of hit test values, see the description of the TVHITTESTINFO structure.

Return Values

Returns the handle to the tree-view item that occupies the specified point, or NULL if no item occupies the point.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_InsertItem

Inserts a new item in a tree-view control. You can use this macro or send the TVM_INSERTITEM message explicitly.

HTREEITEM TreeView_InsertItem(
    HWND hwndTV,
    LPTVINSERTSTRUCT lpis
);

Parameters

hwndTV
Handle to the tree-view control.
lpis
Address of a TVINSERTSTRUCT structure that specifies the attributes of the tree-view item.

Return Values

Returns the handle to the new item if successful, or NULL otherwise.

See Also

TVN_ENDLABELEDIT

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_Select

Selects the specified tree-view item, scrolls the item into view, or redraws the item in the style used to indicate the target of a drag-and-drop operation. You can use this macro or the TreeView_SelectItem, TreeView_SelectSetFirstVisible, or TreeView_SelectDropTarget macros, or you can send the TVM_SELECTITEM message explicitly.

BOOL TreeView_Select(
    HWND hwndTV,
    HTREEITEM hitem,
    UINT flag
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.
flag
Action flag. This parameter can be one of the following values:
TVGN_CARET | Sets the selection to the given item. The control's parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages.
TVGN_DROPHILITE | Redraws the given item in the style used to indicate the target of a drag-and-drop operation.
TVGN_FIRSTVISIBLE | Ensures that the specified item is visible, and, if possible, displays it at the top of the control's window. Tree-view controls display as many items as will fit in the window. If the specified item is near the bottom of the control's hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SelectDropTarget

Redraws a specified tree-view control item in the style used to indicate the target of a drag-and-drop operation. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

BOOL TreeView_SelectDropTarget(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectDropTarget macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_DROPHILITE value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SelectItem

Selects the specified tree-view item. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

BOOL TreeView_SelectItem(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When you call the TreeView_SelectItem macro, the control's parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. Also, if the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectItem macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_CARET value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SelectSetFirstVisible

Scrolls the tree-view control vertically to ensure that the specified item is visible. If possible, the specified item becomes the first visible item at the top of the control's window. You can use this macro or the TreeView_Select macro, or you can send the TVM_SELECTITEM message explicitly.

BOOL TreeView_SelectSetFirstVisible(
    HWND hwndTV,
    HTREEITEM hitem
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to an item. If the hitem parameter is NULL, the control is set to have no selected item.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Tree-view controls display as many items as will fit in the window. If the specified item is near the bottom of the control's hierarchy of items, it might not become the first visible item, depending on how many items fit in the window.

If the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

Using the TreeView_SelectSetFirstVisible macro is equivalent to sending the TVM_SELECTITEM message with its flag parameter set to the TVGN_FIRSTVISIBLE value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SetBkColor

Sets the background color of the control. You can use this macro or send the TVM_SETBKCOLOR message explicitly.

COLORREF TreeView_SetBkColor(
    HWND hwndTV
    COLORREF clrBk;
);

Parameters

hwndTV
Handle to a tree-view control.
clrBk
COLORREF value that contains the new background color. If this argument is -1, the control will revert to using the system color for the background color.

Return Values

Returns a COLORREF value that represents the previous background color. If this value is -1, the control was using the system color for the background color.

See Also

TreeView_GetBkColor

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_SetCheckState

Sets the item's state image to "checked" or "unchecked." You can also use the TVM_SETITEM message directly.

UINT TreeView_SetCheckState(
    HWND		hwndTV,
    HTREEITEM	hItem,
    BOOL		fCheck
);

Parameters

hwndTV
Handle to the tree-view control.
hItem
Handle to the item.
fCheck
Value that indicates which state image is displayed. Set fCheck to TRUE to display the checked state image or FALSE to display the unchecked image.

Return Values

The return value is not used.

Remarks

A tree-view control can have two image lists. The normal image list stores the selected, nonselected, and overlay images. Check boxes are stored in the state image list and displayed to the left of the corresponding normal image. State images are specified by a one-based index. An index of zero indicates that there is no state image. See Tree-View Image Lists for a discussion of how to handle tree-view images.

If you want to define your own state images, this macro assumes that the checked and unchecked images have the same indexes as the standard image list: 1 for unchecked and 2 for checked.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TreeView_SetImageList

Sets the normal or state image list for a tree-view control and redraws the control using the new images. You can use this macro or send the TVM_SETIMAGELIST message explicitly.

HIMAGELIST TreeView_SetImageList(
    HWND hwndTV,
    HIMAGELIST himl,
    INT iImage
   );

Parameters

hwndTV
Handle to the tree-view control.
himl
The HIMAGELIST handle to the image list. If himl is NULL, the message removes the specified image list from the tree-view control.
iImage
Type of image list to set. This parameter can be one of the following values:
TVSIL_NORMAL | Indicates the normal image list, which contains selected, nonselected, and overlay images for the items of a tree-view control.
TVSIL_STATE | Indicates the state image list. You can use state images to indicate application-defined item states. A state image is displayed to the left of an item's selected or nonselected image.

Return Values

Returns the HIMAGELIST handle to the previous image list, if any, or NULL otherwise.

Remarks

The tree-view control will not destroy the image list specified with this message. Your application must destroy the image list when it is no longer needed.

See Also

TreeView_GetImageList, TVM_GETIMAGELIST

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SetIndent

Sets the width of indentation for a tree-view control and redraws the control to reflect the new width. You can use this macro or send the TVM_SETINDENT message explicitly.

BOOL TreeView_SetIndent(
    HWND hwndTV,
    INT indent
   );

Parameters

hwndTV
Handle to the tree-view control.
indent
Width, in pixels, of the indentation. If this parameter is less than the system-defined minimum width, the new width is set to the system-defined minimum.

Return Values

Although this macro is typed as a BOOL, it always returns zero.

Remarks

The system-defined minimum indent value is typically five pixels, but it is not fixed. To retrieve the exact value of the minimum indent on a particular system, use the TreeView_SetIndent macro with indent set to zero. Then use the TreeView_GetIndent macro to retrieve the minimum indent value.

See Also

TVM_SETINDENT

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TreeView_SetInsertMark

Sets the insertion mark in a tree-view control. You can use this macro or send the TVM_SETINSERTMARK message explicitly.

BOOL TreeView_SetInsertMark(
    HWND hwndTV,
    HTREEITEM htiInsert,
    BOOL fAfter
);

Parameters

hwndTV
Handle to a tree-view control.
htiInsert
HTREEITEM that specifies at which item the insertion mark will be placed. If this argument is NULL, the insertion mark is removed.
fAfter
BOOL value that specifies if the insertion mark is placed before or after the specified item. If this argument is nonzero, the insertion mark will be placed after the item. If this argument is zero, the insertion mark will be placed before the item.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_SetInsertMarkColor

Sets the color used to draw the insertion mark for the tree view. You can use this macro or send the TVM_SETINSERTMARKCOLOR message explicitly.

COLORREF TreeView_SetInsertMarkColor(
    HWND hwndTV,
    COLORREF clrInsertMark
);

Parameters

hwndTV
Handle to a tree-view control.
clrInsertMark
COLORREF value that contains the new insertion mark color.

Return Values

Returns a COLORREF value that contains the previous insertion mark color.

See Also

TreeView_GetInsertMarkColor

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_SetItem

The TreeView_SetItem macro sets some or all of a tree-view item's attributes. You can use this macro or send the TVM_SETITEM message explicitly.

BOOL TreeView_SetItem(
    HWND hwndTV,
    LPTVITEM pitem
    );

-- Version 4.71 or later --

BOOL TreeView_SetItem(
    HWND hwndTV,
    LPTVITEMEX pitem
    );

Parameters

hwndTV
Handle to the tree-view control.
pitem
Address of a TVITEM structure that contains the new item attributes. With version 4.71 and later, you can instead use a TVITEMEX structure.

Return Values

Returns a non-zero value if successful, or zero otherwise.

Remarks

The hItem member of the TVITEM or TVITEMEX structure identifies the item, and the mask member specifies which attributes to set.

See Also

TreeView_GetItem

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SetItemHeight

Sets the height of the tree-view items. You can use this macro or send the TVM_SETITEMHEIGHT message explicitly.

int TreeView_SetItemHeight(
    HWND hwndTV,
    SHORT cyItem
);

Parameters

hwndTV
Handle to a tree-view control.
cyItem
New height of every item in the tree view, in pixels. Heights less than 1 will be set to 1. If this argument is not even, it will be rounded down to the nearest even value. If this argument is -1, the control will revert to using its default item height.

Return Values

Returns the previous height of the items, in pixels.

Remarks

The tree-view control uses this value for the height of all items. To modify the height of individual items, see the description of the iIntegral member of the TVITEMEX structure.

See Also

TreeView_GetItemHeight

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_SetItemState

Sets a tree-view item's state attributes. You can use this macro or send the TVM_SETITEM message explicitly.

UINT TreeView_SetItemState(
    HWND		hwndTV,
    HTREEITEM	hItem,
    UINT		state,
    UINT		stateMask
   );

Parameters

hwndTV
Handle to the tree-view control.
hItem
Handle to the item.
state
Value that is equivalent to the state member of TVITEMEX.
stateMask
Mask used to select the states to be set. It is equivalent to the stateMask member of TVITEMEX.

Return Values

The return value is not used.

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TreeView_SetLineColor

Sets the current line color. You can also use the TVM_SETLINECOLOR message directly.

COLOREF TreeView_SetLineColor(
    HWND hwndTV,
    COLOREF clrLine
    );

Parameters

hwndTV
Handle to the tree-view control.
clrLine
New line color. Use the CLR_DEFAULT value to restore the system default colors.

Return Values

Returns the previous line color.

Remarks

This message only changes line colors. To change the colors of the plus sign (+) and minus sign (-) inside the buttons, use the TreeView_SetTextColor macro.

See Also

TVM_SETLINECOLOR

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


TreeView_SetScrollTime

Sets the maximum scroll time for the tree-view control. You can use this macro or send the TVM_SETSCROLLTIME message explicitly.

UINT TreeView_SetScrollTime(
    HWND hwndTV,
    UINT uMaxScrollTime
);

Parameters

hwndTV
Handle to a tree-view control.
uMaxScrollTime
New maximum scroll time, in milliseconds. If this value is less than 100, it will be rounded up to 100.

Return Values

Returns the previous scroll time, in milliseconds.

Remarks

The maximum scroll time is the longest amount of time that a scroll operation can take. Scrolling will be adjusted so that the scroll will take place within the maximum scroll time. A scroll operation may take less time than the maximum.

See Also

TVM_GETSCROLLTIME

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SetTextColor

Sets the text color of the control. You can use this macro or send the TVM_SETTEXTCOLOR message explicitly.

COLORREF TreeView_SetTextColor(
    HWND hwndTV
    COLORREF clrText;
);

Parameters

hwndTV
Handle to a tree-view control.
clrText
COLORREF value that contains the new text color. If this argument is -1, the control will revert to using the system color for the text color.

Return Values

Returns a COLORREF value that represents the previous text color. If this value is -1, the control was using the system color for the text color.

See Also

TreeView_GetTextColor

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TreeView_SetToolTips

Sets a tree-view control's child ToolTip control. You can use this macro or send the TVM_SETTOOLTIPS message explicitly.

HWND TreeView_SetToolTips(
    HWND hwndTV,
    HWND hwndTooltip
);

Parameters

hwndTV
Handle to a tree-view control.
hwndTooltip
Handle to a ToolTip control.

Return Values

Returns the handle to ToolTip control previously set for the tree-view control, or NULL if ToolTips were not previously used.

Remarks

When created, tree-view controls automatically create a child ToolTip control. To prevent a tree-view control from using ToolTips, create the control with the TVS_NOTOOLTIPS style.

See Also

TreeView_GetToolTips

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


TreeView_SetUnicodeFormat

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the TVM_SETUNICODEFORMAT message explicitly.

BOOL TreeView_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Parameters

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

See Also

TreeView_GetUnicodeFormat

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SortChildren

Sorts the child items of the specified parent item in a tree-view control. You can use this macro or send the TVM_SORTCHILDREN message explicitly.

BOOL TreeView_SortChildren(
    HWND hwndTV,
    HTREEITEM hitem,
    BOOL fRecurse
);

Parameters

hwndTV
Handle to the tree-view control.
hitem
Handle to the parent item whose child items are to be sorted.
fRecurse
Value that specifies whether the sorting is recursive. Set fRecurse to TRUE to sort all levels of child items below the parent item. Otherwise, only the parent's immediate children are sorted.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TreeView_SortChildrenCB

Sorts tree-view items using an application-defined callback function that compares the items. You can use this macro or send the TVM_SORTCHILDRENCB message explicitly.

BOOL TreeView_SortChildrenCB(
    HWND hwndTV,
    LPTVSORTCB psort,
    BOOL fRecurse
);

Parameters

hwndTV
Handle to the tree-view control.
psort
Address of a TVSORTCB structure. The lpfnCompare member is the address of the application-defined callback function, which is called during the sort operation each time the relative order of two list items needs to be compared. For more information about the callback function, see the description of TVSORTCB.
fRecurse
Reserved. Must be zero.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CLICK (tree view)

Notifies a tree-view control's parent window that the user has clicked the left mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

NM_CLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to prevent the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_CUSTOMDRAW (tree view)

Sent by a tree-view control to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMTVCUSTOMDRAW) lParam;

Parameters

lpNMCustomDraw
Address of an NMTVCUSTOMDRAW structure that contains and receives information about the drawing operation. The dwItemSpec member of the nmcd member of this structure contains the handle of the item being drawn. The lItemlParam member of the nmcd member of this structure contains the lParam of the item being drawn.

Return Values

The value your application can return depends on the current drawing stage. The dwDrawStage member of the associated NMCUSTOMDRAW structure holds a value that specifies the drawing stage. You must return one of the following values.

When dwDrawStage equals CDDS_PREPAINT:

CDRF_DODEFAULT | The control draws itself. It does not send any additional NM_CUSTOMDRAW messages for this paint cycle.
CDRF_NOTIFYITEMDRAW | The control notifies the parent of any item-related drawing operations. It sends NM_CUSTOMDRAW notification messages before and after drawing items.
CDRF_NOTIFYITEMERASE | The control notifies the parent when an item will be erased. It sends NM_CUSTOMDRAW notification messages before and after erasing items.
CDRF_NOTIFYPOSTERASE | The control notifies the parent after erasing an item.
CDRF_NOTIFYPOSTPAINT | The control notifies the parent after painting an item.
CDRF_NOTIFYSUBITEMDRAW | Version 4.71. The control notifies the parent when a list-view subitem is being drawn.

When dwDrawStage equals CDDS_ITEMPREPAINT:

CDRF_NEWFONT | Your application specified a new font for the item; the control will use the new font. For more information on changing fonts, see Changing fonts and colors.
CDRF_SKIPDEFAULT | Your application drew the item manually. The control will not draw the item.

Remarks

Version 5.80. If you change the font by returning CDRF_NEWFONT, the tree-view control might display clipped text. This behavior is necessary for backward compatibility with earlier versions of the common controls. If you want to change the font of a tree-view control, you will get better results if you send a CCM_SETVERSION message with the wParam value set to 5 before adding any items to the control.

SeeAlso

Using Custom Draw

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NM_DBLCLK (tree view)

Notifies a tree-view control's parent window that the user has double-clicked the left mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

NM_DBLCLK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to prevent the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_KILLFOCUS (tree view)

Notifies a tree-view control's parent window that the control has lost the input focus. This notification is sent in the form of a WM_NOTIFY message.

NM_KILLFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RCLICK (tree view)

Notifies a tree-view control's parent window that the user has clicked the right mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

NM_RCLICK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to prevent the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RDBLCLK (tree view)

Notifies a tree-view control's parent window that the user has double-clicked the right mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

NM_RDBLCLK
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to prevent the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RETURN (tree view)

Notifies a tree-view control's parent window that the control has the input focus and that the user has pressed the ENTER key. This notification is sent in the form of a WM_NOTIFY message.

NM_RETURN
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

Return nonzero to prevent the default processing, or zero to allow the default processing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_SETCURSOR (tree view)

Notifies a tree-view control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.

NM_SETCURSOR
    lpnmm = (LPNMMOUSE) lParam;

Parameters

lpnmm
Address of an NMMOUSE structure that contains additional information about this notification message.

Return Values

Return zero to enable the control to set the cursor or nonzero to prevent the control from setting the cursor.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NM_SETFOCUS (tree view)

Notifies a tree-view control's parent window that the control has received the input focus. This notification is sent in the form of a WM_NOTIFY message.

NM_SETFOCUS
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_BEGINDRAG

Notifies a tree-view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated. This notification message is sent in the form of a WM_NOTIFY message.

TVN_BEGINDRAG
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the item being dragged in the hItem, state, and lParam members. The ptDrag member specifies the current screen coordinates of the mouse.

Return Values

The return value is ignored.

Remarks

A tree-view control that has the TVS_DISABLEDRAGDROP style does not send this notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_BEGINLABELEDIT

Notifies a tree-view control's parent window about the start of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_BEGINLABELEDIT
    ptvdi = (LPNMTVDISPINFO) lParam

Parameters

ptvdi
Pointer to an NMTVDISPINFO structure. The item member is a TVITEM structure that contains valid information about the item being edited in the hItem, state, lParam, and pszText members.

Return Values

Returns TRUE to cancel label editing.

Remarks

When label editing begins, an edit control is created but not positioned or displayed. Before it is displayed, the tree-view control sends its parent window a TVN_BEGINLABELEDIT notification message.

To customize label editing, implement a handler for TVN_BEGINLABELEDIT and have it send a TVM_GETEDITCONTROL message to the tree-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

When the user cancels or completes the editing, the parent window receives a TVN_ENDLABELEDIT notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TVN_BEGINRDRAG

Notifies a tree-view control's parent window about the initiation of a drag-and-drop operation involving the right mouse button. This notification message is sent in the form of a WM_NOTIFY message.

TVN_BEGINRDRAG
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information in the hItem, state, and lParam members about the item to be dragged. The ptDrag member specifies the current screen coordinates of the mouse.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_DELETEITEM

Notifies a tree-view control's parent window that an item is being deleted. This notification message is sent in the form of a WM_NOTIFY message.

TVN_DELETEITEM
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemOld member is a TVITEM structure whose hItem and lParam members contain valid information about the item being deleted.

Return Values

The return value is ignored.

Remarks

If the lParam member of the TVITEM structure points to memory allocated by your application, you can free it when you receive the TVN_DELETEITEM notification message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_ENDLABELEDIT

Notifies a tree-view control's parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ENDLABELEDIT
    ptvdi = (LPNMTVDISPINFO) lParam

Parameters

ptvdi
Address of an NMTVDISPINFOstructure. The item member of this structure is a TVITEM structure whose hItem, lParam, and pszText members contain valid information about the item that was edited.
If label editing was canceled, the pszText member of the TVITEM structure is NULL; otherwise, pszText is the address of the edited text.

Return Values

If the pszText member is non-NULL, return TRUE to set the item's label to the edited text. Return FALSE to reject the edited text and revert to the original label.

Remarks

If the pszText member is NULL, the return value is ignored.

If you specified the LPSTR_TEXTCALLBACK value for this item and the pszText member is non-NULL, your TVN_ENDLABELEDIT handler should copy the text from pszText to your local storage.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_GETDISPINFO

Requests that a tree-view control's parent window provide information needed to display or sort an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_GETDISPINFO
    lptvdi = (LPNMTVDISPINFO) lParam

Parameters

lptvdi
Address of an NMTVDISPINFO structure. The item member is a TVITEM structure whose mask, hItem, state, and lParam members specify the type of information required. You must fill the members of the structure with the appropriate information.

Return Values

The return value is ignored.

Remarks

This notification is sent under the following circumstances:

  • If the pszText member of the item's TVITEM structure is the LPSTR_TEXTCALLBACK value, the control sends this notification to retrieve the item's text. In this case, the mask member of lptvdi will have the TVIF_TEXT flag set.
  • If the iImage or iSelectedImage member of the item's TVITEM structure is the I_IMAGECALLBACK value, the control sends this notification to retrieve the index of an item's icons in the control's image list. In this case, if the item is selected, the mask member of lptvdi will have the TVIF_SELECTEDIMAGE flag set. If the item is not selected, the mask member of lptvdi will have the TVIF_IMAGE flag set.
  • If the cChildren member of the item's TVITEM structure is the I_CHILDRENCALLBACK value, the control sends this notification to retrieve a value that indicates whether the item has child items. In this case, the mask member of lptvdi will have the TVIF_CHILDREN flag set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_GETINFOTIP

Sent by a tree-view control that has the TVS_INFOTIP style. This notification is sent when the control is requesting additional text information to be displayed in a ToolTip. The notification is sent in the form of a WM_NOTIFY message.

TVN_GETINFOTIP
    lpGetInfoTip = (LPNMTVGETINFOTIP)lParam;

Parameters

lpGetInfoTip
Address of an NMTVGETINFOTIP structure that contains information about this notification.

Return Values

The control ignores the return value for this notification.

Remarks

This notification is only sent by tree-view controls that have the TVS_INFOTIP style.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVN_ITEMEXPANDED

Notifies a tree-view control's parent window that a parent item's list of child items has expanded or collapsed. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ITEMEXPANDED
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list expanded or collapsed. For a list of possible values, see the description of the TVM_EXPAND message.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_ITEMEXPANDING

Notifies a tree-view control's parent window that a parent item's list of child items is about to expand or collapse. This notification message is sent in the form of a WM_NOTIFY message.

TVN_ITEMEXPANDING
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list is to expand or collapse. For a list of possible values, see the description of the TVM_EXPAND message.

Return Values

Returns TRUE to prevent the list from expanding or collapsing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_KEYDOWN

Notifies a tree-view control's parent window that the user pressed a key and the tree-view control has the input focus. This notification message is sent in the form of a WM_NOTIFY message.

TVN_KEYDOWN
    ptvkd = (LPNMTVKEYDOWN) lParam

Parameters

ptvkd
Address of an NMTVKEYDOWN structure. The wVKey member specifies the virtual key code.

Return Values

If the wVKey member of ptvkd is a character key code, the character will be used as part of an incremental search. Return nonzero to exclude the character from the incremental search, or zero to include the character in the search. For all other keys, the return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_SELCHANGED

Notifies a tree-view control's parent window that the selection has changed from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

TVN_SELCHANGED
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemOld and itemNew members of the NMTREEVIEW structure are TVITEM structures that contain information about the previously selected item and the newly selected item. Only the mask, hItem, state, and lParam members of these structures are valid. The stateMask members of the TVITEM structures specified by itemOld and itemNew are undefined on input.
The action member of the NMTREEVIEW structure indicates the type of action that caused the selection to change. It can be one of the following values:
TVC_BYKEYBOARD | By a keystroke.
TVC_BYMOUSE | By a mouse click.
TVC_UNKNOWN | Unknown.

Return Values

The return value is ignored.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_SELCHANGING

Notifies a tree-view control's parent window that the selection is about to change from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

TVN_SELCHANGING
    pnmtv = (LPNMTREEVIEW) lParam

Parameters

pnmtv
Address of an NMTREEVIEW structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

Return Values

Returns TRUE to prevent the selection from changing.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_SETDISPINFO

Notifies a tree-view control's parent window that it must update the information it maintains about an item. This notification message is sent in the form of a WM_NOTIFY message.

TVN_SETDISPINFO
    lptvdi = (LPNMTVDISPINFO) lParam

Parameters

lptvdi
Address of an NMTVDISPINFO structure that describes the item being updated. The hItem member of the TVITEM structure specifies the item being updated, and the mask member specifies which attributes of the item are being updated.

Return Values

The return value is ignored.

Remarks

If the pszText member of the item's TVITEM structure is the LPSTR_TEXTCALLBACK value, the control sends this notification to set the item's text. In this case, the mask member of lptvdi will have the TVIF_TEXT flag set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVN_SINGLEEXPAND

Sent by a tree-view control with the TVS_SINGLEEXPAND style when the user opens or closes a tree item using a single click of the mouse. This notification is sent in the form of a WM_NOTIFY message.

TVN_SINGLEEXPAND
    lpnmtv = (LPNMTREEVIEW)lParam;

Parameters

lpnmtv
Address of an NMTREEVIEW structure that contains information about this notification.

Return Values

Return TVNRET_DEFAULT to allow the default behavior to occur. To modify the default behavior, return:

TVNRET_SKIPOLD | Skip default processing of the item being unselected.
TVNRET_SKIPNEW | Skip default processing of the item being selected.

To skip default processing of selected and unselected items, return both TVNRET_SKIPOLD and TVNRET_SKIPNEW by combining them with a logical OR.

Remarks

This notification is only sent by tree-view controls that have the TVS_SINGLEEXPAND style.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTREEVIEW

Contains information about a tree-view notification message. This structure is identical to the NM_TREEVIEW structure, but it has been renamed to follow current naming conventions.

typedef struct tagNMTREEVIEW {
    NMHDR hdr;
    UINT action;
    TVITEM itemOld;
    TVITEM itemNew;
    POINT ptDrag;
} NMTREEVIEW, FAR *LPNMTREEVIEW;

Members

hdr
NMHDR structure that contains information about this notification message.
action
Notification-specific action flag.
itemOld
TVITEM structure that contains information about the old item state. This member is zero for notification messages that do not use it.
itemNew
TVITEM structure that contains information about the new item state. This member is zero for notification messages that do not use it.
ptDrag
POINT structure that contains the client coordinates of the mouse at the time the event occurred that caused the notification message to be sent.

See Also

WM_NOTIFY

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMTVCUSTOMDRAW

Contains information specific to an NM_CUSTOMDRAW notification message sent by a tree-view control.

typedef struct tagNMTVCUSTOMDRAW {
    NMCUSTOMDRAW nmcd;
    COLORREF clrText;
    COLORREF clrTextBk;
#if (_WIN32_IE >= 0x0400)
    int iLevel;
#endif
} NMTVCUSTOMDRAW, *LPNMTVCUSTOMDRAW;

Members

nmcd
NMCUSTOMDRAW structure that contains general custom draw information.
clrText
COLORREF value representing the color that will be used to display text foreground in the list-view control.
clrTextBk
COLORREF value representing the color that will be used to display text background in the list-view control.
iLevel
Version 4.71. Zero-based level of the item being drawn. The root item is at level zero, a child of the root item is at level one, and so on.

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


NMTVDISPINFO

Contains and receives display information for a tree-view item. This structure is identical to the TV_DISPINFO structure, but it has been renamed to follow current naming conventions.

typedef struct tagNMTVDISPINFO {
    NMHDR hdr;
    TVITEM item;
} NMTVDISPINFO, FAR *LPNMTVDISPINFO;

Members

hdr
NMHDR structure that contains information about this notification message.
item
TVITEM structure that identifies and contains information about the tree-view item. The mask member of the TVITEM structure specifies which information is being set or retrieved. It can be one or more of the following values:
TVIF_CHILDREN | The cChildren member specifies, or is to receive, a value that indicates whether the item has child items.
TVIF_IMAGE | The iImage member specifies, or is to receive, the index of the item's nonselected icon in the image list.
TVIF_SELECTEDIMAGE | The iSelectedImage member specifies, or is to receive, the index of the item's selected icon in the image list.
TVIF_TEXT The pszText member specifies the new item text or the address of a buffer that is to receive the item text.

If the structure is receiving item text, you typically copy the text to the buffer pointed to by the pszText member of the TVITEM structure. However, you can return a string in the pszText member instead. If you do so, you cannot change or delete the string until the corresponding item text is deleted or until two additional TVN_GETDISPINFO notification messages have been sent.

See Also

TVN_SETDISPINFO, WM_NOTIFY

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMTVGETINFOTIP

Contains and receives tree-view item information needed to display a ToolTip for an item. This structure is used with the TVN_GETINFOTIP notification message.

typedef struct tagNMTVGETINFOTIP {
    NMHDR hdr;
    LPTSTR pszText;
    int cchTextMax;
    HTREEITEM hItem;
    LPARAM lParam;
} NMTVGETINFOTIP, *LPNMTVGETINFOTIP;

Members

hdr
NMHDR structure that contains information about this notification message.
pszText
Address of a character buffer that contains the text to be displayed. If you wish to change the text displayed in the ToolTip, you will need to modify the contents of this buffer. The size of this buffer is specified by the ccTextMax structure.
cchTextMax
Size of the buffer at pszText, in characters. Although you should never assume that this buffer will be of any particular size, the INFOTIPSIZE value can be used for design purposes.
hItem
Tree handle to the item for which the ToolTip is being displayed.
lParam
Application-defined data associated with the item for which the ToolTip is being displayed.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


NMTVKEYDOWN

Contains information about a keyboard event in a tree-view control. This structure is used with the TVN_KEYDOWN notification message. The structure is identical to the TV_KEYDOWN structure, but it has been renamed to follow current naming conventions.

typedef struct tagTVKEYDOWN {
    NMHDR hdr;
    WORD wVKey;
    UINT flags;
} NMTVKEYDOWN, FAR *LPNMTVKEYDOWN;

Members

hdr
NMHDR structure that contains information about this notification message.
wVKey
Virtual key code.
flags
Always zero.

See Also

WM_NOTIFY

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVHITTESTINFO

Contains information used to determine the location of a point relative to a tree-view control. This structure is used with the TVM_HITTEST message. The structure is identical to the TV_HITTESTINFO structure, but it has been renamed to follow current naming conventions.

 typedef struct tagTVHITTESTINFO {
    POINT pt;
    UINT flags;
    HTREEITEM hItem;
} TVHITTESTINFO, FAR *LPTVHITTESTINFO;

Members

pt
Client coordinates of the point to test.
flags
Variable that receives information about the results of a hit test. This member can be one or more of the following values:
TVHT_ABOVE | Above the client area.
TVHT_BELOW | Below the client area.
TVHT_NOWHERE | In the client area, but below the last item.
TVHT_ONITEM | On the bitmap or label associated with an item.
TVHT_ONITEMBUTTON | On the button associated with an item.
TVHT_ONITEMICON | On the bitmap associated with an item.
TVHT_ONITEMINDENT | In the indentation associated with an item.
TVHT_ONITEMLABEL | On the label (string) associated with an item.
TVHT_ONITEMRIGHT | In the area to the right of an item.
TVHT_ONITEMSTATEICON | On the state icon for a tree-view item that is in a user-defined state.
TVHT_TOLEFT | To the left of the client area.
TVHT_TORIGHT | To the right of the client area.
hItem
Handle to the item that occupies the point.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVINSERTSTRUCT

Contains information used to add a new item to a tree-view control. This structure is used with the TVM_INSERTITEM message. The structure is identical to the TV_INSERTSTRUCT structure, but it has been renamed to follow current naming conventions.

typedef struct tagTVINSERTSTRUCT {
    HTREEITEM hParent;
    HTREEITEM hInsertAfter;
#if (_WIN32_IE >= 0x0400)
    union
    {
        TVITEMEX itemex;
        TVITEM item;
    } DUMMYUNIONNAME;
#else
    TVITEM item;
#endif
} TVINSERTSTRUCT, FAR *LPTVINSERTSTRUCT;

Members

hParent
Handle to the parent item. If this member is the TVI_ROOT value or NULL, the item is inserted at the root of the tree-view control.
hInsertAfter
Handle to the item after which the new item is to be inserted, or one of the following values:
Value | Description
TVI_FIRST | Inserts the item at the beginning of the list.
TVI_LAST | Inserts the item at the end of the list.
TVI_ROOT | Add the item as a root item.
TVI_SORT | Inserts the item into the list in alphabetical order.
itemex
Version 4.71. TVITEMEX structure that contains information about the item to add.
item
TVITEM structure that contains information about the item to add.

Remarks

The unions in this structure have been updated to work with compilers that do not support nameless unions. If your compiler does not support nameless unions, define the NONAMELESSUNION token before including the commctrl.h header file.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


TVITEM

Specifies or receives attributes of a tree-view item. This structure is identical to the TV_ITEM structure, but it has been renamed to follow current naming conventions. New applications should use this structure.

typedef struct tagTVITEM{
    UINT      mask;
    HTREEITEM hItem;
    UINT      state;
    UINT      stateMask;
    LPTSTR    pszText;
    int       cchTextMax;
    int       iImage;
    int       iSelectedImage;
    int       cChildren;
    LPARAM    lParam;
} TVITEM, FAR *LPTVITEM;

Members

mask
Array of flags that indicate which of the other structure members contain valid data. When this structure is used with the TVM_GETITEM message, the mask member indicates the item attributes to retrieve. This member can be one or more of the following values.
TVIF_CHILDREN | The cChildren member is valid.
TVIF_DI_SETITEM | The tree-view control will retain the supplied information and will not request it again. This flag is valid only when processing the TVN_GETDISPINFO notification.
TVIF_HANDLE | The hItem member is valid.
TVIF_IMAGE | The iImage member is valid.
TVIF_PARAM | The lParam member is valid.
TVIF_SELECTEDIMAGE | The iSelectedImage member is valid.
TVIF_STATE | The state and stateMask members are valid.
TVIF_TEXT | The pszText and cchTextMax members are valid.
hItem
Item to which this structure refers.
state
Set of bit flags and image list indexes that indicate the item's state. When setting the state of an item, the stateMask member indicates the bits of this member that are valid. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member.

Bits 0 through 7 of this member contain the item state flags. For a list of possible item state flags, see Tree-View Control Item States.

The overlay image is superimposed over the item's icon image. Bits 8 through 11 of this member specify the one-based overlay image index. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK mask. To set the overlay image index in this member, use the INDEXTOOVERLAYMASK macro. The image list's overlay images are set with the ImageList_SetOverlayImage function.

A state image is displayed next to an item's icon to indicate an application-defined state. Specify the state image list by sending a TVM_SETIMAGELIST message. To set an item's state image, include the TVIS_STATEIMAGEMASK value in the stateMask member of the TVITEM structure. Bits 12 through 15 of the structure's state member specify the index in the state image list of the image to be drawn.

To set the state image index, use INDEXTOSTATEIMAGEMASK. This macro takes an index and sets bits 12 through 15 appropriately. To indicate that the item has no state image, set the index to zero. This convention means that image zero in the state image list cannot be used as a state image. To isolate bits 12 through 15 of the state member, use the TVIS_STATEIMAGEMASK mask.

stateMask
Bits of the state member that are valid. If you are retrieving an item's state, set the bits of the stateMask member to indicate the bits to be returned in the state member. If you are setting an item's state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item's overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item's state image index, set the TVIS_STATEIMAGEMASK bits.
pszText
Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree-view control sends the parent window a TVN_GETDISPINFO notification message when it needs the item text for displaying, sorting, or editing and a TVN_SETDISPINFO notification message when the item text changes.

If the structure is receiving item attributes, this member is the address of the buffer that receives the item text.

cchTextMax
Size of the buffer pointed to by the pszText member, in characters. If this structure is being used to set item attributes, this member is ignored.
iImage
Index in the tree-view control's image list of the icon image to use when the item is in the nonselected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to retrieve the index when it needs to display the image.

iSelectedImage
Index in the tree-view control's image list of the icon image to use when the item is in the selected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to retrieve the index when it needs to display the image.

cChildren
Flag that indicates whether the item has associated child items. This member can be one of the following values.
zero | The item has no child items.
one | The item has one or more child items.
I_CHILDRENCALLBACK The parent window keeps track of whether the item has child items. In this case, when the tree-view control needs to display the item, the control sends the parent a TVN_GETDISPINFO notification message to determine whether the item has child items.

If the tree-view control has the TVS_HASBUTTONS style, it uses this member to determine whether to display the button indicating the presence of child items. You can use this member to force the control to display the button even though the item does not have any child items inserted. This allows you to display the button while minimizing the control's memory usage by inserting child items only when the item is visible or expanded.

lParam
A value to associate with the item.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in commctrl.h.


TVITEMEX

Specifies or receives attributes of a tree-view item. This structure is an enhancement to the TVITEM structure. New applications should use this structure where appropriate.

typedef struct tagTVITEMEX{
    UINT      mask;
    HTREEITEM hItem;
    UINT      state;
    UINT      stateMask;
    LPTSTR    pszText;
    int       cchTextMax;
    int       iImage;
    int       iSelectedImage;
    int       cChildren;
    LPARAM    lParam;
    int       iIntegral;
} TVITEMEX, FAR *LPTVITEMEX;

Members

mask
Array of flags that indicate which of the other structure members contain valid data. When this structure is used with the TVM_GETITEM message, the mask member indicates the item attributes to retrieve. This member can be one or more of the following values.
TVIF_CHILDREN | The cChildren member is valid.
TVIF_DI_SETITEM | The tree-view control will retain the supplied information and will not request it again. This flag is valid only when processing the TVN_GETDISPINFO notification.
TVIF_HANDLE | The hItem member is valid.
TVIF_IMAGE | The iImage member is valid.
TVIF_INTEGRAL | The iIntegral member is valid.
TVIF_PARAM | The lParam member is valid.
TVIF_SELECTEDIMAGE | The iSelectedImage member is valid.
TVIF_STATE | The state and stateMask members are valid.
TVIF_TEXT | The pszText and cchTextMax members are valid.
hItem
Item to which this structure refers.
state
Set of bit flags and image list indexes that indicate the item's state. When setting the state of an item, the stateMask member indicates the bits of this member that are valid. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member.

Bits 0 through 7 of this member contain the item state flags. For a list of possible item state flags, see Tree-View Control Item States.

Bits 8 through 11 of this member specify the one-based overlay image index. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK mask. To set the overlay image index in this member, use the INDEXTOOVERLAYMASK macro. The image list's overlay images are set with the ImageList_SetOverlayImage function.

A state image is displayed next to an item's icon to indicate an application-defined state. Specify the state image list by sending a TVM_SETIMAGELIST message. To set an item's state image, include the TVIS_STATEIMAGEMASK value in the stateMask member of the TVITEM structure. Bits 12 through 15 of the structure's state member specify the index in the state image list of the image to be drawn.

To set the state image index, use INDEXTOSTATEIMAGEMASK. This macro takes an index and sets bits 12 through 15 appropriately. To indicate that the item has no state image, set the index to zero. This convention means that image zero in the state image list cannot be used as a state image. To isolate bits 12 through 15 of the state member, use the TVIS_STATEIMAGEMASK mask.

stateMask
Bits of the state member that are valid. If you are retrieving an item's state, set the bits of the stateMask member to indicate the bits to be returned in the state member. If you are setting an item's state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item's overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item's state image index, set the TVIS_STATEIMAGEMASK bits.
pszText
Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree-view control sends the parent window a TVN_GETDISPINFO notification message when it needs the item text for displaying, sorting, or editing and a TVN_SETDISPINFO notification message when the item text changes.

If the structure is receiving item attributes, this member is the address of the buffer that receives the item text.

cchTextMax
Size of the buffer pointed to by the pszText member, in characters. If this structure is being used to set item attributes, this member is ignored.
iImage
Index in the tree-view control's image list of the icon image to use when the item is in the nonselected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to retrieve the index when it needs to display the image.

iSelectedImage
Index in the tree-view control's image list of the icon image to use when the item is in the selected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to retrieve the index when it needs to display the image.

cChildren
Flag that indicates whether the item has associated child items. This member can be one of the following values.
zero | The item has no child items.
one | The item has one or more child items.
I_CHILDRENCALLBACK The parent window keeps track of whether the item has child items. In this case, when the tree-view control needs to display the item, the control sends the parent a TVN_GETDISPINFO notification message to determine whether the item has child items.

If the tree-view control has the TVS_HASBUTTONS style, it uses this member to determine whether to display the button indicating the presence of child items. You can use this member to force the control to display the button even though the item does not have any child items inserted. This allows you to display the button while minimizing the control's memory usage by inserting child items only when the item is visible or expanded.

lParam
A value to associate with the item.
iIntegral
Height of the item. This height is in increments of the standard item height (see TVM_SETITEMHEIGHT). By default, each item gets one increment of item height. Setting this member to 2 will give the item twice the standard height; setting this member to 3 will give the item three times the standard height; and so on. The tree-view control does not draw in this extra area. This extra space can be used by the application for drawing when using custom draw.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


TVSORTCB

Contains information used to sort child items in a tree-view control. This structure is used with the TVM_SORTCHILDRENCB message. This structure is identical to the TV_SORTCB structure, but it has been renamed to follow current naming conventions.

typedef struct tagTVSORTCB{
    HTREEITEM hParent;
    PFNTVCOMPARE lpfnCompare;
    LPARAM lParam;
} TVSORTCB, FAR *LPTVSORTCB;

Members

hParent
Handle to the parent item.
lpfnCompare
Address of an application-defined callback function, which is called during a sort operation each time the relative order of two list items needs to be compared. The callback function has the following form:

int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2,
LPARAM lParamSort);
The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters correspond to the lParam member of the TVITEM structure for the two items being compared. The lParamSort parameter corresponds to the lParam member of this structure.

lParam
Application-defined value that gets passed as the lParamSort argument in the callback function specified in lpfnCompare.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Up-Down Controls

An up-down control is a pair of arrow buttons that the user can click to increment or decrement a value, such as a scroll position or a number displayed in a companion control. The value associated with an up-down control is called its current position. An up-down control is most often used with a companion control, which is called a buddy window.

  • About Up-Down Controls
  • Up-Down Control Updates in Internet Explorer
  • Up-Down Control Reference

About Up-Down Controls

To the user, an up-down control and its buddy window often look like a single control. You can specify that an up-down control automatically position itself next to its buddy window and that it automatically set the caption of the buddy window to its current position. For example, you can use an up-down control with an edit control to prompt the user for numeric input. The following illustration shows an up-down control with an edit control as its buddy window, a combination that is sometimes referred to as a spinner control.

Up-down control with an edit control as its buddy window.

An up-down control without a buddy window functions as a sort of simplified scroll bar. For example, a tab control sometimes displays an up-down control to enable the user to scroll additional tabs into view. The following illustration shows an up-down control in the upper-right corner of a tab control.

Up-down control in the upper-right corner of a tab control.

You can create an up-down control and specify its buddy window in several ways. The UPDOWN_CLASS value specifies an up-down control's window class. You can specify this window class in a dialog box template or in a call to the CreateWindowEx function. Another way is to use the CreateUpDownControl function to create an up-down control and, at the same time, specify its buddy window, current position, and minimum and maximum positions.

The UPDOWN_CLASS window class is registered when the common controls dynamic-link library (DLL) is loaded. If you create an up-down control without using the CreateUpDownControl function, you must ensure that the DLL is loaded. You can do so by using the InitCommonControls function.

CreateUpDownControl enables you to specify a buddy window. If you create an up-down control without using this function, you can assign a buddy window by specifying the UDS_AUTOBUDDY window style or by using the UDM_SETBUDDY message. If UDS_AUTOBUDDY is specified, the up-down control automatically selects the previous window in the z-order as its buddy window. This window might be the previous control in a dialog box template. You can use UDM_SETBUDDY to assign a specific buddy window to an up-down control. To determine an up-down control's current buddy window, use the UDM_GETBUDDY message. An up-down control and its buddy window must have the same parent window.

An up-down control notifies its parent window when its current position changes by sending it a UDN_DELTAPOS notification message and a WM_VSCROLL or WM_HSCROLL message. A vertical up-down control (which does not have the UDS_HORZ style) sends a WM_VSCROLL message. A horizontal up-down control (which has the UDS_HORZ style) sends a WM_HSCROLL message.

About Up-Down Control Styles

Using window styles, you can manipulate characteristics of an up-down control, such as how it positions itself relative to its buddy window, whether it sets the text of its buddy window, and whether it processes the UP ARROW and DOWN ARROW keys.

An up-down control with the UDS_ALIGNLEFT or UDS_ALIGNRIGHT style aligns with the left or right edge of its buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.

An up-down control with the UDS_SETBUDDYINT style sets the caption of its buddy window whenever the current position changes. The control inserts a thousands separator between every three digits of a decimal string unless the UDS_NOTHOUSANDS style is specified. If the buddy window is a list box, an up-down control sets its current selection instead of its caption.

You can specify the UDS_ARROWKEYS style to provide a keyboard interface for an up-down control. If this style is specified, the control processes the UP ARROW and DOWN ARROW keys. The control also subclasses the buddy window so that it can process these keys when the buddy window has the focus.

If you use an up-down control for horizontal scrolling, you can specify the UDS_HORZ style. This style causes the up-down control's arrows to point left and right instead of up and down.

By default, the current position does not change if the user attempts to increment it or decrement it beyond the maximum or minimum value. You can change this behavior by using the UDS_WRAP style, so the position "wraps" to the opposite extreme. For example, incrementing past the upper limit wraps the position back to the lower limit.

Position and Acceleration

After an up-down control is created, you can change the control's current position, minimum position, and maximum position by sending messages. You can also change the radix base used to display the current position in the buddy window and the rate at which the current position changes when the up or down arrow is clicked.

To retrieve the current position of an up-down control, use the UDM_GETPOS message. For an up-down control with a buddy window, the current position is the number in the buddy window's caption. Because the caption may have changed (for example, the user may have edited the text of an edit control), the up-down control retrieves the current caption and updates its current position accordingly.

The buddy window's caption may be either a decimal or hexadecimal string, depending on the radix base (that is, either base 10 or 16) of the up-down control. You can set the radix base by using the UDM_SETBASE message and retrieve the radix base by using the UDM_GETBASE message.

The UDM_SETPOS message sets the current position of a buddy window. Note that unlike a scroll bar, an up-down control automatically changes its current position when the up and down arrows are clicked. An application, therefore, does not need to set the current position when processing the WM_VSCROLL or WM_HSCROLL message.

You can change the minimum and maximum positions of an up-down control by using the UDM_SETRANGE message. The maximum position may be less than the minimum, and in that case clicking the up arrow button decreases the current position. To put it another way, up means moving towards the maximum position. To retrieve the minimum and maximum positions for an up-down control, use the UDM_GETRANGE message.

You can control the rate at which the position changes when the user holds down an arrow button by setting the up-down control's acceleration. The acceleration is defined by an array of UDACCEL structures. Each structure specifies a time interval and the number of units by which to increment or decrement at the end of that interval. To set the acceleration, use the UDM_SETACCEL message. To retrieve acceleration information, use the UDM_GETACCEL message.

Default Up-Down Controls Message Processing

This section describes the standard Windows messages processed by an up-down control.
Message | Processing performed
WM_CREATE | Allocates and initializes a private data structure and saves its address as window data.
WM_DESTROY | Frees data allocated during WM_CREATE processing.
WM_ENABLE | Invalidates the window.
WM_KEYDOWN | Changes the current position in the case of an UP ARROW or DOWN ARROW key.
WM_KEYUP | Completes the position change.
WM_LBUTTONDOWN | Captures the mouse. If the buddy window is an edit control or list box, it sets the focus to the buddy window. If the mouse is over the up or down button, it begins changing the position and sets a timer.
WM_LBUTTONUP | Completes the position change and releases the mouse capture if the up-down control has captured the mouse. If the buddy window is an edit control, it selects all the text in the edit control.
WM_PAINT | Paints the up-down control. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_TIMER | Changes the current position if the mouse is being held down over a button and a sufficient interval has elapsed.

Up-Down Control Updates in Internet Explorer

Up-down controls in Microsoft® Internet Explorer support the following new feature.

Full 32-bit Range
The up-down control now supports a full 32-bit range. The UDM_SETRANGE32 and UDM_GETRANGE32 messages have been added to support this feature. The up-down control uses signed integers for its range, so it is necessary to set the range from -0x7FFFFFFF to +0x7FFFFFFF to utilize the full 32-bit range.


Up-Down Control Styles

The following styles are used when creating up-down controls.

UDS_ALIGNLEFT | Positions the up-down control next to the left edge of the buddy window. The buddy window is moved to the right, and its width is decreased to accommodate the width of the up-down control.
UDS_ALIGNRIGHT | Positions the up-down control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.
UDS_ARROWKEYS | Causes the up-down control to increment and decrement the position when the UP ARROW and DOWN ARROW keys are pressed.
UDS_AUTOBUDDY | Automatically selects the previous window in the z-order as the up-down control's buddy window.
UDS_HORZ | Causes the up-down control's arrows to point left and right instead of up and down.
UDS_HOTTRACK | Causes the control to exhibit "hot tracking" behavior. That is, it highlights the UP ARROW and DOWN ARROW on the control as the pointer passes over them. This style requires Microsoft® Windows® 98 or Windows® 2000. If the system is running Windows® 95 or Windows NT® 4.0, the flag is ignored. To check whether hot tracking is enabled, call SystemParametersInfo.
UDS_NOTHOUSANDS | Does not insert a thousands separator between every three decimal digits.
UDS_SETBUDDYINT | Causes the up-down control to set the text of the buddy window (using the WM_SETTEXT message) when the position changes. The text consists of the position formatted as a decimal or hexadecimal string.
UDS_WRAP | Causes the position to "wrap" if it is incremented or decremented beyond the ending or beginning of the range.


CreateUpDownControl

Creates an up-down control.

HWND CreateUpDownControl(
    DWORD dwStyle,
    int x,
    int y,
    int cx,
    int cy,
    HWND hParent,
    int nID,
    HINSTANCE hInst
    HWND hBuddy,
    int nUpper,
    int nLower,
    int nPos
);

Parameters

dwStyle
Window styles for the control. This parameter should include the WS_CHILD, WS_BORDER, and WS_VISIBLE styles, and it may include any of the window styles specific to the up-down control.
x
Horizontal coordinate, in client coordinates, of the upper-left corner of the control.
y
Vertical coordinate, in client coordinates, of the upper-left corner of the control.
cx
Width, in pixels, of the up-down control.
cy
Height, in pixels, of the up-down control.
hParent
Handle to the parent window of the up-down control.
nID
Identifier for the up-down control.
hInst
Handle to the module instance of the application creating the up-down control.
hBuddy
Handle to the window associated with the up-down control. If this parameter is NULL, the control has no buddy window.
nUpper
Upper limit (range) of the up-down control.
nLower
Lower limit (range) of the up-down control.
nPos
Position of the control.

Return Values

If the function succeeds, the return value is the window handle to the up-down control. If the function fails, the return value is NULL.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.
Import Library: comctl32.lib.


UDM_GETACCEL

Retrieves acceleration information for an up-down control.

UDM_GETACCEL
    wParam = (WPARAM) cAccels;
    lParam = (LPARAM) (LPUDACCEL) paAccels;

Parameters

cAccels
Number of elements in the array specified by paAccels.
paAccels
Address of an array of UDACCEL structures that receive acceleration information.

Return Values

The return value is the number of accelerator structures retrieved.

If the cAccels parameter is zero and the paAccels parameter is NULL, the return value is the number of accelerators currently set for the control.

See Also

UDM_SETACCEL

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_GETBASE

Retrieves the current radix base (that is, either base 10 or 16) for an up-down control.

UDM_GETBASE
    wParam = 0;
    lParam = 0;

Return Values

The return value is the current base value.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_GETBUDDY

Retrieves the handle to the current buddy window.

UDM_GETBUDDY
    wParam = 0;
    lParam = 0;

Return Values

The return value is the handle to the current buddy window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_GETPOS

Retrieves the current position of an up-down control with 16-bit precision.

UDM_GETPOS
    wParam = 0;
    lParam = 0;

Return Values

If successful, the high-order word is set to zero and the low-order word is set to the control's current position. If an error occurs, the high-order word is set to a nonzero value.

Remarks

When processing this message, the up-down control updates its current position based on the caption of the buddy window. The up-down control returns an error if there is no buddy window or if the caption specifies an invalid or out-of-range value.

If 32-bit values have been enabled for an up-down control with UDM_SETRANGE32, this message returns only the lower 16 bits of the position. To retrieve the full 32-bit position, use UDM_GETPOS32.

See Also

UDM_GETRANGE, UDM_GETRANGE32, UDM_SETPOS, UDM_SETRANGE32

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_GETPOS32

Returns the 32-bit position of an up-down control.

UDM_GETPOS32
    wParam = 0;
    lParam = (LPARAM) (LPBOOL) pfError;

Parameters

pfError
Pointer to a Boolean value that is set to zero if the value is successfully retrieved or nonzero if an error occurs. If this parameter is set to NULL, errors are not reported.

Return Values

Returns the position of an up-down control with 32-bit precision. Applications must check the pfError value to determine whether the return value is valid.

Remarks

When it processes this message, the up-down control updates its current position based on the caption of the buddy window. It returns an error if there is no buddy window or if the caption specifies an invalid or out-of-range value.

See Also

UDM_GETPOS, UDM_SETPOS, UDM_SETPOS32

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


UDM_GETRANGE

Retrieves the minimum and maximum positions (range) for an up-down control.

UDM_GETRANGE
    wParam = 0;
    lParam = 0;

Return Values

The return value is a 32-bit value that contains the minimum and maximum positions. The low-order word is the maximum position for the control, and the high-order word is the minimum position.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_GETRANGE32

Retrieves the 32-bit range of an up-down control.

UDM_GETRANGE32
    wParam = (WPARAM)(LPINT) pLow;
    lParam = (LPARAM)(LPINT) pHigh;

Parameters

pLow
Address of a signed integer that receives the lower limit of the up-down control range. This parameter may be NULL.
pHigh
Address of a signed integer that receives the upper limit of the up-down control range. This parameter may be NULL.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


UDM_GETUNICODEFORMAT

Retrieves the UNICODE character format flag for the control.

UDM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Return Values

Returns the UNICODE format flag for the control. If this value is nonzero, the control is using UNICODE characters. If this value is zero, the control is using ANSI characters.

Remarks

See the remarks for CCM_GETUNICODEFORMAT for a discussion of this message.

See Also

UDM_SETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_SETACCEL

Sets the acceleration for an up-down control.

UDM_SETACCEL
    wParam = (WPARAM) nAccels;
    lParam = (LPARAM) (LPUDACCEL) aAccels;

Parameters

nAccels
Number of UDACCEL structures specified by aAccels.
aAccels
Address of an array of UDACCEL structures that contain acceleration information. Elements should be sorted in ascending order based on the nSec member.

Return Values

Returns TRUE if successful, or FALSE otherwise.

See Also

UDM_GETACCEL

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_SETBASE

Sets the radix base for an up-down control. The base value determines whether the buddy window displays numbers in decimal or hexadecimal digits. Hexadecimal numbers are always unsigned, and decimal numbers are signed.

UDM_SETBASE
    wParam = (WPARAM) nBase;
    lParam = 0;

Parameters

nBase
New base value for the control. This parameter can be 10 for decimal or 16 for hexadecimal.

Return Values

The return value is the previous base value. If an invalid base is given, the return value is zero.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_SETBUDDY

Sets the buddy window for an up-down control.

UDM_SETBUDDY
    wParam = (WPARAM) (HWND) hwndBuddy;
    lParam = 0;

Parameters

hwndBuddy
Handle to the new buddy window.

Return Values

The return value is the handle to the previous buddy window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_SETPOS

Sets the current position for an up-down control with 16-bit precision.

UDM_SETPOS
    wParam = 0;
    lParam = (LPARAM) MAKELONG((short) nPos, 0);

Parameters

nPos
New position for the up-down control. If the parameter is outside the control's specified range, nPos will be set to the nearest valid value.

Return Values

The return value is the previous position.

Remarks

This message only supports 16-bit positions. If 32-bit values have been enabled for an up-down control with UDM_SETRANGE32, use UDM_SETPOS32.

See Also

UDM_GETRANGE, UDM_GETPOS

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_SETPOS32

Sets the position of an up-down control with 32-bit precision.

UDM_SETPOS32
    wParam = 0;
    lParam = (LPARAM) (INT) nPos;

Parameters

nPos
Variable of type integer that specifies the new position for the up-down control. If the parameter is outside the control's specified range, nPos is set to the nearest valid value.

Return Values

Returns the previous position.

See Also

UDM_GETPOS, UDM_SETPOS, UDM_GETPOS32

Requirements

Version 5.80 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in commctrl.h.


UDM_SETRANGE

Sets the minimum and maximum positions (range) for an up-down control.

UDM_SETRANGE
    wParam = 0;
    lParam = (LPARAM) MAKELONG((short) nUpper, (short) nLower);

Parameters

nUpper and nLower
Maximum position and minimum position for the up-down control. Neither position can be greater than the UD_MAXVAL value or less than the UD_MINVAL value. In addition, the difference between the two positions cannot exceed UD_MAXVAL.

Return Values

No return value.

Remarks

The maximum position can be less than the minimum position. Clicking the up arrow button moves the current position closer to the maximum position, and clicking the down arrow button moves towards the minimum position.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


UDM_SETRANGE32

Sets the 32-bit range of an up-down control.

UDM_SETRANGE32
    wParam = (WPARAM)(int) iLow;
    lParam = (LPARAM)(int) iHigh;

Parameters

iLow
Signed integer value that represents the new lower limit of the up-down control range.
iHigh
Signed integer value that represents the new upper limit of the up-down control range.

Return Values

The return value for this message is not used.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


UDM_SETUNICODEFORMAT

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

UDM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Parameters

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

Return Values

Returns the previous UNICODE format flag for the control.

Remarks

See the remarks for CCM_SETUNICODEFORMAT for a discussion of this message.

See Also

See also UDM_GETUNICODEFORMAT

Requirements

Version 4.00 and later of Comctl32.dll

Windows NT/2000: Requires Windows NT 4.0 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NM_RELEASEDCAPTURE (up-down)

Notifies an up-down control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam;

Parameters

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Return Values

The control ignores the return value from this notification.

Requirements

Version 4.71 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in commctrl.h.


UDN_DELTAPOS

Sent by the operating system to the parent window of an up-down control when the position of the control is about to change. This happens when the user requests a change in the value by pressing the control's up or down arrow. The UDN_DELTAPOS message is sent in the form of a WM_NOTIFY message.

UDN_DELTAPOS
    lpnmud = (LPNMUPDOWN) lParam;

Parameters

lpnmud
Address of an NMUPDOWN structure that contains information about the position change.

The iPos member of this structure contains the current position of the control. The iDelta member of the structure is a signed integer that contains the proposed change in position. If the user has clicked the up button, this is a positive value. If the user has clicked the down button, this is a negative value.

Return Values

Return nonzero to prevent the change in the control's position, or zero to allow the change.

Remarks

The UDN_DELTAPOS notification is sent before the WM_VSCROLL or WM_HSCROLL message, which actually changes the control's position. This lets you examine, allow, modify, or disallow the change.

See Also

WM_COMMAND

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


NMUPDOWN

Contains information specific to up-down control notification messages. It is identical to and replaces the NM_UPDOWN structure.

typedef struct _NM_UPDOWN {
    NMHDR hdr;
    int   iPos;
    int   iDelta;
} NMUPDOWN, FAR *LPNMUPDOWN;

Members

hdr
NMHDR structure that contains additional information about the notification message.
iPos
Signed integer value that represents the up-down control's current position.
iDelta
Signed integer value that represents the proposed change in the up-down control's position.

See Also

UDN_DELTAPOS, WM_NOTIFY

Requirements

Version 4.70 and later of Comctl32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 3.0 and later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 3.0 or later).
Header: Declared in commctrl.h.


UDACCEL

Contains acceleration information for an up-down control.

typedef struct {
    UINT nSec;
    UINT nInc;
}UDACCEL, FAR *LPUDACCEL;

Members

nSec
Amount of elapsed time, in seconds, before the position change increment specified by nInc is used.
nInc
Position change increment to use after the time specified by nSec elapses.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later
Windows 95/98/Me: Requires Windows 95 or later
Header: Declared in commctrl.h.


Shell Programmers Guide

The Microsoft® Windows® user interface (UI) provides users with access to a wide variety of objects necessary for running applications and managing the operating system. The most numerous and familiar of these objects are the folders and files that reside on computer disk drives. There are also a number of virtual objects that allow the user to do tasks such as sending files to remote printers or accessing the Recycle Bin. The Shell organizes these objects into a hierarchical namespace, and provides users and applications with a consistent and efficient way to access and manage objects.

The Shell Programmers Guide describes how the Shell works and how to use the Shell's API in your application. This document provides a brief overview of its contents.

  • Document Conventions
  • How the Shell Programmers Guide Is Organized
  • Overview of Shell Basics
  • Overview of Intermediate Shell Techniques
  • Overview of Advanced Shell Techniques

Document Conventions

The Shell Programmers Guide follows the usual Platform SDK document conventions. Two conventions in particular should be noted:

  • Sample code omits normal error-correction code. This code has been removed only to make the code more readable. You should include all appropriate error-correction code in your own applications.
  • To make sample registry entries clear, key names are displayed with a bold font. Value names and data are displayed with a standard font.

How the Shell Programmers Guide Is Organized

The Shell Programmers Guide is organized into three sections: Shell Basics, Intermediate Shell Techniques, and Advanced Shell Techniques. The Shell Basics section contains information that all Shell programmers should be familiar with. The remaining two sections discuss more sophisticated or specialized Shell features.

The Shell Basics and Intermediate Shell Techniques sections are divided into two subsections that reflect the distinctly different ways that developers can interact with the Shell:

  • Programming the Shell. The Shell API can be used by applications to perform a variety of tasks. In this context, Shell programming is similar to other types of Windows programming.
  • Extending the Shell. There are a number of ways that you can customize or extend the behavior of the Shell. For instance, you can modify the shortcut menus that the Shell displays when a user right-clicks a particular file, or you can change the file's icon. The simplest Shell extensions can be implemented by modifying the registry. More sophisticated Shell extensions require you to implement a dynamic-link library (DLL), which is loaded by the Shell.

Overview of Shell Basics

The Shell Basics section provides an introduction to the Shell. It includes discussions of those features of the Shell that most developers should be familiar with. If you are unfamiliar with the Shell, you should read through Shell Basics before going on to the remaining sections.

The initial document in Shell Basics is the Shell Namespace. It discusses the architecture of the Shell namespace and how Shell objects are identified. This section is a must-read, as it introduces concepts and vocabulary that are fundamental to Shell programming. Familiarity with this document is assumed for all subsequent documents in the Shell Programming Guide.

The Shell Basics: Programming the Shell section discusses how to do a number of basic tasks, including:

  • How to navigate the namespace and find files and folders.
  • How to launch applications.
  • How to transfer Shell objects with Clipboard and drag-and-drop operations.
  • How to debug applications that use the Shell.

The Shell Basics: Extending the Shell section discusses how you can extend the Shell by modifying the registry or creating special files, including:

  • How to define a file name extension as a file class and associate it with an application.
  • How to customize a file class's icon and shortcut menu.
  • How to customize the appearance of a folder.
  • How to use Autorun to automatically launch a CD-ROM application.

Overview of Intermediate Shell Techniques

The Intermediate Shell Techniques section covers a number of the more sophisticated Shell features. Some of the topics in this section discuss more powerful and flexible ways to do some of the tasks discussed in Shell Basics. Other topics introduce Shell features that were not discussed in Shell Basics.

The Intermediate Shell Techniques: Programming the Shell section includes a document that outlines which interfaces are exposed by the standard Shell folders. The remaining topics discuss how to do a number of tasks, including:

  • How to create links and shortcuts.
  • How to use the taskbar.
  • How to use application desktop toolbars.

The bulk of the Intermediate Shell Techniques: Extending the Shell section discusses how to create Shell extension handlers. These handlers allow you to dynamically modify a variety of Shell behaviors, including the icons and shortcut menus associated with a class of files. Other sections discuss:

  • How to integrate your application's cleanup procedures with the Shell's disk cleanup manager.
  • How to customize the way Webview displays the contents of a folder.

Overview of Advanced Shell Techniques

The Advanced Shell Techniques section covers a variety of additional ways to extend the Shell. The bulk of the section discusses how to create a custom virtual folder, or namespace extension, and integrate it into the Shell's namespace. The remaining sections discuss some specialized Shell topics, including:

  • Creating custom explorer bars, tool bands, and desk bands.
  • Using the Active Desktop object.
  • Creating Control Panel applications.
  • Using the Shell API with scripting languages and Visual Basic®.


Shell FAQ

This FAQ provides answers to some questions that are commonly asked about the Shell. Links to the relevant documents are provided for a more detailed discussion.

What is the Shell namespace? What is a namespace object?

The Shell namespace organizes the file system and other objects managed by the Shell into a single tree-structured hierarchy. Conceptually, the Shell namespace is essentially a larger and more inclusive version of the file system. Namespace objects include file system folders and files, along with "virtual" objects, such as the Recycle Bin and Printers folders.
  • The Shell Namespace

Is there a dialog box that I can display to let the user choose a folder?

The SHBrowseForFolder function displays a dialog box that allows a user to select a directory, and returns its PIDL.

What is a PIDL? Why not just use file system paths?

A PIDL is a way of identifying any namespace object. You can also use paths to identify namespace objects, but only if they are part of the file system. With namespace objects that are not part of the file system, you must use PIDLs.
  • The Shell Namespace

How do I retrieve the PIDL of a namespace object?

There are a variety of ways to retrieve an object's PIDL. Some common approaches are:
  • Use the desktop's IShellFolder::ParseDisplayName method to convert a file system path into an equivalent PIDL. This method will also convert the GUID that identifies a virtual folder into a PIDL.
    • Getting Information About the Contents of a Folder
  • Display a dialog box that allows the user to select a folder, and returns its PIDL.
    • Getting a Folder's ID
  • Use the folder's CSIDL to retrieve its PIDL. Special folders, such as Program Files or Printers, are assigned a token called a CSIDL. You can use a special folder's CSIDL to obtain its PIDL. If a special folder is in the file system, you can also use its CSIDL to obtain its path.
    • Getting a Folder's ID
  • Navigate the namespace until you locate the object.
    • Getting Information About the Contents of a Folder
    • Navigating the Namespace

How do I use SHGetFolderPath on systems prior to Microsoft® Windows® 2000?

It is available as a redistributable DLL, ShFolder.dll.

How do I convert a PIDL back into a file path?

Use the Shell API's SHGetPathFromIDList function.

What is the difference between relative and fully-qualified PIDLs?

It is much like the difference between a relative and fully-qualified file path. Like a file path, a PIDL defines a path through the namespace, with one element for each portion of the path. Fully-qualified PIDLS start from the root of the namespace, the desktop. Relative PIDLS start from some other point in the namespace. Some Shell functions expect fully-qualified PIDLs, and others expect relative PIDLs, so it is important to understand which is required.
  • The Shell Namespace

How do I retrieve a file's icon? How do I retrieve a file's friendly name?

The Shell API provides a function for this purpose: SHGetFileInfo.

Is there a way to customize how objects are displayed in Windows Explorer?

There are two ways to customize Windows Explorer:
  • Create a Desktop.ini file for a folder.
    • Customizing Folders with Desktop.ini
  • Create a custom folder.htt file.
    • Web View

How can I use drag-and-drop or the clipboard to transfer namespace objects such as files or folders?

There are a number of Shell-specific clipboard formats that you can use to transfer Shell objects.
  • Transferring Shell Data Using Drag-and-Drop or the Clipboard

What is a file association? What is a file class? How do I create one? What are they good for?

The terms file association and file class mean essentially the same thing. A file association or file class consists of all the files that have the same file-name extension. File classes are created with the registry. Once a file class has been created, you can customize the behavior of its files. For instance, you can replace the standard file icon with a custom icon or add items to the shortcut menu.
  • Creating a File Association
  • Customizing Icons
  • Extending Shortcut Menus

How can I get AutoPlay to launch my CD-ROM application?

Create an AutoRun.inf file on the CD-ROM.
  • Creating an AutoPlay-enabled CD-ROM Application

What exactly is the My Documents folder and how do I use it?

It provides a default location for the current user's document files. It automatically maps to the location in the file system where the current user's document files are stored. You use it much like a normal file system folder.
  • Managing the File System


What's New in the Shell

This is preliminary documentation and is subject to change.

The Microsoft product code-named Whistler includes several enhancements to the Shell. This article introduces these new features and includes links to more in-depth discussions and reference material.

The following topics are discussed.

  • Shared Environments: Windows User Accounts and Desktop Switching
  • AutoPlay Hardware and Media Content
  • Control Panel Enhancements
  • Themes

Shared Environments: Windows User Accounts and Desktop Switching

Whistler provides an underlying infrastructure that supports state separation of user data, user settings, and computer settings. Applications that properly use this infrastructure have the following end-user benefits.

  • A user can easily back up individual documents and settings without backing up application or operating system files.
  • Multiple users can share a single computer while maintaining each user's preferences and settings.
  • A user can work at multiple computers and maintain documents and settings from one computer to another.

This infrastructure provides the following features and benefits.

  • Windows User Accounts
  • Desktop Switching
  • Personal Terminal Server (Remote Desktop)

Windows User Accounts

Whistler is a personalized system. Each user has the option of maintaining a separate Whistler account. This is a paradigm departure from Microsoft® Windows® 95 and Windows 98, where all users in a household typically chose to share one account.

Users are encouraged to create separate accounts during the Setup process. Accounts can also be created and maintained later through Control Panel.

Whistler accounts are Windows 2000-style profiles, which means that each user's data is stored separately. By default, these accounts are not password-protected, but users can choose to set a password on their account for greater privacy.

If there is more than one account on the computer, a Welcome screen is displayed as seen in the following example.

Welcome screen example

When users click their icon, their desktop is displayed or, if they have set a password, they are prompted to log on as shown in the following example.

Welcome screen login.

Desktop Switching

Desktop switching enables more than one user to be logged on at a time. Users can switch quickly among all open accounts, and all users who are logged on have access to the computer without requiring other users to log off.

For example, Samantha logs on. She connects to the Internet, then opens Microsoft® PowerPoint® and starts working on a document. James then asks for some time on the computer. He displays the Welcome screen, clicks his name, logs on, and starts playing a game. Samantha is still logged on at this point. If Samantha wishes, she can switch to her open account without logging James off. Samantha's PowerPoint presentation is still open and her Internet connection is preserved.

Personal Terminal Server (Remote Desktop)

Using Whistler, you can access data and applications from other computers. For example, you can lock your office workstation, and then connect to it from home. Using your home computer, you can control the applications running on your office workstation. When you return to the office, you can unlock your workstation and continue working from where you stopped at home.

AutoPlay Hardware and Media Content

AutoPlay is a new feature that detects content such as pictures, music, or video files on removable media and removable devices. AutoPlay then automatically launches applications to play or display that content. This simplifies the use of specialized peripheral devices such as MP3 players and digital photo readers. It also makes it easier for users unfamiliar with the software necessary to access various content types.

Before Whistler, Windows Millennium Edition (Windows Me) implemented similar support for picture content on imaging devices, automatically running the Acquisition UI (Scanner and Camera Wizard) when a camera or scanner is plugged in. Whistler generalizes and extends this scheme, making it a universal feature of the system for all hot-plug removable storage devices that appear in My Computer. AutoPlay is extensible so that other devices and media can benefit from this architecture.

An expanded selection of icons, including branded icons for major manufacturers, is included to offer improved visual differentiation of drives and other attached devices in My Computer. Icons for devices with removable media, with the exception of floppy disk drives, are provided in both ready and not-ready versions to indicate the current state of the device. This confirms that a device hot-plugged into the system is ready for use, and it helps avoid "device not ready" messages from devices without media inserted.

What does AutoPlay support?

Out of the box, AutoPlay supports a variety of media content types and applications. Both independent hardware vendors (IHVs) and independent software vendors (ISVs) can extend this support to include their hardware devices and applications. Whistler also supports mixed content. A user can configure a different AutoPlay action for any combination of pictures, music files, and video.

Supported Media and Device Types

The media and device types supported out of the box are:

  • Removable storage media such as Zip and Jaz
  • Flash media such as CompactFlash™, SmartMedia™, and Memory Stick
  • PC cards
  • External hot-plug USB or 1394 fixed drives

Supported Content Types

The content types supported out of the box are:

  • Pictures (.jpg, .bmp, .gif, .tif)
  • Music Files (.mp3, .wma)
  • Video (.mpg, .asf)
These content types must be in certain predetermined directories to be supported. For other file formats, media content providers and ISVs can define their own content types through a Desktop.ini file.

For more information see Using AutoPlay.

Control Panel Enhancements

The new Control Panel design addresses many of the top user issues seen in accessing system settings. It does this by grouping settings logically, and by exposing common tasks, links to related areas, and access to Help topics.

Whistler Control Panel offers a category view containing ten categories as shown in the following illustration. Eight of these categories are extensible (Add or Remove Programs and User Accounts are not) so that third parties can add their own control panels.

Control Panel Category View

Users can easily switch between this category view and the classic Control Panel view by means of a link in the left column of the page. Furthermore, the last view is maintained for each user. When Control Panel is opened, users see the same view that was displayed during their previous session.

Features of the Category Pages

The following illustration shows features available in the Appearance and Themes category. Tasks, Control Panel icons, and all other options are specific to the category selected.

Control Panel Appearance and Themes Category.

Category pages expose common tasks for a category, troubleshooters, and list-related See Also links. They also provide access to Control Panel applications that are registered in that particular category. Tasks launch Control Panel applications with the appropriate tab brought to the foreground. See Also entries can navigate to Web sites, launch Control Panel applications, or launch separate windows, depending on the link. Troubleshooting links launch Help and Support Center with the proper content.

Themes

What Are Themes?

Themes are specifications for the appearance of controls. They describe selected desktop elements' color, size, and font. The look and feel of theme-aware controls can change based on selected system themes. Similar theme ideas have been seen since Microsoft® Plus!. For example, the Windows 2000 Appearance tab in the Display Control Panel enables the user to change colors, fonts, and sizes of selected desktop elements. However, using Whistler themes in conjunction with common controls version 6 provides more control than ever over the desktop. Themes enable the system to make changes to any theme-aware control or window.

Themes provide a mechanism for all Windows-based applications to become theme-aware. You can take advantage of theme capability to produce controls that query the system for theme information. Therefore you can tailor your application's appearance to suit your audience—for example, a business user versus a home user.

Why Use Themes?

The theme library, UxTheme.lib, is a rendering library that separates the visual element of a control from its functionality. Using this library, a control can retrieve its appearance from the current system theme without the need for specialized code.

UxTheme.lib is used by common controls to take advantage of system themes, providing functions for opening and closing the theme data files, as well as a number of drawing and measuring functions. ComCtl32.dll version 6 queries UxTheme.lib for appropriate dimensions, sizes, and other pertinent information about a control. Using UxTheme.lib, you can define the rendering of icons, borders, controls, and other user interface (UI) elements.

For more information, see Themes.


Control Panel Categories

This is preliminary documentation and is subject to change.

The Whistler Control Panel now supports categorization of Control Panel applications. Whistler also has support for third parties to add Control Panel applications to categories.

Registering a Control Panel Application in a Category

You can register a Control Panel application in a particular category by adding a REG_DWORD entry indicating the desired category to the registry. The following example registry entry assigns the application MyCPL.cpl to the category Appearance and Themes. Details of the entry are discussed below.

HKEY_LOCAL_MACHINE
Software
Microsoft
Windows
CurrentVersion
Control Panel
Extended Properties
{305CA226-D286-468e-B848-2B2E8E697B74} 2
%SystemRoot%\System32\MyCPL.cpl= [REG_DWORD] 0x00000001

The registry key {305CA226-D286-468e-B848-2B2E8E697B74} 2 is the container for all category entries. That key represents SCID_CONTROLPANELCATEGORY, and is composed of PSGUID_CONTROLPANEL and PID_CONTROLPANEL_CATEGORY, both defined in Shlguid.h.

The Name entry is the full path of your .cpl file, using environment variables if desired. The Value entry for that Name should be one of the category IDs listed below, stored as a REG_DWORD.

  • 0x00000000 : Other Control Panel Options. Any Control Panel application that does not specify a category ID is put in this category.
  • 0x00000001 : Appearance and Themes.
  • 0x00000002 : Printers and Other Hardware.
  • 0x00000003 : Network and Internet Options.
  • 0x00000004 : Sounds, Speech, and Audio Devices.
  • 0x00000005 : Performance and Maintenance
  • 0x00000006 : Date, Time, Language, and Regional Options.
  • 0x00000007 : Accessibility Options.
  • 0x00000008 : Add or Remove Programs.
  • 0x00000009 : User Accounts.
  • 0xFFFFFFFF : Do not add to any category.

The categories Add or Remove Programs and User Accounts work somewhat differently from other categories in Control Panel. When one or more applications are added to one of these two categories, the associated link in Control Panel opens a category page. The registered applications appear in the lower portion of the page under the heading "or Pick a Control Panel icon". When no applications are registered for one of these categories, the associated link in Control Panel directly invokes the standard Microsoft® Windows® application for that category.

The parent key name Extended Property derives from the fact that you can access this property from script through the ExtendedProperty method on the ShellFolderItem object. The following sample Microsoft® JScript® code enumerates the control panels and their category IDs.

var strSCID = "{305CA226-D286-468e-B848-2B2E8E697B74} 2";
var shell = new ActiveXObject("Shell.Application");
var cpls = shell.Namespace(3).Items();   // 3 is the ID for Control Panel

for (i=0; i < cpls.Count; i++)
{
    var fldrItem = cpls.Item(i);
    Document.write("The cpl " + fldrItem.Name +
                   " belongs to category id " +
                   ldrItem.ExtendedProperty(strSCID));
}

For Control Panel applications that are implemented as Shell namespace extensions—for example, fonts or scheduled tasks—specify the category ID in the registry under the CLSID entry. For example, the registry entry for the Administrative Tools folder is as follows:

HKEY_CLASSES_ROOT
CLSID
{D20EA4E1-3957-11D2-A40B-OC5020524153}
{305CA226-D286-468e-B848-2B2E8E697B74} 2= [REG_DWORD] 0x00000005

In this case, you create a value named {305CA226-D286-468e-B848-2B2E8E697B74} 2, then store the category ID as a REG_DWORD as before.


Using AutoPlay

[This is preliminary documentation and subject to change.]

AutoPlay is a new feature of Microsoft® Windows® that detects content such as pictures, music, or video files on removable media and removable devices. AutoPlay then automatically launches applications to play or display that content. This simplifies the user experience for users dealing with specialized peripheral devices such as MP3 players and digital photo readers as well as for users unfamiliar with the software necessary to access various content types.

An expanded selection of icons, including branded icons for major manufacturers, is included to offer improved visual differentiation of drives and other attached devices in My Computer. Icons for devices with removable media, with the exception of floppy drives, are provided in both "ready" and "not ready" versions to indicate the current state of the device. This confirms that a device hot-plugged into the system is ready for use, and it helps avoid "device not ready" messages from devices without media inserted.

Note AutoPlay should not be confused with AutoRun. AutoRun, introduced in Windows 95, enables a compact disc to automatically launch a function, such as an installer or game play, when placed in the CD-ROM drive. This is accomplished through the use of an Autorun.inf file in the root directory of the compact disc. For more details, see the Microsoft Platform Software Development Kit (SDK) Shell documentation.

This documentation is organized in the following sections.

  • Using and Configuring AutoPlay
  • Preparing Hardware and Software for Use with AutoPlay


Themes

This is preliminary documentation and is subject to change.

The common controls that are included in the Microsoft product code-named Whistler are based on the Microsoft® Win32® common controls and user controls. This control set has a new functionality, referred to as themes. The look and feel of theme-aware controls can change based on selected system themes.

The following topics are discussed in this article.

  • What Are Themes?
  • How to Draw a Themed Control
  • Related Topics

What Are Themes?

Themes are specifications for the appearance of controls. For example, themes can define the color, size, and font of controls, and they enable you to configure the visual interface to coordinate with your application interface. Additionally, they provide a mechanism for all Microsoft® Windows®-based applications to become theme-aware.

An updated themes application programming interface (API)—ComCtl32.dll version 6—and an updated UxTheme library are provided in Whistler to enable you to program themes. The themes API provides functions for drawing, opening, closing, and retrieving theme information.

The common controls library, UxTheme.lib, is a rendering library that separates the visual element of a control from its functionality. Using this library, a control can retrieve its appearance from the current system theme without you writing specialized code.

UxTheme.lib is used by the common controls to take advantage of system themes. ComCtl32.dll queries UxTheme.lib for appropriate dimensions, sizes, and other pertinent information for a control. The dynamic-link library (DLL) calls UxTheme.lib to render the parts of a control or surface. Using UxTheme.lib, you can define the rendering of icons, borders, controls, and other user interface (UI) elements.

You can take advantage of theme capability and produce controls that query the system for theme information. The system UI modifies its appearance based on the theme specifications. Using the common controls delivered in ComCtl32.dll version 6 makes your application theme-aware; therefore you can tailor your application appearance to suit your audience. For example, the business and consumer releases of Whistler might each implement a different theme to create user interfaces that distinguish the two releases. The Appearance tab of the Display window on the Windows 2000 Control Panel enables the user to change colors, fonts, and sizes of desktop elements. The new controls provide a way for applications to modify desktop elements in the same way; they enable the system to make changes to any theme-aware control or window.

How to Draw a Themed Control

This section provides code examples of steps to create and display a themed button control.

  1. Obtain an HTHEME handle to use for calling the theme manager drawing routines. This can be done when the control is created—as soon as the hwnd is available—or each time the control is painted. The following code shows how to get an HTHEME handle for a button control.
    HTHEME hTheme;
hTheme = OpenThemeData( hwnd, L"button");
if (!hTheme) //If the handle cannot be retrieved,
             //go back to non-theme drawing code.
{
}
    Important See Theme Parts and States for a list of parts and states for button controls.
  2. Use the DrawThemeBackground function to paint the control in its normal, hot, pressed, disabled, down, or defaulted states. The following code shows how to draw the background of a push button.
    if (hTheme)
{
   int iStateId;

   if (fPushed)
      iStateId = 4;
   else if (fDisabled)
      iStateId = 3;
   else if (fMouseOver)
      iStateId = 2;
   else if (fDefault)
      iStateId = 1;
   else
      iStateId = 0;
   hr = DrawThemeBackground (hTheme, hdc,
        TMT_BUTTON, iStateId, &clientRect, 0);
}
else  //Use non-theme code.
{
}
    Important Use the lower level functions such as GetThemeXXX only when higher level functions do not suffice.
  3. Include code to provide backup drawing when the HTHEME handle is NULL.

Related Topics

  • Theme Reference


User Accounts with Fast User Switching and Remote Desktop

This is preliminary documentation and is subject to change.

Whistler user accounts enable multiple users to be logged on simultaneously, each with their own settings and each running their own applications. Because one user does not have to log off to allow access to another user, each user's desktop is easily accessed using the fast user switching feature. User accounts also include the Personal Terminal Server feature, or Remote Desktop, which enables users to access their desktop account from remote systems.

The following topics are discussed.

  • Infrastructure Usage Requirements
  • Compatibility with Existing Applications
  • Registering for Session Switching Notification
  • Ensuring Only One Instance of Your Application Is Running
  • Shutting Down Your Application Across All Sessions
  • Interaction with System Services
  • Remote Desktop and Bandwidth

Infrastructure Usage Requirements

Underlying infrastructure inherited from Microsoft® Windows® 2000 supports state separation of user data, user settings, and computer settings. Taking advantage of this infrastructure, the following are required to successfully run your application under Whistler.

  • Default to the My Documents folder for storage of user-created data.
  • Classify and store application data correctly.
  • Degrade gracefully on "Access Denied" messages.

Temporary files, memory-mapped files, and documents should all be stored in the appropriate subdirectory of the user's profile directory. Use SHGetFolderLocation or SHGetFolderPath to determine the appropriate storage location for these files. Passing the CSIDL_APPDATA flag to these functions returns the path of a file system directory that serves as a common repository for application-specific data. Use the flag CSIDL_LOCAL_APPDATA in place of CSIDL_APPDATA for data that should change when the user changes, such as temporary files.

The requirements listed above are a subset of those in the Microsoft Certification program. For more information, see the Certified for Windows Program page at http://msdn.microsoft.com/certification.

Compatibility with Existing Applications

Both fast user switching and Personal Terminal Server use Terminal Services technology and therefore are compatible with most earlier Microsoft® Win32® applications. If an application is Windows 2000 Logo compliant, implementing basic profile separation and power management features, that application should run properly under individual Whistler user accounts.

Registering for Session Switching Notification

Typically, an application does not need to be notified when a desktop switch occurs. However, applications that must be notified when the account under which they are running is the current desktop, such as applications that access the serial port or other shared resources, can register for desktop switch notification. To register for a notification, use the WTSRegisterSessionNotification function, which is defined in Wtsapi32.h as shown in the following function prototype.

BOOL WINAPI WTSRegisterSessionNotification(HWND hWnd,      //Window handle
                                           DWORD dwFlags); //Flags

The dwFlags parameter can have one of the following values.

  • NOTIFY_FOR_THIS_SESSION. The window receives session change notifications only if the change affects the session that the window belongs to.
  • NOTIFY_FOR_ALL_SESSIONS. The window receives notifications for all session changes.

Once that function has been called, the window with handle hWnd is registered to receive a WM_WTSSESSION_CHANGE message through its WndProc function. The session ID is sent in the lParam parameter, and a code indicating the event generating the message is sent in wParam as one of the following flags.

  • WTS_CONSOLE_CONNECT
  • WTS_CONSOLE_DISCONNECT
  • WTS_REMOTE_CONNECT
  • WTS_REMOTE_DISCONNECT
  • WTS_SESSION_LOGOFF
  • WTS_SESSION_LOGON

Applications can use this message to track their state, as well as to release and acquire console-specific resources. User desktops can be dynamically switched between remote and console control. Applications should use the WM_WTSSESSION_CHANGE message to synchronize with the remote or local connection state.

When your process no longer requires these notifications or is terminating, it should call the following function to unregister its notification.

BOOL WINAPI WTSUnRegisterSessionNotification(HWND hWnd);
Important The hWnd values passed to WTSRegisterSessionNotification are reference counted, so you must make an equal number of calls to WTSUnRegisterSessionNotification to ensure the release of all allocated resources.

Ensuring Only One Instance of Your Application Is Running

Many applications must ensure that they have only one instance running. There are several ways to do this in Whistler. Among them are the following:

  • Use FindWindow or FindWindowEx to search for a known window that your application opens. If that window is already open, you can use that as an indication that the application is already running.
  • Create a mutex or semaphore object when your application is opened, and close that object when the application terminates. The global object namespace is separated for each desktop, allowing a unique list of mutex and semaphore objects for each.

Shutting Down Your Application Across All Sessions

An application might need to shut itself down across all sessions. For example, an application running in two or more sessions simultaneously might download a new file from the Web. Then it might need to close itself and restart with the updated bits. This, of course, would need to be done in all running sessions. Your application should be written so that it exits cleanly when a notification is received.

Interaction with System Services

From a programmatic standpoint, the following cases need to be addressed.

  • The server process receives a direct request from a client process.

    In this case, the message is probably transmitted using a local procedure call (LPC) or a remote procedure call (RPC). There are application programming interfaces (APIs) for either LPC or RPC that will enable retrieval of the client token. Once the client token is obtained, the server can use it in a call to CreateProcessAsUser. This will bring up the process on the correct window station, assuming that the client user token has a session tag, which it should.

    Note CreateProcessAsUser does not support handle inheritance across sessions at this time.

  • The server process receives a notification and needs to display the user interface (UI), but the display does not have to be in the current user's context.

    In this case, the server process can duplicate its primary process token and change the session identifier in question to match the current session identifier. The current session identifier can be obtained by using the WTSGetActiveConsoleSessionID function. See the MSDN Library Terminal Services API Reference section for more details on this function.

    Note To set the token session ID, you need the SE_TCB_PRIVILEGE. You will have this only as a service running in NT AUTHORITY\SYSTEM.

Remote Desktop and Bandwidth

With the addition of the Remote Desktop feature to Whistler, applications should make an effort not to use more bandwidth than needed, avoiding extensive screen drawings and animation effects if the desktop is connected remotely. To determine whether the current session is remote, you can call GetSystemMetrics(SM_REMOTESESSION). Be aware, however, that this call does not distinguish between remote and disconnected.


Shell Basics

The Microsoft® Windows® user interface (UI) gives users access to a wide variety of objects necessary for running applications and managing the operating system. The most numerous and familiar of these objects are the folders and files that reside on computer disk drives. There are also a number of virtual objects that allow the user to do tasks, such as send files to remote printers or access the Recycle Bin.

The Shell organizes these objects into a hierarchical structure called the namespace, which provides users and applications with a consistent and efficient way to access and manage objects. Users interact with the namespace through the Shell's graphical UI or through an application. Applications interact with the namespace through the Shell's application programming interface (API). This section is an introduction to the Shell API.

The Shell API consists of a collection of functions, Component Object Model (COM) interfaces, and COM objects that provide applications with a rich set of tools to access and manage the namespace. The Shell API can be used anywhere in an application, with one important exception: Like all COM-based services, the Shell API should not be used within a DLL's DllMain entry point function. Doing so can cause unpredictable behavior.

To use the Shell API effectively in an application, you should first read the Shell Namespace section. This document describes the structure of the namespace and how namespace objects are identified.

Programming the Shell

The Shell API allows applications to perform a variety of tasks. Some of the more common tasks are discussed in the following documentation.

  • Getting a Folder's ID
  • Getting Information About the Contents of a Folder
  • Navigating the Namespace
  • Launching Applications
  • Managing the File System
  • Managing Printers
  • Transferring Shell Objects with Drag-and-Drop and the Clipboard
  • Debugging with the Shell
  • Scriptable Shell Objects

Extending the Shell

By integrating your application with the Shell, you can extend the Shell's functionality and customize certain aspects of its behavior. In order of increasing complexity, you can extend the Shell by:

  • Putting information in the registry or in special files.
  • Implementing a Shell extension handler.
  • Implementing a namespace extension.

The first approach, which is used by many applications, is discussed in the following documentation.

  • Creating a File Association
  • Customizing Icons
  • Extending Shortcut Menus
  • Customizing Folders with Desktop.ini
  • Creating an AutoRun-enabled CD-ROM Application
  • Using AutoPlay

For a discussion of how to write extension handlers, see Creating Shell Extension Handlers. For a discussion of how to write namespace extensions, see Creating a Shell Namespace Extension.

Note To improve the readability of the sample code in the Shell Basics documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values and data are in a normal font.


The Shell Namespace

The Shell namespace organizes the file system and other objects managed by the Shell into a single tree-structured hierarchy. Conceptually, it is a larger and more inclusive version of the file system.

  • Introduction
  • Identifying Namespace Objects

Introduction

One of the primary responsibilities of the Shell is managing and providing access to the wide variety of objects that make up the system. The most numerous and familiar of these objects are the folders and files that reside on computer disk drives. However, the Shell manages a number of nonfile system, or virtual objects, as well. Some examples include:

  • Network printers
  • Other networked computers
  • Control Panel applications
  • The Recycle Bin

Some virtual objects do not involve physical storage at all. The printer object, for instance, contains a collection of links to networked printers. Other virtual objects, such as the Recycle Bin, may contain data that is stored on a disk drive, but needs to be handled differently than normal files. For example, a virtual object can be used to represent data stored in a database. In terms of the namespace, the various items in the database could appear in the Windows Explorer as separate objects, even though they are all stored in a single disk file.

Virtual objects may even be located on remote computers. For instance, to facilitate roaming, a user's document files might be stored on a server. To give users access to their files from multiple desktop PCs, the My Documents folder on the desktop PC they are currently using will point to the server, not the hard disk of the desktop PC. Its path will include either a mapped network drive or a UNC path name.

Like the file system, the namespace includes two basic types of object: folders and files. Folder objects are the nodes of the tree; they are containers for file objects and other folders. File objects are the leaves of the tree; they are either normal disk files or virtual objects, such as printer links. Folders that are not part of the file system are sometimes referred to as virtual folders.

Like file system folders, the collection of virtual folders generally varies from system to system. There are three classes of virtual folders:

  • Standard virtual folders, such as the Recycle Bin, that are found on all systems.
  • Optional virtual folders that have standard names and functionality, but may not be present on all systems.
  • Non-standard folders that are installed by the user.

Unlike file system folders, users cannot create new virtual folders themselves. They can only install ones created by third-party developers. The number of virtual folders is thus normally much fewer than the number of file system folders. For a discussion of how to implement virtual folders see Creating a Shell Namespace Extension.

You can see a visual representation of how the namespace is structured in the Explorer Bar of the Windows Explorer. For example, the following screenshot of Windows Explorer shows a relatively simple namespace.

A view of the Shell namespace

The ultimate root of the namespace hierarchy is the desktop. Immediately below the root are several virtual folders such as My Computer and the Recycle Bin.

The file systems of the various disk drives can be seen to be subsets of the larger namespace hierarchy. The roots of these file systems are subfolders of the My Computer folder. My Computer also includes the roots of any mapped network drives. Other nodes in the tree, such as My Documents, are virtual folders.

Identifying Namespace Objects

Before you can use a namespace object, you must first have a way of identifying it. An object in the file system could have a name such as MyFile.htm. Because there might be other files with that name elsewhere in the system, uniquely identifying a file or folder requires a fully-qualified path such as "C:\MyDocs\MyFile.htm". This path is basically an ordered list of all folders in a path from the file system root, C:\, ending with the file.

In the context of the namespace, paths are still quite useful for identifying objects located in the file system part of the namespace. However, they cannot be used for virtual objects. Instead, the Shell provides an alternative means of identification that can be used with any namespace object.

Item IDs

Within a folder, each object has an item ID, which is the functional equivalent of a file or folder name. The item ID is actually a SHITEMID structure:

typedef struct _SHITEMID {
    USHORT cb;
    BYTE   abID[1];
} SHITEMID, * LPSHITEMID;

The abID member is the object's identifier. The length of abID is not defined, and its value is determined by the folder that contains the object. Because there is no standard definition for how abID values are assigned by folders, they are only meaningful to the associated folder object. Applications should simply treat them as a token that identifies an object in a particular folder. Because the length of abID varies, the cb member holds the size of the SHITEMID structure, in bytes.

Because item IDs aren't useful for display purposes, the folder that contains the object normally assigns it a display name. This is the name that is used by Windows Explorer when it displays the contents of a folder. For more information on how display names are handled, see Getting Information From a Folder.

Item ID Lists

The item ID is rarely used by itself. Normally, it is part of an item ID list, which serves the same purpose as a file system path. However, instead of the character string used for paths, an item ID list is an ITEMIDLIST structure. This structure is an ordered sequence of one or more item IDs, terminated by a two-byte NULL. Each item ID in the item ID list corresponds to a namespace object. Their order defines a path in the namespace, much like a file system path.

The following illustration shows a schematic representation of the ITEMIDLIST structure that corresponds to C:\MyDocs\MyFile.htm. The display name of each item ID is shown above it. The varying widths of the abID members are arbitrary; they illustrate the fact that the size of this member can vary.

A schematic illustration of a PIDL

PIDLs

For the Shell API, namespace objects are usually identified by a pointer to their ITEMIDLIST structure, or PIDL. For convenience, the term PIDL will generally refer in this documentation to the structure itself rather than the pointer to it.

The PIDL shown in the preceding illustration is referred to as a full, or absolute, PIDL. A full PIDL starts from the desktop, and contains the item IDs of all intermediate folders in the path. It ends with the object's item ID followed by a terminating two-byte NULL. A full PIDL is similar to a fully qualified path and uniquely identifies the object in the Shell namespace.

Full PIDLs are used infrequently. Many functions and methods expect a relative PIDL. The root of a relative PIDL is a folder, not the desktop. As with relative paths, the series of item IDs that make up the structure define a path in the namespace between two objects. Although they do not uniquely identify the object, they are usually smaller than a full PIDL and sufficient for many purposes.

The most commonly used relative PIDLs, single-level PIDLs, are relative to the object's parent folder. They contain only the object's item ID and a terminating NULL. Multi-level PIDLs are also used for many purposes. They contain two or more item IDs and typically define a path from a parent folder to an object through a series of one or more subfolders. Note that a single-level PIDL can still be a fully-qualified PIDL. In particular, desktop objects are children of the desktop, so their fully-qualified PIDLs contain only one item ID.

As discussed in Getting a Folder's ID, the Shell API provides a number of ways to retrieve an object's PIDL. Once you have it, you commonly just use it to identify the object when you call other Shell API functions and methods. In this context, a PIDL's internal contents are opaque and irrelevant. For the purposes of this discussion, think of PIDLs as tokens that represent particular namespace objects, and focus on how to use them for common tasks.

Allocating PIDLs

Although PIDLs have some similarity to paths, using them requires a somewhat different approach. The primary difference is in how to allocate and deallocate memory for them.

Like the string used for a path, memory must be allocated for a PIDL. If an application creates a PIDL, it must allocate sufficient memory for the ITEMIDLIST structure. For most of the cases discussed here, the Shell creates the PIDL and handles memory allocation. Regardless of what allocated the PIDL, the application is usually responsible for deallocating the PIDL when it is no longer needed.

To allocate and deallocate PIDLs, you must use the IMalloc interface exposed by the Shell's allocator. To retrieve a pointer to this interface, call SHGetMalloc. Use the IMalloc::Alloc method to allocate the PIDL, and the IMalloc::Free method to deallocate it. For an example of how to use this interface to handle Shell memory allocation, see Getting a Folder's ID.


Shell Basics: Programming the Shell

The Shell API allows applications to perform a variety of tasks. Some of the more common tasks are discussed in the following documentation.

  • Getting a Folder's ID
  • Getting Information About the Contents of a Folder
  • Navigating the Namespace
  • Launching Applications
  • Managing the File System
  • Managing Printers
  • Transferring Shell Objects with Drag-and-Drop and the Clipboard
  • Debugging with the Shell
  • Scriptable Shell Objects

Note To improve the readability of the sample code in the Shell Basics documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values are in a normal font.


Getting a Folder's ID

Before you can make use of a namespace object, you need a way to identify it. This means obtaining either its PIDL or, in the case of file system objects, its path. This section discusses two of the simpler ways to obtain object IDs.

  • The SHBrowseForFolder Dialog Box
  • Special Folders and CSIDLs
  • A Simple Example of how to Use CSIDLs and SHBrowseForFolder

For a more powerful approach that will work with any folder, use the IShellFolder interface. See Getting Information About the Contents of a Folder for more details.

The SHBrowseForFolder Dialog Box

To enable the user to navigate the namespace and select a folder, your application can simply invoke SHBrowseForFolder. Calling this function launches a dialog box with a user interface (UI) that works somewhat like the Open or SaveAs common dialog boxes.

When the user selects a folder, SHBrowseForFolder returns the folder's fully-qualified PIDL and its display name. If the folder is in the file system, the application can convert the PIDL to a path by calling SHGetPathFromIDList. The application can also restrict the range of folders that the user can select from by specifying a root folder. Only folders that are below that root in the namespace will appear. The following illustration shows the SHBrowseForFolder dialog box, with the root folder set to Program Files.

A simple example of how to use SHBrowseForFolder is provided later.

Special Folders and CSIDLs

A number of commonly used folders are designated as special by the system. These folders have a well-defined purpose, and most of them are present on all systems. Even if they are not present initially, their names and locations are still defined, so they can be added later. The collection of special folders includes all of the system's standard virtual folders, such as Printers, My Documents, and Network Neighborhood. It also includes a number of standard file system folders, such as Program Files and System.

Even though the folders are a standard component of all systems, their names and locations in the namespace can vary. For example, the System directory is C:\Winnt\System32 on some systems and C:\Windows\System32 on others. In the past, environment variables provided a way to determine the name and location of a special folder on any particular system. The Shell now provides a more robust and flexible way to identify special folders, CSIDLs. You should generally use them instead of environment variables.

CSIDLs provide a uniform way of identifying and locating special folders, regardless of their name or location on a particular system. Unlike environment variables, CSIDLs can be used with virtual folders as well as file system folders. Each special folder has a unique CSIDL assigned to it. For example, the Program Files file system folder has a CSIDL of CSIDL_PROGRAM_FILES, and the Network Neighborhood virtual folder has a CSIDL of CSIDL_NETWORK.

A CSIDL is used in conjunction with one of several Shell functions to retrieve a special folder's PIDL, or a special file system folder's path. If the folder doesn't exist on a system, your application can force it to be created by combining its CSIDL with CSIDL_FLAG_CREATE. The CSIDL can be passed to the following functions:

  • SHGetFolderLocation, which retrieves the PIDL of a special folder.
  • SHGetFolderPath, which retrieves the path of a file system special folder.

Note that these two functions were introduced with version 5.0 of the Shell and supersede the SHGetSpecialFolderLocation and SHGetSpecialFolderPath functions. To use SHGetFolderPath with earlier versions of the Shell, you can include the redistributable DLL, Shfolder.dll.

A Simple Example of How to Use CSIDLs and SHBrowseForFolder

The following sample function, PidlBrowse, illustrates how retrieve a pointer to the Shell allocator's IMalloc interface, use CSIDLs to retrieve a folder's PIDL, and use SHBrowseForFolder to have the user select a folder. It returns the PIDL and display name of the selected folder.

LPITEMIDLIST PidlBrowse(HWND hwnd, int nCSIDL, LPSTR pszDisplayName)
{
    LPITEMIDLIST pidlRoot = NULL;
    LPITEMIDLIST pidlSelected = NULL;
    BROWSEINFO bi = {0};
    LPMALLOC pMalloc = NULL;

    SHGetMalloc(&pMalloc);

    if(nCSIDL)
    {
        SHGetFolderLocation(hwnd, nCSIDL, NULL, NULL, &pidlRoot);
    }

    else
    {
        pidlRoot = NULL;
    }

    bi.hwndOwner = hwnd;
    bi.pidlRoot = pidlRoot;
    bi.pszDisplayName = pszDisplayName;
    bi.lpszTitle = "Choose a folder";
    bi.ulFlags = 0;
    bi.lpfn = NULL;
    bi.lParam = 0;

    pidlSelected = SHBrowseForFolder(&bi);

    if(pidlRoot)
    {
        pMalloc->Free(pidlRoot);
    }
    pMalloc->Release();
    return pidlSelected;
}

The calling application passes in a window handle, which is needed by SHBrowseForFolder. The nCSIDL parameter is an optional CSIDL that is used to specify a root folder. Only folders below the root folder in the hierarchy will be displayed. The illustration shown earlier was generated by calling this function with nCSIDL set to CSIDL_PROGRAM_FILES. The calling application also passes in a string buffer, pszDisplayName, to hold the display name of the selected folder when PidlBrowse returns.

PidlBrowse first calls SHGetMalloc to retrieve a pointer to the Shell's allocator. Although no PIDLs are allocated by the function itself, the IMalloc interface will be needed later to deallocate them. If the calling application specifies a root folder by passing in its CSIDL, PidlBrowse calls SHGetFolderLocation to retrieve the folder's PIDL. The function then assigns appropriate values to a BROWSEINFO structure, and passes it to SHBrowseForFolder.

After the user selects a folder, SHBrowseForFolder returns its PIDL. The folder's display name is returned in the pszDisplayName member of the BROWSEINFO structure, and is passed back to the calling application through the pszDisplayName parameter. Finally, PidlBrowse deallocates the root PIDL, releases the IMalloc interface, and returns the selected folder's PIDL to the calling application.


Getting Information About the Contents of a Folder

The Getting a Folder's ID section discussed two approaches to getting a namespace object's PIDL. One obvious question is: Once you have a PIDL, what can you do with it? A related question is: What if neither approach works, or is suitable for your application? The answer to both questions requires taking a closer look at how the namespace is implemented. The key is the the IShellFolder interface.

  • Using the IShellFolder Interface
  • Enumerating the Contents of a Folder
  • Determining Display Names and Other Properties
  • Getting a Pointer to a Subfolder's IShellFolder Interface
  • Determining an Object's Parent Folder

Using the IShellFolder Interface

Earlier in this documentation, namespace folders were referred to as objects. Although, at that point, the term was used in a loose sense, it is actually true in a strict sense as well. Every namespace folder is represented by a Component Object Model (COM) object. Each folder object exposes a number of interfaces that can be used for a wide variety of tasks. Some interfaces that are optional may not be exposed by all folders. However, all folders must expose the fundamental interface, IShellFolder.

The first step in using a folder object is to retrieve a pointer to its IShellFolder interface. In addition to providing access to the object's other interfaces, IShellFolder exposes a group of methods that handle a number of common tasks, several of which are discussed in this section.

To retrieve a pointer to a namespace object's IShellFolder interface, you must first call SHGetDesktopFolder. This function returns a pointer to the IShellFolder interface of the namespace root, the desktop. Once you have the desktop's IShellFolder interface, there a variety of ways to proceed.

If you already have the PIDL of the folder you are interested in—for instance, by calling SHGetFolderLocation—you can retrieve its IShellFolder interface by calling the desktop's IShellFolder::BindToObject method. If you have the path of a file system object, you must first obtain its PIDL by calling the desktop's IShellFolder::ParseDisplayName method and then call IShellFolder::BindToObject. If neither of these approaches is applicable, you can use other IShellFolder methods to navigate the namespace. For more information, see Navigating the Namespace.

Enumerating the Contents of a Folder

The first thing you usually want to do with a folder is to find out what it contains. You must first call the folder's IShellFolder::EnumObjects method. The folder will create a standard OLE enumeration object and return its IEnumIDList interface. This interface exposes four standard methods—Clone, Next, Reset, and Skip—that can be used to enumerate the contents of the folder.

The basic procedure for enumerating a folder's contents is:

  1. Call the folders IShellFolder::EnumObjects method to retrieve a pointer to an enumeration object's IEnumIDList interface.
  2. Pass an unallocated PIDL to IEnumIDList::Next. Next takes care of allocating the PIDL, but the application must deallocate it when it is no longer needed. When Next returns, the PIDL will contain just the object's item ID and the terminating NULLs. In other words, it is a single-level PIDL, relative to the folder, not a fully-qualified PIDL.
  3. Repeat step 2 until Next returns S_FALSE to indicate that all items have been enumerated.
  4. Call IEnumIDList::Release to release the enumeration object.

Note: It is important to keep track of whether you are working with a full or relative PIDL. Some functions and methods will accept either, but others will only take one or the other.

The remaining three IEnumIDList methods (Reset, Skip, and Clone) are useful if you need to do repeated enumerations of the folder. They allow you to reset the enumeration, skip one or more objects, and make a copy of the enumeration object to preserve its state.

Determining Display Names and Other Properties

Once you have enumerated all the PIDLs that are contained by a folder, you can find out what sort of objects they represent. The IShellFolder interface provides a number of useful methods, two of which are discussed here. Other IShellFolder methods and other Shell folder interfaces are discussed later.

One of the most useful properties is the object's display name. To retrieve the display name of an object, pass its PIDL to IShellFolder::GetDisplayNameOf. Although the object can be located anywhere below the parent folder in the namespace, its PIDL must be relative to the folder.

IShellFolder::GetDisplayNameOf returns the display name as part of of a STRRET structure. Because extracting the display name from a STRRET structure can be a little tricky, the Shell provides two functions that do the job for you, StrRetToStr and StrRetToBuf. Both functions take a STRRET structure, and return the display name as a normal string. They differ only in how the string is allocated.

In addition to its display name, an object can have a number of attributes, such as whether it is a folder or whether it can be moved. You can retrieve an object's attributes by passing its PIDL to IShellFolder::GetAttributesOf. The complete list of attributes is quite large, so you should see the reference for details. Note that the PIDL that you pass to GetAttributesOf must be single-level. In particular, IShellFolder::GetAttributesOf will accept the PIDLs returned by IEnumIDList::Next. You can pass in an array of PIDLs, and GetAttributesOf will return those attributes that all objects in the array have in common.

If you have an object's fully-qualified path or PIDL, SHGetFileInfo provides a simple way to retrieve information about an object that is sufficient for many purposes. SHGetFileInfo takes a fully-qualified path or PIDL, and returns a variety of information about the object including:

  • The object's display name
  • The object's attributes
  • Handles to the object's icons
  • A handle to the system image list
  • The path of the file containing the object's icon

Getting a Pointer to a Subfolder's IShellFolder Interface

You can determine whether your folder contains any subfolders by calling IShellFolder::GetAttributesOf and checking to see if the SFGAO_FOLDER flag is set. If an object is a folder, you can bind to it, which provides you with a pointer to its IShellFolder interface.

To bind to a subfolder, call the parent folder's IShellFolder::BindToObject method. This method takes the subfolder's PIDL and returns a pointer to its IShellFolder interface. Once you have this pointer, you can use the IShellFolder methods to enumerate the subfolders contents, determine their properties, and so on.

Determining an Object's Parent Folder

If you have an object's PIDL, you may need a handle to one of the interfaces exposed by its parent folder. For example, if you want to determine the display name associated with a PIDL by using IShellFolder::GetDisplayNameOf, you must first retrieve the IShellFolder interface of the object's parent. It is possible to do this with the techniques discussed in the previous sections. However, a much simpler approach is to use the Shell function, SHBindToParent. This function takes the fully-qualified PIDL of an object and returns a specified interface pointer on the parent folder. Optionally, it also returns the item's single-level PIDL for use in methods such as IShellFolder::GetAttributesOf.

The following sample console application retrieves the PIDL of the System special folder and returns its display name.

#include <shlobj.h>
#include <shlwapi.h>
#include <iostream.h>

int main()
{
    LPMALLOC pMalloc = NULL;
    IShellFolder *psfParent = NULL;
    LPITEMIDLIST pidlSystem = NULL;
    LPCITEMIDLIST pidlRelative = NULL;
    STRRET strDispName;
    TCHAR szDisplayName[MAX_PATH];
    HRESULT hr;

    hr = SHGetMalloc(&pMalloc);

    hr = SHGetFolderLocation(NULL, CSIDL_SYSTEM, NULL, NULL, &pidlSystem);

    hr = SHBindToParent(pidlSystem, IID_IShellFolder, (void **) &psfParent, &pidlRelative);

    if(SUCCEEDED(hr))
    {
        hr = psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL, &strDispName);
        hr = StrRetToBuf(&strDispName, pidlSystem, szDisplayName, sizeof(szDisplayName));
        cout << "SHGDN_NORMAL - " <<szDisplayName << '\n';
    }

    psfParent->Release();
    pMalloc->Free(pidlSystem);
    pMalloc->Release();

    return 0;
}

The application first retrieves a pointer to the Shell allocator's Imalloc interface and uses SHGetFolderLocation to retrieve the System folder's PIDL. It then calls SHBindToParent, which returns a pointer to the parent folder's IShellFolder interface, and the System folder's PIDL relative to its parent. It then uses the parent folder's IShellFolder::GetDisplayNameOf method to retrieve the display name of the System folder. Because GetDisplayNameOf returns a STRRET structure, StrRetToBuf is used to convert the display name into a normal string. After displaying the display name, the interface pointers are released and the System PIDL freed. Note that you must not free the relative PIDL returned by SHBindToParent.


Navigating the Namespace

You now have all the essential elements needed to navigate anywhere in the namespace. The simplest way to start is to have your application call SHGetDesktopFolder to retrieve the desktop's IShellFolder interface. Then, to navigate downward through the namespace, your application can follow these steps:

  1. Enumerate the folder's contents.
  2. Determine which objects are subfolders, and select one.
  3. Bind to the subfolder to retrieve its IShellFolder interface.

Repeat these steps as often as necessary to reach the target.

A Simple Example of Namespace Navigation

The following piece of sample code is a simple console application that illustrates a number of the procedures discussed in the preceding sections. Error checking has been omitted for clarity. The application performs the following tasks:

  1. Retrieves the Program Files folder's IShellFolder interface (Using the IShellFolder Interface).
  2. Enumerates the contents of the folder (Enumerating the Contents of a Folder).
  3. Determines all the display names and prints them (Determining Display Names and Other Properties).
  4. Looks for a subfolder (Determining Display Names and Other Properties).
  5. Binds to the first subfolder it finds (Getting a Pointer to a Subfolder's IShellFolder Interface).
  6. Prints the display names of the objects in the subfolder.
#include <shlobj.h>
#include <shlwapi.h>
#include <iostream.h>

main()
{
    LPMALLOC pMalloc;
    LPITEMIDLIST pidlProgFiles = NULL;
    LPITEMIDLIST pidlItems = NULL;
    IShellFolder *psfFirstFolder = NULL;
    IShellFolder *psfDeskTop = NULL;
    IShellFolder *psfProgFiles = NULL;
    LPENUMIDLIST ppenum = NULL;
    ULONG celtFetched;
    HRESULT hr;
    STRRET strDispName;
    TCHAR pszDisplayName[MAX_PATH];
    ULONG uAttr;

    CoInitialize( NULL );
    hr = SHGetMalloc(&pMalloc);

    hr = SHGetFolderLocation(NULL, CSIDL_PROGRAM_FILES, NULL, NULL, &pidlProgFiles);

    hr = SHGetDesktopFolder(&psfDeskTop);

    hr = psfDeskTop->BindToObject(pidlProgFiles, NULL, IID_IShellFolder, (LPVOID *) &psfProgFiles);
    psfDeskTop->Release();

    hr = psfProgFiles->EnumObjects(NULL,SHCONTF_FOLDERS | SHCONTF_NONFOLDERS, &ppenum);

    while( hr = ppenum->Next(1,&pidlItems, &celtFetched) == S_OK && (celtFetched) == 1)
    {
        psfProgFiles->GetDisplayNameOf(pidlItems, SHGDN_INFOLDER, &strDispName);
        StrRetToBuf(&strDispName, pidlItems, pszDisplayName, MAX_PATH);
        cout << pszDisplayName << '\n';
        if(!psfFirstFolder)
        {
            uAttr = SFGAO_FOLDER;
            psfProgFiles->GetAttributesOf(1, (LPCITEMIDLIST *) &pidlItems, &uAttr);
            if(uAttr & SFGAO_FOLDER)
            {
                hr = psfProgFiles->BindToObject(pidlItems, NULL, IID_IShellFolder, (LPVOID *) &psfFirstFolder);
            }
        }
        pMalloc->Free(pidlItems);
    }

    cout << "\n\n";

    ppenum->Release();

    if(psfFirstFolder)
    {
        hr = psfFirstFolder->EnumObjects(NULL,SHCONTF_FOLDERS | SHCONTF_NONFOLDERS, &ppenum);

        while( hr = ppenum->Next(1,&pidlItems, &celtFetched) == S_OK && (celtFetched) == 1)
        {
            psfFirstFolder->GetDisplayNameOf(pidlItems, SHGDN_INFOLDER, &strDispName);
            StrRetToBuf(&strDispName, pidlItems, pszDisplayName, MAX_PATH);
            cout << pszDisplayName << '\n';
            pMalloc->Free(pidlItems);
        }
    }

    ppenum->Release();
    pMalloc->Free(pidlProgFiles);
    psfProgFiles->Release();
    psfFirstFolder->Release();

    CoUninitialize();
    return 0;
}


Launching Applications

Once your application has located a file object, the next step is often to act on it in some way. For instance, your application might want to launch another application that allows the user to modify a data file. If the file of interest is an executable, your application might want to simply launch it. This document discusses how to use ShellExecute or ShellExecuteEx to perform these tasks.

  • Using ShellExecute and ShellExecuteEx
  • A Simple Example of How to Use ShellExecuteEx

Using ShellExecute and ShellExecuteEx

To use ShellExecute or ShellExecuteEx, your application must specify the file or folder object that is to be acted on, and a verb that specifies the operation. For ShellExecute, assign these values to the appropriate parameters. For ShellExecuteEx, fill in the appropriate members of a SHELLEXECUTEINFO structure. There are also several other members or parameters that can be used to fine-tune the behavior of the two functions.

File and folder objects can be part of the file system or virtual objects, and they can be identified by either paths or PIDLs.

Object Verbs

The verbs available for an object are essentially the items that you find on an object's shortcut menu. To find which verbs are available, look in the registry under

HKEY_CLASSES_ROOT\CLSID\{object_clsid}\Shell\verb

where object_clsid is the CLSID of the object, and verb is the name of the available verb. The verb\Command subkey contains the data indicating what happens when that verb is invoked.

To find out which verbs are available for predefined Shell objects, look in the registry under

HKEY_CLASSES_ROOT\object_name\Shell\verb

where object_name is the name of the predefined Shell object. Again, the verb\Command subkey contains the data indicating what happens when that verb is invoked.

Commonly available verbs include:

Verb | Description
edit | Launches an editor and opens the document for editing.
find | Initiates a search starting from the specified directory.
open | Launches an application. If this file is not an executable file, its associated application is launched.
print | Prints the document file.
properties | Displays the object's properties.

Each verb corresponds to the command that would be used to launch the application from a console window. The open verb is a good example, as it is commonly supported. For .exe files, open simply launches the application. However, it is more commonly used to launch an application that operates on a particular file. For instance, .txt files can be opened by WordPad. The open verb for a .txt file would thus correspond to something like the following command:

"C:\Program Files\Windows NT\Accessories\Wordpad.exe" "%1"

When you use ShellExecute or ShellExecuteEx to open a .txt file, Wordpad.exe is launched with the specified file as its argument. Some commands can have additional arguments, such as flags, that can be added as needed to launch the application properly. For further discussion of shortcut menus and verbs, see Extending Shortcut Menus.

In general, trying to determine the list of available verbs for a particular file is somewhat complicated. In many cases, you can simply set the lpVerb parameter to NULL, which invokes the default command for the file class. This procedure is usually equivalent to setting lpVerb to "open", but some file classes may have a different default command. For further information, see Extending Shortcut Menus and the ShellExecuteEx reference documentation.

Using ShellExecute to Launch the Find Dialog Box

When a user right-clicks a folder icon in Windows Explorer, one of the menu items is "Find". If they select that item, the Shell launches its Find utility. This utility displays a dialog box that can be used to search files for a specified text string. An application can programmatically launch the Find utility for a directory by calling ShellExecute, with "find" as the lpVerb parameter, and the directory path as the lpFile parameter. For instance, the following line of code launches the Find utility for the c:\MyPrograms directory.

ShellExecute(hwnd,"find","c:\\MyPrograms",NULL, NULL, 0);

A Simple Example of How to Use ShellExecuteEx

The following sample console application illustrates the use of ShellExecuteEx. Most error checking code has been omitted for clarity.

#include <shlobj.h>
#include <shlwapi.h>

main()
{
    LPMALLOC pMalloc;
    LPITEMIDLIST pidlWinFiles = NULL;
    LPITEMIDLIST pidlItems = NULL;
    IShellFolder *psfWinFiles = NULL;
    IShellFolder *psfDeskTop = NULL;
    LPENUMIDLIST ppenum = NULL;
    STRRET strDispName;
    TCHAR pszParseName[MAX_PATH];
    ULONG celtFetched;
    SHELLEXECUTEINFO ShExecInfo;
    HRESULT hr;
    BOOL fBitmap = FALSE;

    hr = SHGetMalloc(&pMalloc);

    hr = SHGetFolderLocation(NULL, CSIDL_WINDOWS, NULL, NULL, &pidlWinFiles);

    hr = SHGetDesktopFolder(&psfDeskTop);

    hr = psfDeskTop->BindToObject(pidlWinFiles, NULL, IID_IShellFolder, (LPVOID *) &psfWinFiles);
    hr = psfDeskTop->Release();

    hr = psfWinFiles->EnumObjects(NULL,SHCONTF_FOLDERS | SHCONTF_NONFOLDERS, &ppenum);

    while( hr = ppenum->Next(1,&pidlItems, &celtFetched) == S_OK && (celtFetched) == 1)
    {
        psfWinFiles->GetDisplayNameOf(pidlItems, SHGDN_FORPARSING, &strDispName);
        StrRetToBuf(&strDispName, pidlItems, pszParseName, MAX_PATH);
        pMalloc->Free(pidlItems);
        if(StrCmpI(PathFindExtension(pszParseName), TEXT( ".bmp")) == 0)
        {
            fBitmap = TRUE;
            break;
        }
    }

    ppenum->Release();

    if(fBitmap)
    {
        ShExecInfo.cbSize = sizeof(SHELLEXECUTEINFO);
        ShExecInfo.fMask = NULL;
        ShExecInfo.hwnd = NULL;
        ShExecInfo.lpVerb = NULL;
        ShExecInfo.lpFile = pszParseName;
        ShExecInfo.lpParameters = NULL;
        ShExecInfo.lpDirectory = NULL;
        ShExecInfo.nShow = SW_MAXIMIZE;
        ShExecInfo.hInstApp = NULL;

        ShellExecuteEx(&ShExecInfo);
    }

    pMalloc->Free(pidlWinFiles);
    psfWinFiles->Release();

    return 0;
}

The application first retrieves the PIDL of the Windows directory, and enumerates its contents until it finds the first .bmp file. Unlike the earlier example, IShellFolder::GetDisplayNameOf is used to retrieve the file's parsing name instead of its display name. Because this is a file system folder, the parsing name is a fully qualified path, which is what is needed for ShellExecuteEx.

Once the first .bmp file has been located, appropriate values are assigned to the members of a SHELLEXECUTEINFO structure. The lpFile member is set to the parsing name of the file, and the lpVerb member to NULL, to begin the default operation. In this case, the default operation is "open". The structure is then passed to ShellExecuteEx, which launches the default handler for bitmap files, typically MSPaint.exe, to open the file. After the function returns, the PIDLs are freed and the Windows folder's IShellFolder interface is released.


Managing the File System

The Shell provides a number of ways to manage file systems. The Shell provides a function, SHFileOperation, that allows an application to programmatically move, copy, rename, and delete files. The Shell also supports some additional file management capabilities:

  • HTML documents can be connected to related files, such as graphics files or style sheets. When the document is moved or copied, the connected files are automatically moved or copied as well.
  • For systems that are available to more than one user, files can be managed on a per-user basis. Users have easy access to their data files, but not to files belonging to other users.
  • If document files are added or modified, they can be added to the Shell's list of recent documents. When the user clicks the Documents command on the Start menu, a list of links to the documents appears.

This document discusses how these new file management technologies work. It then outlines how to use the Shell to move, copy, rename, and delete files, and how to manage objects in the Recycle Bin.

  • Per-User File Management
  • My Documents and My Pictures Folders
  • Connected Files
  • Moving, Copying, Renaming, and Deleting Files
  • Simple Example of Managing Files with SHFileOperation
  • Adding Files to the Shell's List of Recent Documents

Per-User File Management

The Microsoft® Windows® 2000 Shell allows files to be associated with a particular user so the files remain hidden from other users. In terms of the file system, the files are stored under the user's profile folder, typically C:\Documents and Settings\Username\ on Windows 2000 systems. This feature allows many individuals to use the same computer, while maintaining the privacy of their files from other users. Different users can have different programs available. It also provides a straightforward way for administrators and applications to store such things as initialization (.ini) or link (.lnk) files. Applications can thus preserve a different state for each user and easily recover that particular state when needed. There is also a profile folder for storing information that is common to all users.

Because it is inconvenient to determine which user is logged in and where their files are located, the standard per-user folders are special folders and are identified by a CSIDL. For instance, the CSIDL for the per-user Program Files folder is CSIDL_PROGRAMS. If your application calls SHGetFolderLocation or SHGetFolderPath with one of the per-user CSIDLs, the function returns the PIDL or path appropriate to the currently logged-in user. If your application needs to retrieve the path or PIDL of the profile folder, its CSIDL is CSIDL_PROFILE.

My Documents and My Pictures Folders

One of the standard icons found on the desktop is My Documents. When you open this folder, it contains a user's document files. The My Pictures subfolder contains image files. However, when you use Windows® Explorer to look at the namespace, the My Documents folder is not part of the file system. My Documents is a virtual folder, located immediately below the desktop in the namespace hierarchy. The My Pictures folder is a subfolder of My Documents.

The purpose of the My Documents and My Pictures folders is to provide a straightforward and secure way for users to access their document and picture files on a system that might have multiple users. Each user is assigned separate file system folders for his or her documents and pictures. For example, the location of a user's documents folder in the file system is typically something like C:\Documents and Settings\Username\My Documents. The My Documents and My Pictures virtual folders are automatically mapped to the current user's file system folders. There is thus no need for users to know anything about the location of their file system folders. They simply access their files through My Documents and My Pictures as if they were part of the file system.

Note My Documents allows a user to access his or her own files but not those of any other user. If multiple individuals use the same computer, an administrator can lock users out of the part of the file system where the actual files are stored. Users will thus be able to work on their own documents through the My Documents folder but not on documents that belong to any other users.

There is usually no need for an application to know which user is logged in or where in the file system that user's My Documents folder is located. Instead, your application can retrieve the PIDL of the My Documents desktop icon by calling the desktop's IShellFolder::ParseDisplayName method. The parsing name used to identify the My Documents folder is not a file path but is ::{450d8fba-ad25-11d0-98a8-0800361b1103}. The bracketed expression is the text form of the My Documents GUID. For example, to retrieve the PIDL of My Documents, your application should use:

hr = psfDeskTop->ParseDisplayName(NULL, NULL,
    L"::{450d8fba-ad25-11d0-98a8-0800361b1103}", &chEaten,
    &pidlDocFiles, NULL);

Once your application has the My Documents PIDL, it can handle the folder as it would a normal file system folder. The Shell automatically maps changes in My Documents or its subfolders to the appropriate file system folders.

If your application needs access to the actual file system folder that contains the current user's documents, pass CSIDL_PERSONAL to SHGetFolderLocation. The function returns the PIDL of the file system folder that is displayed in the current user's My Documents folder.

Connected Files

HTML documents often have a number of associated graphics files, a style sheet file, several Microsoft® JScript® (compatible with ECMA 262 language specification) files, and so on. When you move or copy the primary HTML document, you also usually want to move or copy its associated files to avoid breaking links. Unfortunately, there has been no easy way until now to determine which files are related to any given HTML document other than by analyzing their contents. To alleviate this problem, Windows 2000 provides a simple way to connect a primary HTML document to its group of associated files. If file connection is enabled, when the document is moved or copied all its connected files go with it.

To create a group of connected files, the primary document must have an .htm or .html file name extension. Create a subfolder of the primary document's parent folder. The subfolder's name must be the name of the primary document, minus the .htm or .html extension, followed by one of the extensions listed below. The most commonly used extensions are ".files" or "_files". For instance, if the primary document is named MyDoc.htm, naming the subfolder "MyDoc_files" defines the subfolder as the container for the document's connected files. If the primary document is moved or copied, the subfolder and its files are moved or copied as well.

For some languages, it is possible to use a localized equivalent of "_files" to create a subfolder for connected files. The following table lists the valid strings that can be appended to a document name to create a connected files subfolder. Note that some of these strings have '-' as their first character rather than '_' or '.'.

"_archivos" | "_arquivos" | "_bestanden" | "_bylos"
"-Dateien" | "_datoteke" | "_dosyalar" | "_elemei"
"_failid" | "_fails" | "_fajlovi" | "_ficheiros"
"_fichiers" | "-filer" | ".files" | "_files"
"_file" | "_fitxers" | "_fitxategiak" | "_pliki"
"_soubory" | "_tiedostot" |  |

Note This feature is sensitive to the case of the extension. For instance, for the example given above, a subfolder named "MyDoc_Files" will not be connected to MyDoc.htm.

Whether file connection is enabled or disabled is controlled by a REG_DWORD value, NoFileFolderConnection, of the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer registry key. This value normally is not defined, and file connection is enabled. If necessary, you can disable file connection by adding this value to the key and setting it to 1. To enable file connection again, set NoFileFolderConnection to zero.

Note File connection should normally be enabled because other applications might depend on it. Disable file connection only if absolutely necessary.

Moving, Copying, Renaming, and Deleting Files

The namespace is not static, and applications commonly need to manage the file system by performing one of the following operations:

  • Copying an object to another folder.
  • Moving an object to another folder.
  • Deleting an object.
  • Renaming an object.

These operations are all performed with SHFileOperation. This function takes one or more source files and produces corresponding destination files. In the case of the delete operation, the system attempts to put the deleted files into the Recycle Bin.

It is also possible to move files using the drag-and-drop functionality.

To use the function, you must fill in the members of an SHFILEOPSTRUCT structure and pass it to SHFileOperation. The key members of the structure are pFrom and pTo.

The pFrom member is a double NULL-terminated string that contains one or more source file names. These names can be either fully qualified paths or standard DOS wildcards such as *.*. Although this member is declared as a NULL-terminated string, it is used as a buffer to hold multiple file names. Each file name must be terminated by the usual single NULL character. An additional NULL character must be appended to the end of the final name to indicate the end of pFrom.

The pTo member is a double NULL-terminated string, much like pFrom. The pTo member contains the names of one or more fully qualified destination names. They are packed into pTo in the same way as they are for pFrom. If pTo contains multiple names, you must also set the FOF_MULTIDESTFILES flag in the fFlags member. The usage of pTo depends on the operation as described here:

  • For copy and move operations, if all the files are going to a single directory, pTo contains the fully qualified directory name. If the files are going to different destinations, pTo can also contain one fully qualified directory or file name for each source file. If a directory doesn't exist, the system creates it.
  • For rename operations, pTo contains one fully qualified path for each source file in pFrom.
  • For delete operations, pTo is not used.

Notifying the Shell

Notify the Shell of the change after using SHFileOperation to move, copy, rename, or delete files, or after taking any other action that affects the namespace. Actions that should be accompanied by notification include:

  • Adding or deleting files or folders.
  • Moving, copying, or renaming files or folders.
  • Changing a file association.
  • Changing file attributes.
  • Adding or removing drives or storage media.
  • Creating or disabling a shared folder.
  • Changing the system image list.

An application notifies the Shell by calling SHChangeNotify with the details of what has changed. The Shell can then update its image of the namespace to accurately reflect its new state.

Simple Example of Managing Files with SHFileOperation

The following sample console application illustrates the use of SHFileOperation to copy files from one directory to another. The source and destination directories, C:\My_Docs and C:\My_Docs2, are hard-coded into the application for simplicity.

#include <shlobj.h>
#include <shlwapi.h>

main()
{
    IShellFolder *psfDeskTop = NULL;
    IShellFolder *psfDocFiles = NULL;
    IMalloc *pMalloc = NULL;
    LPITEMIDLIST pidlDocFiles = NULL;
    LPITEMIDLIST pidlItems = NULL;
    IEnumIDList *ppenum = NULL;
    SHFILEOPSTRUCT sfo;
    STRRET strDispName;
    TCHAR szParseName[MAX_PATH];
    TCHAR szSourceFiles[256];
    int i;
    int iBufPos = 0;
    ULONG chEaten;
    ULONG celtFetched;
    HRESULT hr;

    pzSourceFiles[0] = '\0';
    hr = SHGetMalloc(&pMalloc);
    hr = SHGetDesktopFolder(&psfDeskTop);

    hr = psfDeskTop->ParseDisplayName(NULL, NULL, L"c:\\My_Docs",
         &chEaten, &pidlDocFiles, NULL);
    hr = psfDeskTop->BindToObject(pidlDocFiles, NULL, IID_IShellFolder,
         (LPVOID *) &psfDocFiles);
    hr = psfDeskTop->Release();

    hr = psfDocFiles->EnumObjects(NULL,SHCONTF_FOLDERS | SHCONTF_NONFOLDERS,
         &ppenum);

    while( (hr = ppenum->Next(1,&pidlItems, &celtFetched)) == S_OK
       && (celtFetched) == 1)
    {
        psfDocFiles->GetDisplayNameOf(pidlItems, SHGDN_FORPARSING,
            &strDispName);
        StrRetToBuf(&strDispName, pidlItems, szParseName, MAX_PATH);
        for(i=0;i<=lstrlen(szParseName); i++)
        {
            szSourceFiles[iBufPos++] = szParseName[i];
        }
        pMalloc->Free(pidlItems);
    }
    ppenum->Release();

    szSourceFiles[iBufPos] = '\0';

    sfo.hwnd = NULL;
    sfo.wFunc = FO_COPY;
    sfo.pFrom = szSourceFiles;
    sfo.pTo = "c:\\My_Docs2\0";
    sfo.fFlags = FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOCONFIRMMKDIR;

    hr = SHFileOperation(&sfo);

    SHChangeNotify(SHCNE_UPDATEDIR, SHCNF_PATH, (LPCVOID) "c:\My_Docs2", 0);

    pMalloc->Free(pidlDocFiles);
    psfDocFiles->Release();

    return 0;
}

The application first retrieves a pointer to the desktop's IShellFolder interface. It then retrieves the source directory's PIDL by passing its fully qualified path to IShellFolder::ParseDisplayName. Note that ParseDisplayName requires the directory's path to be a Unicode string. The application then binds to the source directory and uses its IShellFolder interface to retrieve an enumerator object's IEnumIDList interface.

As each file in the source directory is enumerated, IShellFolder::GetDisplayNameOf is used to retrieve its name. The SHGDN_FORPARSING flag is set, which causes GetDisplayNameOf to return the file's fully qualified path. The file paths, including the terminating NULL characters, are concatenated into a single array, szSourceFiles. A second NULL character is appended to the final path to terminate the array properly.

Once the enumeration is complete, the application assigns values to an SHFILEOPSTRUCT structure. Note that the array assigned to pTo to specify the destination must also be terminated by a double NULL. In this case, it is simply included in the string that is assigned to pTo. Because this is a console application, the FOF_SILENT, FOF_NOCONFIRMATION, and FOF_NOCONFIRMMKDIR flags are set to suppress any dialog boxes that might appear. After SHFileOperation returns, SHChangeNotify is called to notify the Shell of the change. Then the application performs the usual cleanup and returns.

Adding Files to the Shell's List of Recent Documents

The Shell maintains a list of recently added or modified documents for each user. The user can display a list of links to these files by clicking Documents on the Start menu. As with My Documents, each user has a file system directory to hold the actual links. To retrieve the PIDL of the current user's Recent directory, your application can call SHGetFolderLocation with CSIDL_RECENT, or call SHGetFolderPath to retrieve its path.

Your application can enumerate the contents of the Recent folder using the techniques discussed earlier in this document. However, an application should not modify the contents of the folder as if it were a normal file system folder. If it does so, the Shell's list of recent documents will not be updated properly, and the changes will not be reflected in the Start menu. Instead, to add a document link to a user's Recent folder, your application can call SHAddToRecentDocs. The Shell will add a link to the appropriate file system folder, as well as updating its list of recent documents and the Start menu. You can also use this function to clear the folder.


Managing Printers

The Shell Application Programming Interface (API) provides functions that you can use to manage networked printers. If a file has the print verb associated with it, you can use the ShellExecuteEx command to print it. For further discussion of printing, see Printing and Print Spooler.

  • Printer Management
  • Printing Files with ShellExecuteEx

Printer Management

You can manage printers on a system with the SHInvokePrinterCommand function. This function allows you to:

  • Install printers.
  • Open printers.
  • Get printer properties.
  • Create printer links.
  • Print a test page.

Printing Files with ShellExecuteEx

If a file type has a print command associated with it, you can print the file by calling ShellExecuteEx with print as the verb. This command is often the same as that used for the open verb, with the addition of a flag to tell the application to print the file. For instance, .txt files can be printed by WordPad. The open verb for a .txt file would thus correspond to something like the following command:

"C:\Program Files\Windows NT\Accessories\Wordpad.exe" /p "%1"

When you use ShellExecuteEx to print a .txt file, Wordpad opens the file, prints it, and then closes, returning control to the application. The following sample function takes a fully qualified path, and uses ShellExecuteEx to print it, using the print command associated with its file name extension.

#include <shlobj.h>

HINSTANCE PrintFile(LPCTSTR pszFileName)
{
    SHELLEXECUTEINFO ShExecInfo;
    HINSTANCE hInst;

//Fill the SHELLEXECUTEINFO array.

    ShExecInfo.cbSize = sizeof(SHELLEXECUTEINFO);
    ShExecInfo.fMask = NULL;
    ShExecInfo.hwnd = NULL;
    ShExecInfo.lpVerb = "print";
    ShExecInfo.lpFile = pszFileName;
    ShExecInfo.lpParameters = NULL;
    ShExecInfo.lpDirectory = NULL;
    ShExecInfo.nShow = SW_MAXIMIZE;
    ShExecInfo.hInstApp = NULL;

    hInst = ShellExecuteEx(&ShExecInfo);

    return hInst;
}


Transferring Shell Objects with Drag-and-Drop and the Clipboard

Many applications allow users to transfer data to another application by dragging and dropping the data with the mouse, or by using the Clipboard. Among the many types of data that can be transferred are Shell objects such as files or folders. Shell data transfer can take place between two applications, but users can also transfer Shell data to or from the desktop or Microsoft® Windows® Explorer.

Although files are the most commonly transferred Shell object, Shell data transfer can involve any of the variety of objects found in the Shell namespace. For instance, your application might need to transfer a file to a virtual folder such as the Recycle Bin, or accept an object from a third-party namespace extension. If you are implementing a namespace extension, it must be able to behave properly as a drop source and target.

This document discusses how applications can implement drag-and-drop and Clipboard data transfers with Shell objects.

  • The Shell Data Object
  • Shell Clipboard Formats
  • Handling Shell Data Transfer Scenarios

How Drag-and-Drop Works with Shell Objects

Applications often need to provide users with a way to transfer Shell data. Some examples are:

  • Dragging a file from Windows Explorer or the desktop and dropping it on an application.
  • Copying a file to the Clipboard in Windows Explorer and pasting it into an application.
  • Dragging a file from an application to the Recycle Bin.

For a detailed discussion of how to handle these and other scenarios, see Handling Shell Data Transfer Scenarios. This document focuses on the general principles behind Shell data transfer.

Windows provides two standard ways for applications to transfer Shell data:

  • A user cuts or copies Shell data, such as one or more files, to the Clipboard. The other application retrieves the data from the Clipboard.
  • A user drags an icon that represents the data from the source application and drops the icon on a window owned by the target.

In both cases, the transferred data is contained in a data object. Data objects are COM objects that expose the IDataObject interface. Schematically, there are three essential steps that all Shell data transfers must follow:

  1. The source creates a data object that represents the data that is to be transferred.
  2. The target receives a pointer to the data object's IDataObject interface.
  3. The target calls the IDataObject interface to extract the data from it.

The difference between Clipboard and drag-and-drop data transfers lies primarily in how the IDataObject pointer gets from the source to the target.

Clipboard Data Transfers

The Clipboard is the simplest way to transfer Shell data. The basic procedure is similar to standard Clipboard data transfers. However, because you are transferring a pointer to a data object, not the data itself, you must use the OLE clipboard API instead of the standard clipboard API. The following procedure outlines how to use the OLE clipboard API to transfer Shell data with the Clipboard:

  1. The data source creates a data object to contain the data.
  2. The data source calls OleSetClipboard, which places a pointer to the data object's IDataObject interface on the Clipboard.
  3. The target calls OleGetClipboard to retrieve the pointer to the data object's IDataObject interface.
  4. The target extracts the data by calling the IDataObject::GetData method.
  5. With some Shell data transfers, the target might also need to call the data object's IDataObject::SetData method to provide feedback to the data object on the outcome of the data transfer. See Handling Optimized Move Operations for an example of this type of operation.

Drag-and-Drop Data Transfers

While somewhat more complex to implement, drag-and-drop data transfer has some significant advantages over the Clipboard:

  • Drag-and-drop transfers can be done with a simple mouse movement, making operation more flexible and intuitive to use than the Clipboard.
  • Drag-and-drop provides the user with a visual representation of the operation. The user can follow the icon as it moves from source to target.
  • Drag-and-drop notifies the target when the data is available.

Drag-and-drop operations also use data objects to transfer data. However, the drop source must provide functionality beyond that required for Clipboard transfers:

  • The drop source must also create an object that exposes an IDropSource interface. The system uses IDropSource to communicate with the source while the operation is in progress.
  • The drag-and-drop data object is responsible for tracking cursor movement and displaying an icon to represent the data object.

Drop targets must also provide more functionality than is needed to handle Clipboard transfers:

  • The drop target must expose an IDropTarget interface. When the cursor is over a target window, the system uses IDropTarget to provide the target with information such as the cursor position, and to notify it when the data is dropped.
  • The drop target must register itself with the system by calling RegisterDragDrop. This function provides the system with the handle to a target window and a pointer to the target application's IDropTarget interface.

Note: For drag-and-drop operations, your application must initialize COM with OleInitialize, not CoInitialize.

The following procedure outlines the essential steps that are typically used to transfer Shell data with drag-and-drop:

  1. The target calls RegisterDragDrop to give the system a pointer to its IDropTarget interface and register a window as a drop target.
  2. When the user starts a drag-and-drop operation, the source creates a data object and initiates a drag loop by calling DoDragDrop.
  3. When the cursor is over the target window, the system notifies the target by calling one of the target's IDropTarget methods. The system calls IDropTarget::DragEnter when the cursor enters the target window, and IDropTarget::DragOver as the cursor passes over the target window. Both methods provide the drop target with the current cursor position and the state of keyboard modifier keys such as CTRL or ALT. When the cursor leaves the target window, the system notifies the target by calling IDropTarget::DragLeave. When any of these methods return, the system calls the IDropSource interface to pass the return value to the source.
  4. When the user releases the mouse button to drop the data, the system calls the target's IDropTarget::Drop method. Among the method's parameters is a pointer to the data object's IDataObject interface.
  5. The target calls the data object's IDataObject::GetData method to extract the data.
  6. With some Shell data transfers, the target might also need to call the data object's IDataObject::SetData method to provide feedback to the source on the outcome of the data transfer.
  7. When the target is finished with the data object, it returns from IDropTarget::Drop. The system returns the source's DoDragDrop call to notify the source that the data transfer is complete.
  8. Depending on the particular data transfer scenario, the source might need to take additional action based on the value returned by DoDragDrop and the values that are passed to the data object by the target. For instance, when a file is moved, the source must check these values to determine whether it must delete the original file.
  9. The source releases the data object.

While the procedures outlined above provide a good general model for Shell data transfer, there are many different types of data that can be contained in a Shell data object. There are also a number of different data transfer scenarios that your application might need to handle. Each data type and scenario requires a somewhat different approach to three key steps in the procedure:

  • How a source constructs a data object to contain the Shell data.
  • How a target extracts Shell data from the data object.
  • How the source completes the data transfer operation.

The Shell Data Object provides a general discussion of how a source constructs a Shell data object, and how that data object can be handled by the target. Handling Shell Data Transfer Scenarios discusses in detail how to handle a number of common Shell data transfer scenarios.


Shell Data Object

The data object is central to all Shell data transfers. It is primarily a container to hold the transferred data. However, the target can also communicate with the data object to facilitate some specialized types of Shell data transfer such as optimized moves. This documentation provides a general discussion of how Shell data objects work, how they are constructed by a source, and how they are handled by a target. For a detailed discussion of how to use data objects to transfer different types of Shell data, see Handling Shell Data Transfer Scenarios.

  • How Data Objects Work
  • How a Source Creates a Shell Data Object
  • How a Target Handles a Shell Data Object
  • Using the Drag-and-Drop Helper Object

How Data Objects Work

Data objects are COM objects, created by the data source to transfer data to a target. They typically carry more than one item of data. There are two reasons for this practice:

  • While almost any type of data can be transferred with a data object, the source typically does not know what kind of data the target can accept. For instance, the data might be a portion of a formatted text document. While the target might be able to handle complex formatting information, it might also be able to accept only ANSI text. For this reason, data objects often include the same data in several different formats. The target can then extract the data in a format that it can handle.
  • Data objects can also contain auxiliary data items that are not versions of source data. This type of data item typically provides additional information about the data transfer operation. For instance, the Shell uses auxiliary data items to indicate whether a file is to be copied or moved.

Clipboard Formats

Each item of data in a data object has an associated format, usually called a clipboard format. There are a number of standard clipboard formats, declared in Winuser.h, that correspond to commonly used types of data. Clipboard formats are integers, but they are normally referred to by their equivalent name, which has the form CF_XXX. For instance, the clipboard format for ANSI text is CF_TEXT.

Applications can extend the range of available clipboard formats by defining private formats. To define a private format, an application calls RegisterClipBoardFormat with a string that identifies the format. The unsigned integer that the function returns is a valid format value that can be used just like a standard clipboard format. However, both source and target must register the format in order to use it. With one exception—CF_HDROP—the clipboard formats used to transfer Shell data are defined as private formats. They must be registered by the source and target before they can be used. For a description of the available Shell clipboard formats, see Shell Clipboard Formats.

Although there are some exceptions, data objects normally contain only one item of data for each clipboard format they support. This one-to-one correlation between format and data allows the format value to be used as an identifier for the associated data item. In fact, when discussing the contents of a data object, a particular item of data is typically called a "format" and is referred to by its format name. For example, phrases such as "Extract the CF_TEXT format..." are typically used when discussing a data object's ANSI text data item.

When the drop target receives the pointer to the data object, the drop target enumerates the available formats to determine what types of data are available. It then requests one or more of the available formats and extracts the data. The specific way that the target extracts Shell data from a data object varies with the format; this is discussed in detail in How a Target Handles a Shell Data Object.

With simple clipboard data transfers, the data is placed in a global memory object. The address of that object is placed on the Clipboard, along with its format. The clipboard format tells the target what kind of data it will find at the associated address. While simple clipboard transfers are easy to implement:

  • Data objects provide a much more flexible way to transfer data.
  • Data objects are better suited for transferring large amounts of data.
  • Data objects must be used to transfer data with a drag-and-drop operation.

For these reasons, all Shell data transfers use data objects. With data objects, clipboard formats are not used directly. Instead, data items are identified with a generalization of the clipboard format, a FORMATETC structure.

FORMATETC Structure

The FORMATETC structure is an extended version of a clipboard format. As used for Shell data transfers, the FORMATETC structure has the following characteristics:

  • A data item is still identified by its clipboard format, in the cfFormat member.
  • Data transfer is not limited to global memory objects. The tymed member is used to indicate the data transfer mechanism contained in the associated STGMEDIUM structure. It is set to one of the TYMED_XXX values.
  • The Shell uses the lIndex member with its CFSTR_FILECONTENTS format to allow a data object to contain more than one data item per format. For a discussion of how to use this format, see Using the CFSTR_FILECONTENTS Format to Extract Data from a File.
  • The dwAspect member is typically set to DVASPECT_CONTENT. However, there are three values defined in Shlobj.h that can be used for Shell data transfer.

    DVASPECT_COPY | Used to indicate that the format represents a copy of the data.
    DVASPECT_LINK | Used to indicate that the format represents a shortcut to the data.
    DVASPECT_SHORTNAME | Used with the CF_HDROP format to request a file path with the names shortened to the 8.3 format.
  • The ptd member is not used for Shell data transfers and is normally set to NULL.

STGMEDIUM structure

The STGMEDIUM structure provides access to the data being transferred. Three data transfer mechanisms are supported for Shell data:

  • A global memory object.
  • An IStream interface.
  • An IStorage interface.

The tymed member of the STGMEDIUM structure is a TYMED_XXX value that identifies the data transfer mechanism. The second member is a pointer that is used by the target to extract the data. The pointer can be one of a variety of types, depending on the tymed value. The three tymed values that are used for Shell data transfers are summarized in the following table, along with their corresponding STGMEDIUM member name.

tymed Value | Member name | Description
TYMED_HGLOBAL | hGlobal | A pointer to a global memory object. This pointer type is typically used for transferring small amounts of data. For instance, the Shell uses global memory objects to transfer short text strings such as file names or URLs.
TYMED_ISTREAM | pstm | A pointer to an IStream interface. This pointer type is preferred for most Shell data transfers because it requires relatively little memory compared to TYMED_HGLOBAL. Also, the TYMED_ISTREAM data transfer mechanism does not require the source to store its data in any particular way.
TYMED_ISTORAGE | pstg | A pointer to an IStorage interface. The target calls the interface methods to extract the data. Like TYMED_ISTREAM, this pointer type requires relatively little memory. However, because TYMED_ISTORAGE is less flexible than TYMED_ISTREAM, it is not as commonly used.

How a Source Creates a Data Object

When a user initiates a Shell data transfer, the source is responsible for creating a data object and loading it with data. The following procedure summarizes the process:

  1. Call RegisterClipBoardFormat to obtain a valid clipboard format value for each Shell format that will be included in the data object. Remember that CF_HDROP is already a valid clipboard format and does not need to be registered.
  2. For each format to be transferred, either put the associated data into a global memory object or create an object that provides access to that data through an IStream or IStorage interface. The IStream and IStorage interfaces are created using standard COM techniques. For a discussion of how to handle global memory objects, see How to Add a Global Memory Object to a Data Object.
  3. Create FORMATETC and STGMEDIUM structures for each format.
  4. Instantiate a data object.
  5. Load the data into the data object by calling the IDataObject::SetData method for each supported format and passing in the format's FORMATETC and STGMEDIUM structures.
  6. With clipboard data transfers, call OleSetClipboard to place a pointer to the data object's IDataObject interface on the Clipboard. For drag-and-drop transfers, initiate a drag loop by calling DoDragDrop. The IDataObject pointer will be passed to the drop target when the data is dropped, ending the drag loop.

The data object is now ready to be transferred to the target. For clipboard data transfers, the object is simply held until the target requests it by calling OleGetClipboard. For drag-and-drop data transfers, the data object is responsible for creating an icon to represent the data and moving it as the user moves the cursor. While the object is in the drag loop, the source receives status information through its IDropSource interface. For further discussion, see Implementing IDropSource.

The source receives no notification if the data object is retrieved from the Clipboard by a target. When an object is dropped on a target by a drag-and-drop operation, the DoDragDrop function that was called to initiate the drag loop will return.

How to Add a Global Memory Object to a Data Object

Many of the Shell data formats are in the form of a global memory object. Use the following procedure to create a format containing a global memory object and load it into the data object:

  1. Create a FORMATETC structure. Set the cfFormat member to the appropriate clipboard format value and the tymed member to TYMED_HGLOBAL.
  2. Create an STGMEDIUM structure. Set the tymed member to TYMED_HGLOBAL.
  3. Create a global memory object by calling GlobalAlloc to allocate a suitably sized block of memory.
  4. Assign the block of data to be transferred to the address returned by GlobalAlloc.
  5. Assign the global memory object's address to the hGlobal member of the STGMEDIUM structure.
  6. Load the format into the data object by calling IDataObject::SetData and passing in the FORMATETC and STGMEDIUM structures created in the previous steps.

The following sample function creates a global memory object containing a DWORD value and loads it into a data object. The pdtobj parameter is a pointer to the data object's IDataObject interface, cf is the clipboard format value, and dw is the data value.

STDAPI DataObj_SetDWORD(IDataObject *pdtobj, UINT cf, DWORD dw)

{
    FORMATETC fmte = {(CLIPFORMAT) cf, NULL, DVASPECT_CONTENT, -1,
        TYMED_HGLOBAL};
    STGMEDIUM medium;

    HRESULT hres = E_OUTOFMEMORY;
    DWORD *pdw = (DWORD *)GlobalAlloc(GPTR, sizeof(DWORD));
    if (pdw)
    {
        *pdw = dw;
        medium.tymed = TYMED_HGLOBAL;
        medium.hGlobal = pdw;
        medium.pUnkForRelease = NULL;

        hres = pdtobj->SetData(&fmte, &medium, TRUE);

        if (FAILED(hres))
            GlobalFree((HGLOBAL)pdw);
    }
    return hres;
}

Implementing IDataObject

IDataObject is a data object's primary interface. It must be implemented by all data objects. It is used by both source and target for a variety of purposes, including:

  • Loading data into the data object.
  • Extracting data from the data object.
  • Determining what types of data are in the data object.
  • Providing feedback to the data object on outcome of the data transfer.

IDataObject supports a number of methods. This section discusses how to implement the three most important methods for Shell data objects, SetData, EnumFormatEtc, and GetData. For a discussion of the other methods, see the IDataObject reference.

SetData method

The primary function of the SetData method is to allow the source to load data into the data object. For each format to be included, the source creates a FORMATETC structure to identify the format and an STGMEDIUM structure to hold a pointer to the data. The source then calls the object's IDataObject::SetData method and passes in the format's FORMATETC and STGMEDIUM structures. The method must store this information so that it is available when the target calls GetData to extract data from the object.

However, when transferring files, the Shell often puts the information for each file to be transferred into a separate CFSTR_FILECONTENTS format. To distinguish the different files, the lIndex member of each file's FORMATETC structure is set to an index value that identifies the particular file. Your SetData implementation must be capable of storing multiple CFSTR_FILECONTENTS formats that differ only by their lIndex members.

While the cursor is over the target window, the target can use the drag-and-drop helper object to specify the drag image. The drag-and-drop helper object calls SetData to load private formats into the data object that are used for cross-process support. To support the drag-and-drop helper object, your SetData implementation must be able to accept and store arbitrary private formats.

After the data has been dropped, some types of Shell data transfer require the target to call SetData to provide the data object with information about the outcome of the drop operation. For example, when moving files with an optimized move operation, the target normally deletes the original files, but it is not required to do so. The target informs the data object whether it deleted the files by calling SetData with a CFSTR_LOGICALPERFORMEDDROPEFFECT format. There are several other Shell clipboard formats that are also used by the target to pass information to the data object. Your SetData implementation must be able to recognize these formats and respond appropriately. For further discussion, see Handling Shell Data Transfer Scenarios.

EnumFormatEtc method

When the target receives a data object, it commonly calls EnumFormatEtc to determine what formats the object contains. The method creates an OLE enumeration object and returns a pointer to the object's IEnumFORMATETC interface. The target then uses the interface to enumerate the available formats.

Note An enumeration object should always enumerate the available formats in order of quality, starting with the best. The relative quality of formats is defined by the drop source. In general, the highest-quality formats contain the richest and most complete data. For instance, a 24-bit color image would normally be considered higher quality than a gray-scale version of that image. The reason for enumerating formats in order of their quality is that targets typically enumerate until they get to a format that they support, and then they use that format to extract the data. For this procedure to produce the best available format that the target can support, the formats must be enumerated in order of their quality.

An enumeration object for Shell data is implemented in much the same way as for other types of data transfer, with one notable exception. Because data objects typically contain only one data item per format, they normally enumerate every format that is passed to IDataObject::SetData. However, as discussed in SetData method, Shell data objects can contain multiple CFSTR_FILECONTENTS formats.

Because the purpose of EnumFormatEtc is to allow the target to determine what types of data are present, there is no need to enumerate more than one CFSTR_FILECONTENTS format. If the target needs to know how many of these formats the data object contains, the target can retrieve that information from the accompanying CFSTR_FILEDESCRIPTOR format. For further discussion of how to implement EnumFormatEtc, see the method's reference documentation.

GetData method

The target calls GetData to extract a particular data format. The target specifies the format by passing in the appropriate FORMATETC structure. GetData returns the format's STGMEDIUM structure.

The target can set the tymed member of the FORMATETC structure to a specific TYMED_XXX value to specify which data transfer mechanism it will use to extract the data. However, the target can also make a more generic request and let the data object decide. To ask the data object to select the data transfer mechanism, the target sets all the TYMED_XXX values that it supports. GetData selects one of these data transfer mechanisms and returns the appropriate STGMEDIUM structure. For instance, tymed is commonly set to TYMED_HGLOBAL | TYMED_ISTREAM | TYMED_ISTORAGE to request any of the three Shell data transfer mechanisms.

Note Because there can be multiple CFSTR_FILECONTENTS formats, the cfFormat and tymed members of the FORMATETC structure are not sufficient to indicate which STGMEDIUM structure GetData should return. For the CFSTR_FILECONTENTS format, GetData must also examine the FORMATETC structure's lIndex member in order to return the correct STGMEDIUM structure.

The CFSTR_INDRAGLOOP format is placed in data objects to allow targets to check the status of the drag-and-drop loop while avoiding expensive rendering of the object's data. The format's data is a DWORD value that is set to a nonzero value if the data object is within a drag loop. The format's data value is set to zero if the data has been dropped. If a target requests this format and it has not been loaded by the source, GetData should respond as if the source had loaded the format with a value of zero.

While the cursor is over the target window, the target can use the drag-and-drop helper object to specify the drag image. The drag-and-drop helper object calls SetData to load private formats into the data object that are used for cross-process support. It later calls GetData to retrieve them. To support the drag-and-drop helper object, your GetData implementation must be able to return arbitrary private formats when they are requested.

Implementing IDropSource

The source must create an object that exposes an IDropSource interface. This interface allows the source to update the drag image that indicates the current position of the cursor and to provide feedback to the system on how to terminate a drag-and-drop operation. IDropSource has two methods: GiveFeedback and QueryContinueDrag.

GiveFeedback method

While in the drag loop, a drop source is responsible for keeping track of the cursor position and displaying an appropriate drag image. However, in some cases you might want to change the appearance of the drag image when it is over the drop target's window.

When the cursor enters or leaves the target window and while it is moving over the target window, the system periodically calls the target's IDropTarget interface. The target responds with a DROPEFFECT value that is forwarded to the source through the IDropSource::GiveFeedback method. If appropriate, the source can modify the appearance of the cursor based on the DROPEFFECT value. For further details, see the IDropSource::GiveFeedback and DoDragDrop references.

QueryContinueDrag method

This method is called if the mouse button or keyboard state changes while the data object is in the drag loop. It notifies the source whether the ESCAPE key has been pressed and provides the current state of the keyboard modifier keys, such as CONTROL or SHIFT. The QueryContinueDrag method's return value specifies one of three actions:

  • S_OK. Continue the drag operation
  • DRAGDROP_S_DROP. Drop the data. The system then calls the target's IDropTarget::Drop method.
  • DRAGDROP_S_CANCEL. Terminate the drag loop without dropping the data. This value is normally returned if the ESCAPE key was pressed.

For further discussion, see the IDropSource::QueryContinueDrag and DoDragDrop references.

How a Target Handles a Data Object

The target receives a data object when it either retrieves the data object from the Clipboard or has it dropped on the target window by the user. The target can then extract data from the data object. If necessary, the target can also notify the data object of the outcome of the operation. Prior to a Shell data transfer, a drop target must prepare itself for the operation:

  1. The target must call RegisterClipBoardFormat to obtain a valid clipboard format value for all Shell formats, other than CF_HDROP, that might be included in the data object. CF_HDROP is already a valid clipboard format and does not need to be registered.
  2. To support a drag-and-drop operation, the target must implement an IDropTarget interface and register a target window. To register a target window, the target calls RegisterDragDrop and passes in the window's handle and the IDropTarget interface pointer.

For clipboard transfers, the target does not receive any notification that a data object has been placed on the Clipboard. Typically, an application is notified that an object is on the Clipboard by a user action, such as clicking the Paste button on the application's toolbar. The target then retrieves the data object's IDataObject pointer from the Clipboard by calling OleGetClipboard. For drag-and-drop data transfers, the system uses the target's IDropTarget interface to provide the target with information about the progress of the data transfer:

  • The system calls IDropTarget::DragEnter when the cursor enters the target window.
  • The system periodically calls IDropTarget::DragOver as the cursor passes over the target window, to give the target the current cursor position.
  • The system calls IDropTarget::DragLeave when the cursor leaves the target window.
  • The system calls IDropTarget::Drop when the user drops the data object on the target window.

For a discussion of how to implement these methods, see Implementing IDropTarget.

When the data is dropped, IDropTarget::Drop provides the target with a pointer to the data object's IDataObject interface. The target then uses this interface to extract data from the data object.

Extracting Shell Data from a Data Object

Once a data object has been dropped or retrieved from the Clipboard, the target can extract the data it needs. The first step in the extraction process is typically to enumerate the formats contained by the data object:

  • Call IDataObject::EnumFormatEtc. The data object creates a standard OLE enumeration object and returns a pointer to its IEnumFORMATETC interface.
  • Use the IEnumFORMATETC methods to enumerate the formats contained by the data object. This operation usually retrieves one FORMATETC structure for each format that the object contains. However, the enumeration object normally returns only a single FORMATETC structure for the CFSTR_FILECONTENTS format, regardless of how many such formats are contained by the data object.
  • Select one or more formats to be extracted, and store their FORMATETC structures.

To retrieve a particular format, pass the associated FORMATETC structure to IDataObject::GetData. This method returns an STGMEDIUM structure that provides access to the data. To specify a particular data transfer mechanism, set the tymed value of the FORMATETC structure to the corresponding TYMED_XXX value. To ask the data object to select a data transfer mechanism, the target sets the TYMED_XXX values for every data transfer mechanism that the target can handle. The data object selects one of these data transfer mechanisms and returns the appropriate STGMEDIUM structure.

For most formats, the target can retrieve the data by passing the FORMATETC structure that it received when it enumerated the available formats. One exception to this rule is CFSTR_FILECONTENTS. Because a data object can contain multiple instances of this format, the FORMATETC structure returned by the enumerator might not correspond to the particular format you want to extract. In addition to specifying the cfFormat and tymed members, you must also set the lIndex member to the file's index value. For further discussion, see Using the CFSTR_FILECONTENTS Format to Extract Data from a File.

The data extraction process depends on the type of pointer contained by the returned STGMEDIUM structure. If the structure contains a pointer to an IStream or IStorage interface, use the interface methods to extract the data. The process of extracting data from a global memory object is discussed in the next section.

Extracting a global memory object from a data object

Many of the Shell data formats are in the form of a global memory object. Use the following procedure to extract a format containing a global memory object from a data object and assign its data to a local variable:

  1. Create a FORMATETC structure. Set the cfFormat member to the appropriate clipboard format value and the tymed member to TYMED_HGLOBAL.
  2. Create an empty STGMEDIUM structure.
  3. Call IDataObject::GetData, and pass in pointers to the FORMATETC and STGMEDIUM structures.

    When IDataObject::GetData returns, the STGMEDIUM structure will contain a pointer to the global memory object that contains the data.

  4. Assign the data to a local variable by calling GlobalLock and passing in the hGlobal member of the STGMEDIUM structure.
  5. Call GlobalUnlock to release the lock on the global memory object.
  6. Call ReleaseStgMedium to release the global memory object.

Note You must use ReleaseStgMedium to release the global memory object, not GlobalFree.

The following example shows how to extract a DWORD value stored as a global memory object from a data object. The pdtobj parameter is a pointer to the data object's IDataObject interface, cf is the clipboard format that identifies the desired data, and pdwOut is used to return the data value.

STDAPI DataObj_GetDWORD(IDataObject *pdtobj, UINT cf, DWORD *pdwOut)
{
    STGMEDIUM medium;
    FORMATETC fmte = {(CLIPFORMAT) cf, NULL, DVASPECT_CONTENT, -1,
        TYMED_HGLOBAL};

    HRESULT hres = pdtobj->GetData(&fmte, &medium);

    if (SUCCEEDED(hres))
    {
        DWORD *pdw = (DWORD *)GlobalLock(medium.hGlobal);

        if (pdw)
        {
            *pdwOut = *pdw;
            GlobalUnlock(medium.hGlobal);
        }

        else
        {
            hres = E_UNEXPECTED;
        }

        ReleaseStgMedium(&medium);
    }
    return hres;
}

Implementing IDropTarget

The system uses the IDropTarget interface to communicate with the target while the cursor is over the target window. The target's responses are forwarded to the source through its IDropSource interface. Depending on the response, the source can modify the icon that represents the data. If the drop target needs to specify the data icon, it can do so by creating a drag-and-drop helper object.

With conventional drag-and-drop operations, the target informs the data object of the outcome of the operation by setting the pdwEffect parameter of IDropTarget::Drop to the appropriate DROPEFFECT value. With Shell data objects, the target might also need to call IDataObject::SetData. For a discussion of how targets should respond for different data transfer scenarios, see Handling Shell Data Transfer Scenarios.

The following sections briefly discuss how to implement the IDropTarget::DragEnter, IDropTarget::DragOver, and IDropTarget::Drop methods. For further details, see the reference documentation.

DragEnter method

The system calls the IDropTarget::DragEnter method when the cursor enters the target window. Its parameters provide the target with the location of the cursor, the state of keyboard modifier keys such as the CTRL key, and a pointer to the data object's IDataObject interface. The target is responsible for using that interface to determine whether it can accept any of the formats contained by the data object. If it can, it normally leaves the value of pdwEffect unchanged. If it cannot accept any data from the data object, it sets the pdwEffect parameter to DROPEFFECT_NONE. The system passes the value of this parameter to the data object's IDropSource interface to allow it to display the appropriate drag image.

Targets should not use the IDataObject::GetData method to render Shell data before it has been dropped. Fully rendering the object's data for each such occurrence might cause the drag cursor to stall. To avoid this problem, some Shell objects contain a CFSTR_INDRAGLOOP format. By extracting this format, targets can check the status of the drag loop while avoiding expensive rendering of the object's data. The format's data value is a DWORD that is set to a nonzero value if the data object is within a drag loop. The format's data value is set to zero if the data has been dropped.

If the target can accept data from the data object, it should examine grfKeyState to determine whether any modifier keys have been pressed to modify the normal drop behavior. For instance, the default operation is typically a move, but depressing the CTRL key usually indicates a copy operation.

While the cursor is over the target window, the target can use the drag-and-drop helper object to replace the data object's drag image with its own. If so, IDropTarget::DragEnter should call IDropTargetHelper::DragEnter to pass the information contained in the DragEnter parameters to the drag-and-drop helper object.

DragOver method

As the cursor moves within the target window, the system periodically calls the IDropTarget::DragOver method. Its parameters provide the target with the location of the cursor and the state of keyboard modifier keys such as the CTRL key. DragOver has much the same responsibilities as IDropTarget::DragEnter, and the implementations are usually very similar.

If the target is using the drag-and-drop helper object, IDropTarget::DragOver should call IDropTargetHelper::DragOver to forward the information contained in the DragOver parameters to the drag-and-drop helper object.

Drop method

The system calls the IDropTarget::Drop method to notify the target that the user has dropped the data, typically by releasing the mouse button. Drop has the same parameters as IDropTarget::DragEnter. The target normally responds by extracting one or more formats from the data object. When finished, the target should set the pdwEffect parameter to a DROPEFFECT value that indicates the outcome of the operation. For some types of Shell data transfer, the target must also call IDataObject::SetData to pass a format with additional information on the outcome of the operation to the data object. For a detailed discussion, see Handling Shell Data Transfer Scenarios.

If the target is using the drag-and-drop helper object, IDropTarget::Drop should call IDropTargetHelper::Drop to forward the information contained in the IDropTargetHelper::DragOver parameters to the drag-and-drop helper object.

Using the Drag-and-Drop Helper Object

The drag-and-drop helper object (CLSID_DragDropHelper) is exported by the Shell to allow targets to specify the drag image while it is over the target window. To use the drag-and-drop helper object, create an in-process server object by calling CoCreateInstance with a CLSID of CLSID_DragDropHelper. The drag-and-drop helper object exposes two interfaces that are used in the following way:

  • The IDragSourceHelper interface allows the drop target to specify an icon to represent the data object.
  • The IDropTargetHelper interface allows the drop target to inform the drag-and-drop helper object of the cursor location, and to show or hide the data icon.

Using the IDragSourceHelper Interface

The IDragSourceHelper interface is exposed by the drag-and-drop helper object to allow a drop target to provide the image that will be displayed while the cursor is over the target window. IDragSourceHelper provides two alternative ways to specify the bitmap to be used as a drag image:

  • Drop targets that have a window can register a DI_GETDRAGIMAGE window message for it by initializing the drag-and-drop helper object with IDragSourceHelper::InitializeFromWindow. When the target receives a DI_GETDRAGIMAGE message, the handler puts the drag image bitmap information in the SHDRAGIMAGE structure that is passed as the message's lParam value.
  • Windowless drop targets specify a bitmap when they initialize the drag-and-drop helper object with IDragSourceHelper::InitializeFromBitmap.

Using the IDropTargetHelper Interface

This interface allows the drop target to notify the drag-and-drop helper object when the cursor enters or leaves the target. While the cursor is over the target window, IDropTargetHelper allows the target to give the drag-and-drop helper object the information that the target receives through its IDropTarget interface.

Four of the IDropTargetHelper methods—IDropTargetHelper::DragEnter, IDropTargetHelper::DragLeave, IDropTargetHelper::DragOver, and IDropTargetHelper::Drop—are associated with the IDropTarget method of the same name. To use the drag-and-drop helper object, each of the IDropTarget methods should call the corresponding IDropTargetHelper method to forward the information to the drag-and-drop helper object. The fifth IDropTargetHelper method, IDropTargetHelper::Show, notifies the drag-and-drop helper object to show or hide the drag image. This method is used when dragging over a target window in a low color-depth video mode. It allows the target to hide the drag image while it is painting the window.


Shell Clipboard Formats

The Shell clipboard formats are used to identify the type of Shell data being transferred. Most Shell clipboard formats identify a type of data, such as a list of file names or PIDLs. However, some formats are used for communication between source and target. They can expedite the data transfer process by supporting Shell operations such as optimized move and delete-on-paste. Shell data is always contained in a data object that uses a FORMATETC structure as a more general way to characterize data. The structure's cfFormat member is set to the clipboard format for the particular item of data. The other members provide additional information, such as the data transfer mechanism. The data is contained in an accompanying STGMEDIUM structure.

Note Standard clipboard format identifiers have the form CF_XXX. A common example is CF_TEXT, which is used for transferring ANSI text data. These identifiers have predefined values and can be used directly with FORMATETC structures. With the exception of CF_HDROP, Shell format identifiers have the form CFSTR_XXX and are not predefined. For simplicity, the CFSTR_XXX values are often referred to as formats. However, unlike predefined formats, they must be registered by both source and target before they can be used to transfer data. To register a Shell format, include the Shlobj.h header file and pass the CFSTR_XXX format identifier to RegisterClipBoardFormat. This function returns a valid clipboard format value, which can then be used as the cfFormat member of a FORMATETC structure.

The Shell clipboard formats are organized here into three groups, based on how they are used:

  • Formats for Transferring File System Objects
  • Formats for Transferring Virtual Objects
  • Formats for Communication Between Source and Target

Formats for Transferring File System Objects

These formats are used to transfer one or more files or other Shell objects.

  • CF_HDROP
  • CFSTR_FILECONTENTS
  • CFSTR_FILEDESCRIPTOR
  • CFSTR_FILENAME
  • CFSTR_FILENAMEMAP
  • CFSTR_MOUNTEDVOLUME
  • CFSTR_SHELLIDLIST
  • CFSTR_SHELLIDLISTOFFSET

CF_HDROP

This clipboard format is used when transferring the locations of a group of existing files. Unlike the other Shell formats, it is predefined, so there is no need to call RegisterClipBoardFormat. The data consists of an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a DROPFILES structure as its hGlobal member.

The pFiles member of the DROPFILES structure contains an offset to a double NULL-terminated character array containing the file names. If you are extracting a CF_HDROP format from a data object, you can use DragQueryFile to extract individual file names from the global memory object. If you are creating a CF_HDROP format to place in a data object, you will need to construct the file name array.

The file name array consists of a series of strings, each containing one file's fully qualified path, including the terminating NULL character. An additional NULL character is appended to the final string to terminate the array. For example, if the files c:\temp1.txt and c:\temp2.txt are being transferred, the character array looks like this:

c:\temp1.txt'\0'c:\temp2.txt'\0''\0'

Note In this example, '\0' is used to represent the NULL character, not the literal characters that should be included.

If the object was copied to the clipboard as part of a drag-and-drop operation, the pt member of the DROPFILES structure contains the coordinates of the point where the object was dropped. You can use DragQueryPoint to extract the cursor coordinates.

If this format is present in a data object, an OLE drag loop simulates WM_DROPFILES functionality with non-OLE drop targets. This is important if your application is the source of a drag-and-drop operation on a Microsoft® Windows® 3.1 system.

Note This format supports both ANSI and Unicode. However, only ANSI file paths can be used with Windows 95 systems.

CFSTR_FILECONTENTS

This format identifier is used with the CFSTR_FILEDESCRIPTOR format to transfer data as if it were a file, regardless of how it is actually stored. The data consists of an STGMEDIUM structure that represents the contents of one file. The file is normally represented as a stream object, which avoids having to place the contents of the file in memory. In that case, the tymed member of the STGMEDIUM structure is set to TYMED_ISTREAM, and the file is represented by an IStream interface. The file can also be a storage or global memory object (TYMED_ISTORAGE or TYMED_HGLOBAL). The associated CFSTR_FILEDESCRIPTOR format contains a FILEDESCRIPTOR structure for each file that specifies the file's name and attributes.

The target treats the data associated with a CFSTR_FILECONTENTS format as if it were a file. When the target calls IDataObject::GetData to extract the data, it specifies a particular file by setting the lindex member of the FORMATETC structure to the zero-based index of the file's FILEDESCRIPTOR structure in the accompanying CFSTR_FILEDESCRIPTOR format. The target then uses the returned interface pointer or global memory handle to extract the data.

CFSTR_FILEDESCRIPTOR

This format identifier is used with the CFSTR_FILECONTENTS format to transfer data as a group of files. These two formats are the preferred way to transfer Shell objects that are not stored as file-system files. For example, these formats can be used to transfer a group of e-mail messages as individual files, even though each e-mail is actually stored as a block of data in a database. The data consists of an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a FILEGROUPDESCRIPTOR structure that is followed by an array containing one FILEDESCRIPTOR structure for each file in the group. For each FILEDESCRIPTOR structure, there is a separate CFSTR_FILECONTENTS format that contains the contents of the file. To identify a particular file's CFSTR_FILECONTENTS format, set the lIndex value of the FORMATETC structure to the zero-based index of the file's FILEDESCRIPTOR structure.

The CFSTR_FILEDESCRIPTOR format is commonly used to transfer data as if it were a group of files, regardless of how it is actually stored. From the target's perspective, each CFSTR_FILECONTENTS format represents a single file and is treated accordingly. However, the source can store the data in any way it chooses. While a CSFTR_FILECONTENTS format might correspond to a single file, it could also, for example, represent data extracted by the source from a database or text document.

CFSTR_FILENAME

This format identifier is used to transfer a single file. The data consists of an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a single null-terminated string containing the file's fully qualified file path. This format has been superseded by CF_HDROP, but it is supported for backward compatibility with Windows 3.1 applications.

CFSTR_FILENAMEMAP

This format identifier is used when a group of files in CF_HDROP format is being renamed as well as transferred. The data consists of an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a double null-terminated character array. This array contains a new name for each file, in the same order that the files are listed in the accompanying CF_HDROP format. The format of the character array is the same as that used by CF_HDROP to list the transferred files.

CFSTR_MOUNTEDVOLUME

This format identifier is used to transfer a path on a mounted volume. It is similar to CF_HDROP, but it contains only a single path and can handle the longer path strings that might be needed to represent a path when the volume is mounted on a folder. The data consists of an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a single null-terminated string containing the fully qualified file path. The path string must end with a '\' character, followed by the terminating NULL.

Prior to Microsoft Windows 2000, volumes could be mounted only on drive letters. For Windows 2000 and later systems with an NTFS formatted drive, you can also mount volumes on empty folders. This feature allows a volume to be mounted without taking up a drive letter. The mounted volume can use any currently supported format, including FAT, FAT32, NTFS, and CDFS.

You can add pages to a Drive Properties property sheet by implementing a property sheet handler. If the volume is mounted on a drive letter, the Shell passes path information to the handler with the CF_HDROP format. With Windows 2000 and later systems, the CF_HDROP format is used when a volume is mounted on a drive letter, just as with earlier systems. However, if a volume is mounted on a folder, the CFSTR_MOUNTEDVOLUME format identifier is used instead of CF_HDROP.

If only drive letters will be used to mount volumes, only CF_HDROP will be used, and existing property sheet handlers will work as they did with earlier systems. However, if you want your handler to display a page for volumes that are mounted on folders as well as drive letters, the handler must be able to understand both the CSFTR_MOUNTEDVOLUME and CF_HDROP formats.

CFSTR_SHELLIDLIST

This format identifier is used when transferring the locations of one or more existing namespace objects. It is used in much the same way as CF_HDROP, but it contains PIDLs instead of file system paths. Using PIDLS allows the CFSTR_SHELLIDLIST format to handle virtual objects as well as file system objects. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a CIDA structure.

The aoffset member of the CIDA structure is an array containing offsets to the beginning of the ITEMIDLIST structure for each PIDL that is being transferred. To extract a particular PIDL, first determine its index. Then, add the aoffset value that corresponds to that index to the address of the CIDA structure.

The first element of aoffset contains an offset to the fully qualified PIDL of a parent folder. If this PIDL is empty, the parent folder is the desktop. Each of the remaining elements of the array contains an offset to one of the PIDLs to be transferred. All of these PIDLs are relative to the PIDL of the parent folder.

The following two macros can be used to retrieve PIDLs from a CIDA structure. The first takes a pointer to the structure and retrieves the PIDL of the parent folder. The second takes a pointer to the structure and retrieves one of the other PIDLs, identified by its zero-based index.

#define GetPIDLFolder(pida) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[0])
#define GetPIDLItem(pida, i) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[i+1])

Note The value that is returned by these macros is a pointer to the PIDL's ITEMIDLIST structure. Since these structures vary in length, you must determine the end of the structure by walking through each of the ITEMIDLIST structure's SHITEMID structures until you reach the two-byte NULL that marks the end. For further discussion of PIDLs and the ITEMIDLIST structure, see The Shell Namespace.

CFSTR_SHELLIDLISTOFFSET

This format identifier is used with formats such as CF_HDROP, CFSTR_SHELLIDLIST, and CFSTR_FILECONTENTS to specify the position of a group of objects following a transfer. The data consists of an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to an array of POINT structures. The first structure specifies the screen coordinates, in pixels, of the upper-left corner of the rectangle that encloses the group. The remainder of the structures specify the locations of the individual objects relative to the group's position. They must be in the same order as that used to list the objects in the associated format.

Formats for Transferring Virtual Objects

The CFSTR_SHELLIDLIST format can be used to transfer both file system and virtual objects. However, there are also several specialized formats for transferring particular types of virtual objects.

  • CFSTR_NETRESOURCES
  • CFSTR_PRINTERGROUP
  • CFSTR_INETURL
  • CFSTR_SHELLURL

CFSTR_NETRESOURCES

This format identifier is used when transferring network resources, such as a domain or server. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a single NULL-terminated string that identifies the network resource. The drop target can then use the data with any of the WNet API functions, such as WNetAddConnection, to perform network operations on the object.

CFSTR_PRINTERGROUP

This format identifier is used when transferring the friendly names of printers. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a string in the same format as that used with CF_HDROP. However, the pFiles member of the DROPFILES structure contains one or more friendly names of printers instead of file paths.

CFSTR_INETURL

This format identifier replaces CFSTR_SHELLURL. If you want your application to manipulate clipboard URLs, use CFSTR_INETURL instead of CFSTR_SHELLURL. This format gives the best clipboard representation of a single URL. If UNICODE is not defined, the application retrieves the CF_TEXT/CFSTR_SHELLURL version of the URL. If UNICODE is defined, the application retrieves the CF_UNICODE version of the URL.

CFSTR_SHELLURL (deprecated)

This format identifier is the deprecated identifier for transferring a single URL. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a single NULL-terminated string that contains the URL. This format is equivalent to the CF_TEXT clipboard format, but it is useful for Internet-related applications.

Note: This format identifier has been deprecated; use CFSTR_INETURL instead.

Formats for Communication Between Source and Target

Several format identifiers were introduced with Internet Explorer 4.0 to allow communication between source and target. These formats accompany the actual data and give applications a greater degree of control over move-copy-paste or drag-and-drop operations involving Shell objects.

  • CFSTR_INDRAGLOOP
  • CFSTR_LOGICALPERFORMEDDROPEFFECT
  • CFSTR_PASTESUCCEEDED
  • CFSTR_PERFORMEDDROPEFFECT
  • CFSTR_PREFERREDDROPEFFECT
  • CFSTR_TARGETCLSID

CFSTR_INDRAGLOOP

This format identifier is used by a data object to indicate whether it is in a drag-and-drop loop. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a DWORD value. If the DWORD value is nonzero, the data object is within a drag-and-drop loop. If the value is set to zero, the data object is not within a drag-and-drop loop.

Some drop targets might call IDataObject::GetData and attempt to extract data while the object is still within the drag-and-drop loop. Fully rendering the object for each such occurrence might cause the drag cursor to stall. If the data object supports CFSTR_INDRAGLOOP, the target can instead use that format to check the status of the drag-and-drop loop and avoid expensive rendering of the object until it is actually dropped. The expensive-to-render formats should still be included in the FORMATETC enumerator and in calls to IDataObject::QueryGetData. If the data object does not set CFSTR_INDRAGLOOP, it should act as if the value is set to zero.

CFSTR_LOGICALPERFORMEDDROPEFFECT

Version 5.0. This format identifier allows a drop source to call the data object's IDataObject::GetData method to determine the outcome of a Shell data transfer. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a DWORD containing a DROPEFFECT value.

The CFSTR_PERFORMEDDROPEFFECT format identifier was intended to allow the target to indicate to the data object what operation actually took place. However, the Shell uses optimized moves for file system objects whenever possible. In that case, the Shell normally sets the CFSTR_PERFORMEDDROPEFFECT value to DROPEFFECT_NONE, to indicate to the data object that the original data has been deleted. Thus, the source cannot use the CFSTR_PERFORMEDDROPEFFECT value to determine which operation has taken place. While most sources do not need this information, there are some exceptions. For instance, even though optimized moves eliminate the need for a source to delete any data, the source might still need to update a related database to indicate that the files have been moved or copied.

If a source needs to know which operation took place, it can call the data object's IDataObject::GetData method and request the CFSTR_LOGICALPERFORMEDDROPEFFECT format. This format essentially reflects what happens from the user's point of view after the operation is complete. If a new file is created and the original file is deleted, the user sees a move operation and the format's data value is set to DROPEFFECT_MOVE. If the original file is still there, the user sees a copy operation and the format's data value is set to DROPEFFECT_COPY. If a link was created, the format's data value will be DROPEFFECT_LINK.

CFSTR_PASTESUCCEEDED

This format identifier is used by the target to inform the data object, through its IDataObject::SetData method, that a delete-on-paste operation succeeded. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a DWORD containing a DROPEFFECT value. This format is used to notify the data object that it should complete the cut operation and delete the original data, if necessary. For more information, see Delete-on-Paste Operations.

CFSTR_PERFORMEDDROPEFFECT

This format identifier is used by the target to inform the data object through its IDataObject::SetData method of the outcome of a data transfer. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a DWORD set to the appropriate DROPEFFECT value, normally DROPEFFECT_MOVE or DROPEFFECT_COPY.

This format is normally used when the outcome of an operation can be either move or copy, such as in an optimized move or delete-on-paste operation. It provides a reliable way for the target to tell the data object what actually happened. It was introduced because the value of pdwEffect returned by DoDragDrop did not reliably indicate which operation had taken place. The CFSTR_PERFORMEDDROPEFFECT format is the reliable way to indicate that an unoptimized move has taken place.

CFSTR_PREFERREDDROPEFFECT

This format identifier is used by the source to specify whether its preferred method of data transfer is move or copy. A drop target requests this format by calling the data object's IDataObject::GetData method. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to a DWORD value. This value is set to DROPEFFECT_MOVE if a move operation is preferred or DROPEFFECT_COPY if a copy operation is preferred.

This feature is used when a source can support either a move or copy operation. It uses the CFSTR_PREFERREDDROPEFFECT format to communicate its preference to the target. Because the target is not obligated to honor the request, the target must call the source's IDataObject::SetData method with a CFSTR_PERFORMEDDROPEFFECT format to tell the data object which operation was actually performed.

With a delete-on-paste operation, the CFSTR_PREFERREDDROPFORMAT format is used to tell the target whether the source did a cut or copy. With a drag-and-drop operation, you can use CFSTR_PREFERREDDROPFORMAT to specify the Shell's action. If this format is not present, the Shell performs a default action, based on context. For instance, if a user drags a file from one volume and drops it on another volume, the Shell's default action is to copy the file. By including a CFSTR_PREFERREDDROPFORMAT format in the data object, you can override the default action and explicitly tell the Shell to copy, move, or link the file. If the user chooses to drag with the right button, CFSTR_PREFERREDDROPFORMAT specifies the default command on the drag-and-drop shortcut menu. The user is still free to choose other commands on the menu.

Before Internet Explorer 4.0, an application indicated that it was transferring shortcut file types by setting FD_LINKUI in the dwFlags member of the FILEDESCRIPTOR structure. Targets then had to use a potentially time-consuming call to IDataObject::GetData to find out if the FD_LINKUI flag was set. Now, the preferred way to indicate that shortcuts are being transferred is to use the CFSTR_PREFERREDDROPEFFECT format set to DROPEFFECT_LINK. However, for backward compatibility with older systems, sources should still set the FD_LINKUI flag.

CFSTR_TARGETCLSID

This format identifier is used by a target to provide its CLSID to the source. The data is an STGMEDIUM structure that contains a global memory object. The structure's hGlobal member points to the CLSID GUID of the drop target.

This format is used primarily to allow objects to be deleted by dragging them to the Recycle Bin. When an object is dropped in the Recycle Bin, the source's IDataObject::SetData method is called with a CFSTR_TARGETCLSID format set to the Recycle Bin's CLSID (CLSID_RecycleBin). The source can then delete the original object.


Handling Shell Data Transfer Scenarios

The Shell Data Object document discussed the general approach that is used to transfer Shell data with drag-and-drop or the Clipboard. However, to implement Shell data transfer in your application, you must also understand how to apply these general principles and techniques to the variety of ways that Shell data can be transferred. This document presents the following common Shell data transfer scenarios and discusses how to implement each one in your application.

  • General Guidelines
  • Copying File Names from the Clipboard to an Application
  • Copying the Contents of a Dropped File into an Application
  • Handling Optimized Move Operations
  • Handling Delete-on-Paste Operations
  • Transferring Data to and from Virtual Folders
  • Dropping Files on the Recycle Bin
  • Creating and Importing Scrap Files
  • Dragging and Dropping Shell Objects Asynchronously

Note Although each of these scenarios discusses a specific data transfer operation, many of them apply to a variety of related scenarios. For instance, the primary difference between most clipboard and drag-and-drop transfers is in how the data object gets to the target. Once the target has a pointer to the data object's IDataObject interface, the procedures for extracting information are largely the same for both types of data transfer. However, some of the scenarios are limited to a specific type of operation. Refer to the individual scenario for details.

General Guidelines

Each of the following sections discusses a single, fairly specific data transfer scenario. However, data transfers are often more complex and might involve aspects of several scenarios. You typically do not know, in advance, which scenario you will actually need to handle. Here are a few general guidelines to keep in mind.

For data sources:

  • The Shell clipboard formats, with the exception of CF_HDROP, are not predefined. Each format you want to use must be registered by calling RegisterClipboardFormat.
  • Include as many formats as you can support. You generally don't know where the data object will be dropped. This practice improves the odds that the data object will contain a format that the drop target can accept.
  • Existing files should be offered with the CF_HDROP format.
  • Offer file-like data with CFSTR_FILECONTENTS/CFSTR_FILEDESCRIPTOR formats. This approach allows the target to create a file from a data object without needing to know anything about the underlying data storage. You should normally present the data as an IStream interface. This data transfer mechanism is more flexible than a global memory object and uses much less memory.
  • Use standard feedback cursors.
  • Support left and right drag.
  • Use the data object itself from an embedded object. This approach allows your application to retrieve any extra formats the data object has to offer and avoids creating an extra layer of containment. For instance, an embedded object from server A is dragged from server/container B and dropped on container C. C should create an embedded object of server A, not an embedded object of server B containing an embedded object of server A.
  • Remember that the Shell might use optimized moves or delete-on-paste operations when moving files. Your application should be able to recognize these operations and respond appropriately.

For data targets:

  • The Shell clipboard formats, with the exception of CF_HDROP, are not predefined. Each format you want to use must be registered by calling RegisterClipboardFormat.
  • Implement and register an OLE drop target. Avoid using Microsoft® Windows® 3.1 targets or the WM_DROPFILES message, if possible.
  • The formats contained by a data object vary, depending on where the object comes from. Since you generally don't know in advance where a data object comes from, don't assume that a particular format will be present. The data object should enumerate the formats in order of quality, starting with the best. Thus, to get the best available format, applications normally enumerate the available formats and use the first format in the enumeration that they can support.
  • Support right-drag. You can customize the drag shortcut menu by creating a drag-and-drop handler
  • If your application will accept existing files, it must be able to handle the CF_HDROP format.
  • In general, applications that accept files should also handle the CFSTR_FILECONTENTS/CFSTR_FILEDESCRIPTOR formats. While files from the file system have the CF_HDROP format, files from providers such as namespace extensions generally use CFSTR_FILECONTENTS/CFSTR_FILEDESCRIPTOR. Examples include Windows® CE folders, FTP folders, Web folders, and CAB folders. The source normally implements an IStream interface to present data from its storage as a file.
  • Remember that the Shell might use optimized moves or delete-on-paste operations when moving files. Your application should be able to recognize these operations and respond appropriately.

Copying File Names from the Clipboard to an Application

Scenario: A user selects one or more files in Windows® Explorer and copies them to the Clipboard. Your application extracts the file names and pastes them into the document.

This scenario could be used, for instance, to allow a user to create an HTML link by cutting and pasting the file to your application. Your application can then extract the file name from the data object and process it to create an anchor tag.

When a user selects a file in Windows Explorer and copies it to the Clipboard, the Shell creates a data object. It then calls OleSetClipboard to place a pointer to the data object's IDataObject interface on the Clipboard.

When the user selects the Paste command from your application's menu or toolbar:

  1. Call OleGetClipboard to retrieve the data object's IDataObject interface.
  2. Call IDataObject::EnumFormatEtc to request an enumerator object.
  3. Use the enumerator object's IEnumFORMATETC interface to enumerate the formats contained by the data object.

Note The final two steps in this procedure are included for completeness. They are typically not necessary for simple file transfers. All data objects used for this type of data transfer should contain the CF_HDROP format, which can be used to determine the names of the files contained by the object. However, for more general data transfers, you should enumerate the formats and select the best one that your application can handle.

Extracting the File Names from the Data Object

The next step is to extract one or more file names from the data object and paste them into your application. Note that the procedure discussed in this section for extracting a file name from a data object applies equally well to drag-and-drop transfers.

The simplest way to retrieve file names from a data object is the CF_HDROP format:

  1. Call IDataObject::GetData. Set the cfFormat member of the FORMATETC structure to CF_HDROP and the tymed member to TYMED_HGLOBAL. The dwAspect member is normally set to DVASPECT_CONTENT. However, if you need to have the file's path in short (8.3) format, set dwAspect to DVASPECT_SHORT.

    When IDataObject::GetData returns, the hGlobal member of the STGMEDIUM structure points to a global memory object that contains the data.

  2. Create an HDROP variable and set it to the hGlobal member of the STGMEDIUM structure. The HDROP variable is now a handle to a DROPFILES structure followed by a double NULL-terminated string containing the fully qualified file paths of the copied files.
  3. Determine how many file paths are in the list by calling DragQueryFile with the iFile parameter set to 0xFFFFFFFF. The function returns the number of file paths in the list. The file path's zero-based index in this list is used in the next step to identify a particular path.
  4. Extract the file paths from the global memory object by calling DragQueryFile once for each file, with iFile set to the file's index.
  5. Process the file paths as needed and paste them into your application.
  6. Call ReleaseStgMedium and pass in the pointer to the STGMEDIUM structure that you passed to IDataObject::GetData in step 1. Once you have released the structure, the HDROP value that you created in step 2 is no longer valid and should not be used.

Copying the Contents of a Dropped File into an Application

Scenario: A user drags one or more files from Windows Explorer and drops them on your application's window. Your application extracts the content of the file(s) and pastes it into the application.

This scenario uses drag-and-drop to transfer the files from Windows Explorer to the application. Prior to the operation, your application must:

  1. Call RegisterClipboardFormat to register any needed Shell clipboard formats.
  2. Call RegisterDragDrop to register a target window and your application's IDropTarget interface.

After the user initiates the operation by selecting one or more files and starting to drag them:

  1. Windows Explorer creates a data object and loads the supported formats into it.
  2. Windows Explorer calls DoDragDrop to initiate the drag loop.
  3. When the drag image reaches your target window, the system notifies you by calling IDropTarget::DragEnter.
  4. To determine what the data object contains, call the data object's IDataObject::EnumFormatEtc method. Use the enumerator object returned by the method to enumerate the formats contained by the data object. If your application does not want to accept any of these formats, return DROPEFFECT_NONE. For the purposes of this scenario, your application should ignore any data objects that do not contain formats used to transfer files, such as CF_HDROP.
  5. When the user drops the data, the system calls IDropTarget::Drop.
  6. Use the IDataObject interface to extract the contents of the files.

There are several different ways to extract the contents of a Shell object from a data object. In general, use the following order:

  • If the file contains a CF_TEXT format, the data is ANSI text. You can use the CF_TEXT format to extract the data, rather than opening the file itself.
  • If the file contains a linked or embedded OLE object, the data object contains a CF_EMBEDDEDOBJECT format. Use standard OLE techniques to extract the data. Scrap files always contain a CF_EMBEDDEDOBJECT format.
  • If the Shell object is from the file system, the data object contains a CF_HDROP format with the names of the files. Extract the file name from CF_HDROP and call OleCreateFromFile to create a new linked or embedded object. For a discussion of how to retrieve a file name from a CF_HDROP format, see Copying File Names from the Clipboard to an Application.
  • If the data object contains a CFSTR_FILEDESCRIPTOR format, you can extract a file's contents from the file's CFSTR_FILECONTENTS format. For a discussion of this procedure, see Using the CFSTR_FILECONTENTS Format to Extract Data from a File.
  • Prior to Shell version 4.71, an application indicated that it was transferring a shortcut file type by setting FD_LINKUI in the dwFlags member of the FILEDESCRIPTOR structure. For later versions of the Shell, the preferred way to indicate that shortcuts are being transferred is to use the CFSTR_PREFERREDDROPEFFECT format set to DROPEFFECT_LINK. This approach is much more efficient than extracting the FILEDESCRIPTOR structure just to check a flag.

If the data extraction process will be lengthy, you might want to do the operation asynchronously on a background thread. Your primary thread can then proceed without unnecessary delays. For a discussion of how to handle asynchronous data extraction, see Dragging and Dropping Shell Objects Asynchronously.

Using the CFSTR_FILECONTENTS Format to Extract Data from a File

The CFSTR_FILECONTENTS format provides a very flexible and powerful way to transfer the contents of a file. It is not even necessary for the data to be stored as a single file. All that is required for this format is that the data object present the data to the target as if it were a file. For instance, the actual data might be a section of a text document or a block of data extracted from a database. The target can treat the data as a file and doesn't need to know anything about the underlying storage mechanism.

Namespace extensions normally use CFSTR_FILECONTENTS to transfer data because this format does not assume any particular storage mechanism. A namespace extension can use whatever storage mechanism is convenient, and use this format to present its objects to applications as if they were files.

The data transfer mechanism for CFSTR_FILECONTENTS is normally TYMED_ISTREAM. Transferring an IStream interface pointer requires much less memory than loading the data into a global memory object, and IStream is a simpler way to represent data than IStorage.

A CFSTR_FILECONTENTS format is always accompanied by a CFSTR_FILEDESCRIPTOR format. You must examine the contents of this format first. If more than one file is being transferred, the data object will actually contain multiple CFSTR_FILECONTENTS formats, one for each file. The CFSTR_FILEDESCRIPTOR format contains the name and attributes of each file, and provides an index value for each file that is needed to extract a particular file's CFSTR_FILECONTENTS format.

To extract a CFSTR_FILECONTENTS format:

  1. Extract the CFSTR_FILEDESCRIPTOR format as a TYMED_HGLOBAL value.
  2. The hGlobal member of the returned STGMEDIUM structure points to a global memory object. Lock that object by passing the hGlobal value to GlobalLock.
  3. Cast the pointer returned by GlobalLock to a FILEGROUPDESCRIPTOR pointer. It will point to a FILEGROUPDESCRIPTOR structure followed by one or more FILEDESCRIPTOR structures. Each FILEDESCRIPTOR structure contains a description of a file that is contained by one of the accompanying CFSTR_FILECONTENTS formats.
  4. Examine the FILEDESCRIPTOR structures to determine which one corresponds to the file you want to extract. The zero-based index of that FILEDESCRIPTOR structure is used to identify the file's CFSTR_FILECONTENTS format. Because the size of a global memory block is not byte-precise, use the structure's nFileSizeLow and nFileSizeHigh members to determine how many bytes represent the file in the global memory object.
  5. Call IDataObject::GetData with the cfFormat member of the FORMATETC structure set to the CFSTR_FILECONTENTS value and the lIndex member set to the index that you determined in the previous step. The tymed member is typically set to TYMED_HGLOBAL | TYMED_ISTREAM | TYMED_ISTORAGE. The data object can then choose its preferred data transfer mechanism.
  6. The STGMEDIUM structure that IDataObject::GetData returns will contain a pointer to the file's data. Examine the tymed member of the structure to determine the data transfer mechanism.
  7. If tymed is set to TYMED_ISTREAM or TYMED_ISTORAGE, use the interface to extract the data. If tymed is set to TYMED_HGLOBAL, the data is contained in a global memory object. For a discussion of how to extract data from a global memory object, see How to Extract a Global Memory Object from a Data Object.
  8. Call GlobalUnlock to unlock the global memory object that you locked in step 2.

Handling Optimized Move Operations

Scenario: A file is moved from the file system to a namespace extension using an optimized move.

In a conventional move operation, the target makes a copy of the data and the source deletes the original. This procedure can be inefficient because it requires two copies of the data. With large objects such as databases, a conventional move operation might not even be practical.

With an optimized move, the target uses its understanding of how the data is stored to handle the entire move operation. There is never a second copy of the data, and there is no need for the source to delete the original data. Shell data is well suited to optimized moves because the target can handle the entire operation using the Shell API. A typical example is moving files. Once the target has the path of a file to be moved, it can use SHFileOperation to move it. There is no need for the source to delete the original file.

Note The Shell normally uses an optimized move to move files. To handle Shell data transfer properly, your application must be capable of detecting and handling an optimized move.

Optimized moves are handled in the following way:

  1. The source calls DoDragDrop with the dwEffect parameter set to DROPEFFECT_MOVE to indicate that the source objects can be moved.
  2. The target receives the DROPEFFECT_MOVE value through one of its IDropTarget methods, indicating that a move is allowed.
  3. The target either copies the object (unoptimized move) or moves the object (optimized move).
  4. The target then tells the source whether it needs to delete the original data.

    An optimized move is the default operation, with the data deleted by the target. To inform the source that an optimized move was performed:

    • The target sets the pdwEffect value it received through its IDropTarget::Drop method to some value other than DROPEFFECT_MOVE. It is typically set to either DROPEFFECT_NONE or DROPEFFECT_COPY. The value will be returned to the source by DoDragDrop.
    • The target also calls the data object's IDataObject::SetData method and passes it a CFSTR_PERFORMEDDROPEFFECT format identifier set to DROPEFFECT_NONE. This method call is necessary because some drop targets might not set the pdwEffect parameter of DoDragDrop properly. The CFSTR_PERFORMEDDROPEFFECT format is the reliable way to indicate that an optimized move has taken place.

    If the target did an unoptimized move, the data must be deleted by the source. To inform the source that an unoptimized move was performed:

    • The target sets the pdwEffect value it received through its IDropTarget::Drop method to DROPEFFECT_MOVE. The value will be returned to the source by DoDragDrop.
    • The target also calls the data object's IDataObject::SetData method and passes it a CFSTR_PERFORMEDDROPEFFECT format identifier set to DROPEFFECT_MOVE. This method call is necessary because some drop targets might not set the pdwEffect parameter of DoDragDrop properly. The CFSTR_PERFORMEDDROPEFFECT format is the reliable way to indicate that an unoptimized move has taken place.
  5. The source inspects the two values that can be returned by the target. If both are set to DROPEFFECT_MOVE, it completes the unoptimized move by deleting the original data. Otherwise, the target did an optimized move and the original data has been deleted.

Handling Delete-on-Paste Operations

Scenario: One or more files are cut from a folder in Windows Explorer and pasted into a namespace extension. Windows Explorer leaves the files highlighted until it receives feedback on the outcome of the paste operation.

Traditionally, when a user cuts data it immediately disappears from view. This might not be efficient, and it can lead to usability problems if the user becomes concerned about what has happened to the data. An alternative approach is to use a delete-on-paste operation.

With a delete-on-paste operation, the selected data is not immediately removed from view. Instead, the source application marks it as selected, perhaps by changing the font or background color. After the target application has pasted the data, it notifies the source about the outcome of the operation. If the target performed an optimized move, the source can simply update its display. If the target performed a normal move, the source must also delete its copy of the data. If the paste fails, the source application restores the selected data to its original appearance.

Note The Shell normally uses delete-on-paste when a cut/paste operation is used to move files. Delete-on-paste operations with Shell objects normally use an optimized move to move the files. To handle Shell data transfer properly, your application must be capable of detecting and handling delete-on-paste operations.

The essential requirement for delete-on-paste is that the target must report the outcome of the operation to the source. However, standard clipboard techniques cannot be used to implement delete-on-paste because they do not provide a way for the target to communicate with the source. Instead, the target application uses the data object's IDataObject::SetData method to report the outcome to the data object. The data object can then communicate with the source through a private interface.

The basic procedure for a delete-on-paste operation is as follows:

  1. The source marks the screen display of the selected data.
  2. The source creates a data object. It indicates a cut operation by adding the CFSTR_PREFERREDDROPEFFECT format with a data value of DROPEFFECT_MOVE.
  3. The source places the data object on the Clipboard using OleSetClipboard.
  4. The target retrieves the data object from the Clipboard using OleGetClipboard.
  5. The target extracts the CFSTR_PREFERREDDROPEFFECT data. If it is set to only DROPEFFECT_MOVE, the target can either do an optimized move or simply copy the data.
  6. If the target does not do an optimized move, it calls the IDataObject::SetData method with the CFSTR_PERFORMEDDROPEFFECT format set to DROPEFFECT_MOVE.
  7. When the paste is complete, the target calls the IDataObject::SetData method with the CFSTR_PASTESUCCEEDED format set to DROPEFFECT_MOVE.
  8. When the source's IDataObject::SetData method is called with the CFSTR_PASTESUCCEEDED format set to DROPEFFECT_MOVE, it must check to see if it also received the CFSTR_PERFORMEDDROPEFFECT format set to DROPEFFECT_MOVE. If both formats are sent by the target, the source will have to delete the data. If only the CFSTR_PASTESUCCEEDED format is received, the source can simply remove the data from its display. If the transfer fails, the source updates the display to its original appearance.

Transfering Data to and from Virtual Folders

Scenario: A user drags an object from or drops it on a virtual folder.

Virtual folders contain objects that are generally not part of the file system. Some virtual folders, such as the Recycle Bin, can represent data that is stored on the hard drive but not as ordinary file system objects. Some can represent stored data that is on a remote system, such as a hand-held PC, or an FTP site. Others, such as the Printers folder, contain objects that do not represent stored data at all. While some virtual folders are part of the system, developers can also create and install custom virtual folders by implementing a namespace extension.

Regardless of the type of data or how it is stored, the folder and file objects that are contained by a virtual folder are presented by the Shell as if they were normal files and folders. It is the responsibility of the virtual folder to take whatever data it contains and present it to the Shell appropriately. This requirement means that virtual folders normally support drag-and-drop and clipboard data transfers.

There are thus two groups of developers who need to be concerned with data transfer to and from virtual folders:

  • Developers whose applications need to accept data that is transferred from a virtual folder.
  • Developers whose namespace extensions need to properly support data transfer.

Accepting Data from a Virtual Folder

Virtual folders can represent virtually any type of data and can store that data in any way they choose. Some virtual folders might actually contain normal file system files and folders. Others might, for instance, pack all their objects into a single document or database.

When a file system object is transferred to an application, the data object normally contains a CF_HDROP format with the object's fully qualified path. Your application can extract this string and use the normal file system functions to open the file and extract its data. However, because virtual folders typically do not contain normal file system objects, they generally do not use CF_HDROP.

Instead of CF_HDROP, data is normally transferred from virtual folders with the CFSTR_FILEDESCRIPTOR/CFSTR_FILECONTENTS formats. The CFSTR_FILECONTENTS format has two advantages over CF_HDROP:

  • No particular method of data storage is assumed.
  • The format is more flexible. It supports three data transfer mechanisms: a global memory object, an IStream interface, or an IStorage interface.

Global memory objects are rarely used to transfer data to or from virtual objects because the data must be copied into memory in its entirety. Transferring an interface pointer requires almost no memory and is much more efficient. With very large files, an interface pointer might be the only practical data transfer mechanism. Typically, data is represented by an IStream pointer, because that interface is somewhat more flexible than IStorage. The target extracts the pointer from the data object and uses the interface methods to extract the data.

For further discussion of how to handle the CFSTR_FILEDESCRIPTOR/CFSTR_FILECONTENTS formats, see Using the CFSTR_FILECONTENTS Format to Extract Data from a File.

Transferring Data to and from a NameSpace Extension

When you implement a namespace extension, you will normally want to support drag-and-drop capabilities. Follow the recommendations for drop sources and targets discussed in General Guidelines. In particular, a namespace extension must:

  • Be able to handle the CFSTR_FILEDESCRIPTOR/CFSTR_FILECONTENTS formats. These two formats are normally used to transfer objects to and from namespace extensions.
  • Be able to handle optimized moves. The Shell expects that Shell objects will be moved with an optimized move.
  • Be able to handle a delete-on-paste operation. The Shell uses delete-on-paste when objects are moved from the Shell with a cut/paste operation.
  • Be able to handle data transfer through an IStream or IStorage interface. Data transfer to or from a virtual folder is normally handled by transferring one of these two interface pointers, typically an IStream pointer. The target then calls the interface methods to extract the data:
    • As a drop source, the namespace extension must extract the data from storage and pass it through this interface to the target.
    • As a drop target, a namespace extension must accept data from a source through this interface and store it properly.

For a more thorough discussion of how to implement a namespace extension, see Creating a Shell Namespace Extension.

Dropping Files on the Recycle Bin

Scenario: The user drops a file on the Recycle Bin. Your application or namespace extension deletes the original file.

The Recycle Bin is a virtual folder that is used as a repository for files that are no longer needed. As long as the Recycle Bin has not been emptied, the user can later recover the file and return it to the file system.

For the most part, transferring Shell objects to the Recycle Bin works much like any other folder. However, when a user drops a file on the Recycle Bin, the source needs to delete the original, even if the feedback from the folder indicates a copy operation. Normally, a drop source has no way of knowing which folder its data object has been dropped on. However, for Windows® 2000 and later systems, when a data object is dropped on the Recycle Bin, the Shell will call the data object's IDataObject::SetData method with a CFSTR_TARGETCLSID format set to the Recycle Bin's CLSID (CLSID_RecycleBin). To handle the Recycle Bin case properly, your data object should be able to recognize this format and communicate the information to the source through a private interface.

Note When IDataObject::SetData is called with a CFSTR_TARGETCLSID format set to CLSID_RecycleBin, the data source should close any open handles to the objects that are being transferred before returning from the method. Otherwise, you might create sharing violations.

Creating and Importing Scrap Files

Scenario: A user drags some data from an OLE application's data file and drops it on the desktop or Windows Explorer.

Windows allows users to drag an object from an OLE application's data file and drop it on the desktop or a file system folder. This operation creates a scrap file, which contains the data or a link to the data. The file name is taken from the short name registered for the CLSID of the object and the CF_TEXT data. For the Shell to create a scrap file containing data, the application's IDataObject interface must support the CF_EMBEDSOURCE clipboard format. To create a file containing a link, IDataObject must support the CF_LINKSOURCE format.

There are also three optional features that an application can implement to support scrap files:

  • Round-trip support
  • Cached data formats
  • Delayed rendering

Round-trip Support

A round trip involves transferring a data object to another container and then back to the original document. For instance, a user could transfer a group of cells from a spreadsheet to the desktop, creating a scrap file with the data. If the user then transfers the scrap back to the spreadsheet, the data needs to be integrated into the document as it was before the original transfer.

When the Shell creates the scrap file, it represents the data as an embedding object. When the scrap is transferred to another container, it is transferred as an embedding object, even if it is being returned to the original document. Your application is responsible for determining the data format contained in the scrap and putting the data back into its native format if necessary.

To establish the format of the embedded object, determine its CLSID by retrieving the object's CF_OBJECTDESCRIPTOR format. If the CLSID indicates a data format that belongs to the application, it should transfer the native data instead of calling OleCreateFromData.

Cached Data Formats

When the Shell creates a scrap file, it checks the registry for the list of available formats. By default, there are two formats available: CF_EMBEDSOURCE and CF_LINKSOURCE. However, there are a number of scenarios where applications might need to have scrap files in different formats:

  • To allow scraps to be transferred to non-OLE containers, which cannot accepted embedded object formats.
  • To allow suites of applications to communicate with a private format.
  • To make round trips easier to handle.

Applications can add formats to the scrap by caching them in the registry. There are two types of cached formats:

  • Priority cache formats. For these formats, the data is copied in its entirety into the scrap from the data object.
  • Delay-rendered formats. For these formats, the data object is not copied to the scrap. Instead, rendering is delayed until a target requests the data. Delay-rendering is discussed in more detail in the next section.

To add a priority cache or delay-rendered format, create a DataFormat subkey under the CLSID key of the application that is the source of the data. Under that subkey, create a PriorityCacheFormats or DelayRenderFormats subkey. For each priority cache or delay-rendered format, create a numbered subkey starting with zero. Set the value of this key to either a string with the registered name of the format or a #X value, where X represents the format number of a standard clipboard format.

The following sample shows cached formats for two applications. The MyProg1 application has the rich-text format as a priority cache format, and a private format "My Format" as a delay-rendered format. The MyProg2 application has the CF_BITMAP format ("#8") as a priority cache format.

HKEY_CLASSES_ROOT
    CLSID
        {GUID}="MyProg1"
            DataFormats
                PriorityCacheFormats
                    0="Rich Text Format"
                DelayRenderFormats
                    0="My Format"
        {GUID}="MyProg2"
            DataFormats
                PriorityCacheFormats
                    0="#8"

Additional formats can be added by creating additional numbered subkeys.

Delayed Rendering

A delayed rendering format allows an application to create a scrap file but delay the expense of rendering the data until it is requested by a target. The IDataObject interface of a scrap will offer the delayed rendering formats to the target along with native and cached data. If the target requests a delayed rendering format, the Shell will run the application and provide the data to the target from the active object.

Note Because delayed rendering is somewhat risky, it should be used with caution. It will not work if the server is not available, or on applications that are not OLE-enabled.

Dragging and Dropping Shell Objects Asynchronously

Scenario: A user transfers a large block of data from source to target. To avoid blocking both applications for a significant amount of time, the target extracts the data asynchronously.

Normally, drag-and-drop is a synchronous operation. In brief:

  1. The drop source calls DoDragDrop and blocks its primary thread until the function returns. Blocking the primary thread normally blocks user interface (UI) processing.
  2. After the target's IDropTarget::Drop method is called, the target extracts the data from the data object on its primary thread. This procedure normally blocks the target's UI processing for the duration of the extraction process.
  3. Once the data has been extracted, the target returns the IDropTarget::Drop call, the system returns DoDragDrop, and both threads can proceed.

In short, synchronous data transfer can block the primary threads of both applications for a significant amount of time. In particular, both threads must wait while the target extracts the data. For small amounts of data, the time required to extract data is small and synchronous data transfer works quite well. However, synchronously extracting large amounts of data can cause lengthy delays and interfere with the UI of both target and source.

The IAsyncOperation interface is an optional interface that can be implemented by a data object. It gives the drop target the ability to extract data from the data object asynchronously on a background thread. Once data extraction is handed off to the background thread, the primary threads of both applications are free to proceed.

Using IASyncOperation

The purpose of IAsyncOperation is to allow the drop source and drop target to negotiate whether data can be extracted asynchronously. The following procedure outlines how the drop source uses the interface:

  1. Create a data object that exposes IAsyncOperation.
  2. Call IAsyncOperation::SetAsyncMode with fDoOpAsync set to VARIANT_TRUE to indicate that an asynchronous operation is supported.
  3. After DoDragDrop returns, call IAsyncOperation::InOperation:
    • If IAsyncOperation::InOperation fails or returns VARIANT_FALSE, a normal synchronous data transfer has taken place and the data extraction process is finished. The source should do any cleanup that is required, and proceed.
    • If IAsyncOperation::InOperation returns VARIANT_TRUE, the data is being extracted asynchronously. Cleanup operations should be handled by IAsyncOperation::EndOperation.
  4. Release the data object.
  5. When the asynchronous data transfer is complete, the data object normally notifies the source through a private interface.

The following procedure outlines how the drop target uses the IAsyncOperation interface to extract data asynchronously:

  1. When the system calls IDropTarget::Drop, call IDataObject::QueryInterface and request an IAsyncOperation interface (IID_IAsyncOperation) from the data object.
  2. Call IAsyncOperation::GetAsyncMode. If the method returns VARIANT_TRUE, the data object supports asynchronous data extraction.
  3. Create a separate thread to handle data extraction and call IAsyncOperation::StartOperation.
  4. Return the IDropTarget::Drop call, as you would for a normal data transfer operation. DoDragDrop will return and unblock the drop source. Do not call IDataObject::SetData to indicate the outcome of an optimized move or delete-on-paste operation. Wait until the operation is finished.
  5. Extract the data on the background thread. The target's primary thread is unblocked and free to proceed.
  6. If the data transfer was an optimized move or delete-on-paste operation, call IDataObject::SetData to indicate the outcome.
  7. Notify the data object that extraction is finished by calling IAsyncOperation::EndOperation.


Debugging with the Shell

This overview explains how to debug Shell and namespace extension DLLs.

  • Running the Shell Under a Debugger
  • Running and Testing Shell Extensions on Windows NT
  • Unloading the DLL

Running the Shell Under a Debugger

To debug your extension, you need to execute the Shell from the debugger. Follow these steps:

  1. Load the extension's project into the debugger, but do not run it.
  2. From the Start menu on the Microsoft® Windows® taskbar, choose Shut Down.
  3. Press CTRL+ALT+SHIFT, and click No in the Shut Down Windows dialog box. On Windows 2000, click Cancel instead of No. The Shell is now shut down, but all other applications are still running, including the debugger.
  4. Set the debugger to run the extension DLL with Explorer.exe from the Windows directory.
  5. Run the project from the debugger. The Shell will start up as usual, but the debugger will be attached to the Shell's process.

Running and Testing Shell Extensions on Windows NT

You can run and test your Microsoft® Windows NT® extensions in a separate Windows Explorer process to avoid stopping and restarting the desktop and taskbar. Your desktop and taskbar can still be used while you run and test the extensions.

To enable this feature, add the following value to the registry.

HKEY_CURRENT_USER\
   Software\
      Microsoft\
         Windows\
            CurrentVersion\
               Explorer\
                  DesktopProcess(REG_DWORD) = 1

For this value to take effect, you must log off and log on again. This setting causes the desktop and taskbar windows to be created in one Explorer.exe process, and all other Explorer and folder windows to be opened in a different Explorer.exe process.

In addition to making running and testing your extensions more convenient, this setting also makes the desktop more robust as it relates to Shell extensions. Many such extensions (shortcut menu extensions, for example) will be loaded into the nondesktop Explorer.exe process. If this process terminates, the desktop and taskbar will be unaffected, and the next Explorer or folder window will recreate the terminated process.

Unloading the DLL

The Shell automatically unloads a DLL when the DLL's usage count is zero, but only after the DLL has not been used for a period of time. This inactive period might be unacceptably long at times, especially when a Shell extension DLL is being debugged. For operating systems prior to Windows 2000, you can shorten the inactive period by adding the following information to the registry.

HKLM
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  AlwaysUnloadDll


Scriptable Shell Objects

The Microsoft® Windows® Shell provides a powerful set of automation objects that enable you to program the Shell with Microsoft® Visual Basic® and scripting languages such as Microsoft® JScript® (compatible with ECMA 262 language specification) and Visual Basic Scripting Edition (VBScript). You can use these objects to access many of the Shell's features and dialog boxes. For example, you can access the file system, launch programs, and change system settings.

This section introduces the scriptable Shell objects.

  • Shell Versions
  • Instantiating Shell Objects
  • Shell Object
  • Folder Objects
  • Shell Objects Reference

Shell Versions

Many of the Shell objects became available in version 4.71 of the Shell. Others are available in version 5.00 and later. This means that on computers running Microsoft® Windows® 95 or Microsoft® Windows NT® 4.0, the Shell objects are available only if the integrated desktop is installed. Version 4.71 of the Shell is on all Microsoft® Windows® 98 computers, and version 5.00 is on all Microsoft® Windows® 2000 computers. The following table lists each Shell object under the version of the Shell in which the object became available.

Version 4.71 | Version 5.00
Folder | DIDiskQuotaUser
FolderItemVerb | DiskQuotaControl
FolderItemVerbs | Folder2
Shell | FolderItem
ShellFolderView | FolderItems
ShellUIHelper | FolderItems2
ShellWindows | IShellDispatch2
WebViewFolderContents | IShellLinkDual2
 | ShellFolderItem
 | ShellFolderViewOC
 | ShellLinkObject

Instantiating Shell Objects

To instantiate the Shell objects in Visual Basic applications with early binding, add references to the following libraries in your project:

  • Microsoft Internet Controls (SHDocVw)
  • Microsoft Shell Controls and Automation (Shell32)

Late Binding

You can also instantiate many of the Shell objects with late binding. This approach works in Visual Basic applications and in script. The following example shows how to instantiate the Shell object in JScript.

<SCRIPT LANGUAGE="JScript">
<!--

  function fnCreateShell()
  {
      // Instantiate the Shell object and invoke its FileRun method.
    var oShell = new ActiveXObject("Shell.Application");
    oShell.FileRun;
  }

-->
</SCRIPT>

The following example shows how to instantiate the Folder object in VBScript.

<SCRIPT LANGUAGE="VBScript">
<!--

  function fnCreateFolder()

    dim oShell
    dim oFolder
    dim sDir

    sDir = "C:\SomePath"
    set oShell = CreateObject("Shell.Application")
    set oFolder = oShell.NameSpace(sDir)

  end function

-->
</SCRIPT>

In the preceding example, sDir is the path to the Folder object. Note that the ShellSpecialFolderConstants enumeration values are not available in script.

The ProgID for each of the Shell objects is shown in the following table.

Object | ProgID
DIDiskQuotaUser | Microsoft.DiskQuota.1
DiskQuotaControl | Cannot late bind
Folder | Shell.Application.NameSpace("...")
Folder2 | Shell.Application.NameSpace("...")
FolderItem Shell.Application.NameSpace("...").Self or
Folder.Items.Item or Folder.ParseName
FolderItems | Folder.Items
FolderItems2 | Folder.Items
FolderItemVerb | Shell.NameSpace("...").Self.Verbs.Item(i)
FolderItemVerbs FolderItem.Verbs or
Shell.NameSpace("...").Self.Verbs
IShellDispatch2 | Shell.Application
IShellLinkDual2 Shell.NameSpace("...").Self.GetLink or
Shell.NameSpace("...").Items(i).GetLink
Shell | Shell.Application
ShellFolderItem Shell.NameSpace("...").Self or
Shell.NameSpace("...").Items(i)
ShellFolderView | Cannot late bind
ShellFolderViewOC | Cannot late bind
ShellLinkObject Shell.NameSpace("...").Self.GetLink or
Shell.NameSpace("...").Items(i).GetLink
ShellUIHelper | Cannot late bind
ShellWindows Shell.Windows or
ShellWindows._NewEnum
WebViewFolderContents | Cannot late bind

HTML OBJECT Element

You can also use the OBJECT element to instantiate Shell objects on an HTML page. To do this, set the OBJECT element's ID attribute to the variable name you will use in your scripts, and identify the object using its registered number (CLASSID). The following HTML creates an instance of the ShellFolderItem object using the OBJECT element.

<OBJECT ID="oShFolderItem"
    NAME="Shell Folder Item Object"
    CLASSID="clsid:2fe352ea-fd1f-11d2-b1f4-00c04f8eeb3e">
</OBJECT>

The following table lists each Shell object and its respective CLASSID.

Object | CLASSID
DIDiskQuotaUser | 7988B571-EC89-11cf-9C00-00AA00A14F56
DiskQuotaControl | 7988B571-EC89-11cf-9C00-00AA00A14F56
Folder | BBCBDE60-C3FF-11CE-8350-444553540000
Folder2 | f0d2d8ef-3890-11d2-bf8b-00c04fb93661
FolderItem | 744129E0-CBE5-11CE-8350-444553540000
FolderItems | 744129E0-CBE5-11CE-8350-444553540000
FolderItems2 | C94F0AD0-F363-11d2-A327-00C04F8EEC7F
FolderItemVerb | 08EC3E00-50B0-11CF-960C-0080C7F4EE85
FolderItemVerbs | 1F8352C0-50B0-11CF-960C-0080C7F4EE85
IShellDispatch2 | A4C6892C-3BA9-11d2-9DEA-00C04FB16162
IShellLinkDual2 | 317EE249-F12E-11d2-B1E4-00C04F8EEB3E
Shell | 13709620-C279-11CE-A49E-444553540000
ShellFolderItem | 2fe352ea-fd1f-11d2-b1f4-00c04f8eeb3e
ShellFolderView | 62112AA1-EBE4-11cf-A5FB-0020AFE7292D
ShellFolderViewOC | 4a3df050-23bd-11d2-939f-00a0c91eedba
ShellLinkObject | 11219420-1768-11d1-95BE-00609797EA4F
ShellUIHelper | 64AB4BB7-111E-11D1-8F79-00C04FC2FBE1
ShellWindows | 9BA05972-F6A8-11CF-A442-00A0C90A8F39
WebViewFolderContents | 1820FED0-473E-11D0-A96C-00C04FD705A2

Shell Object

The Shell object represents the objects in the Windows Shell. You can use the methods exposed by the Shell object to:

  • Open, explore, and browse for folders.
  • Minimize, restore, cascade, or tile open windows.
  • Launch Control Panel applications.
  • Display system dialog boxes.

Users are perhaps most familiar with the commands they access from the Start menu and the taskbar's shortcut menu. The taskbar's shortcut menu appears when users right-click the taskbar. The following HTML Application (HTA) produces a start page with buttons that implement many of the Shell object's methods. Some of these methods implement features on the Start menu and the taskbar's shortcut menu.

<HTML>
<HEAD>
<TITLE>Start Page</TITLE>

<OBJECT ID="oShell"
    CLASSID="clsid:13709620-C279-11CE-A49E-444553540000">
</OBJECT>

<STYLE>
    INPUT {width: 200}
</STYLE>

<SCRIPT LANGUAGE="VBScript">
<!--
  function fnStart(sMethod)
    select case sMethod
      case 0
          'Minimizes all windows on the desktop
        oShell.MinimizeAll
      case 1
          'Displays the Run dialog box
        oShell.FileRun
      case 2
          'Displays the Shut Down Windows dialog box
        oShell.ShutdownWindows
      case 3
          'Displays the Find dialog box
        oShell.FindFiles
      case 4
          'Displays the Date/Time dialog box
        oShell.SetTime
      case 5
          'Displays the Internet Properties dialog box
        oShell.ControlPanelItem "INETCPL.cpl"
      case 6
          'Explores the My Documents folder
        oShell.Explore "C:\My Documents"
      case 7
          'Enables user to select folder from Program Files
        oShell.BrowseForFolder 0, "My Programs", 0, "C:\Program Files"
      case 8
          'Opens the Favorites folder
        oShell.Open "C:\WINDOWS\Favorites"
      case 9
          'Displays the Taskbar Properties dialog box
        oShell.TrayProperties
    end select
  end function
-->
</SCRIPT>

</HEAD>

<BODY>

<H1>Start...</H1>
<INPUT type="button" value="Edit Taskbar Properties" onclick="fnStart(9)"><br>
<INPUT type="button" value="Open Favorites Folder" onclick="fnStart(8)"><br>
<INPUT type="button" value="Browse Program Files" onclick="fnStart(7)"><br>
<INPUT type="button" value="Explore My Documents" onclick="fnStart(6)"><br>
<INPUT type="button" value="Modify Internet Properties" onclick="fnStart(5)"><br>
<INPUT type="button" value="Set System Time" onclick="fnStart(4)"><br>
<INPUT type="button" value="Find a File or Folder" onclick="fnStart(3)"><br>
<INPUT type="button" value="Shut Down Windows" onclick="fnStart(2)"><br>
<INPUT type="button" value="Run" onclick="fnStart(1)">
<INPUT type="button" value="Minimize All Windows" onclick="fnStart(0)">
</BODY>
</HTML>

Security

As an application, an HTA runs under a different security model than a Web page. To interact with a Web page that implements the functionality of the Shell objects, users must enable the "Initialize and script ActiveX Controls not marked as safe" option for the security zone in which they are viewing the page.

Folder Objects

The Folder object represents a Shell folder. You can use the methods exposed by the Folder object to:

  • Get information about a folder.
  • Create subfolders.
  • Copy and move file objects into the folder.

The FolderItem object represents an item in a Shell folder. Its properties enable you to retrieve information about the item. You can use the methods exposed by this object to execute an item's verbs, or to retrieve information about an item's FolderItemVerbs object.

The FolderItems object represents a collection of items in a Shell folder. Its methods and properties enable you to retrieve information about the collection.

The following Visual Basic example shows the relationship between several of the folder objects and how they can be used together. When the user clicks the command button called cmdGetPath, the program displays a dialog box that enables the user to select a folder from My Computer, where ssfDRIVES is the ShellSpecialFolderConstants enumeration value for My Computer. When the user chooses a folder, the folder's path is displayed in the text box called txtPath.

Private Sub cmdGetPath_Click()

  Dim oShell As New Shell
  Dim oFolder As Folder
  Dim oFolderItem As FolderItem

  Set oFolder = oShell.BrowseForFolder(Me.hWnd, "Select a Folder", _
    0, ssfDrives)

  Set oFolderItem = oFolderItems.Item

  txtPath.Text = oFolderItem.Path

End Sub

In VBScript, this function is slightly different because the ShellSpecialFolderConstants enumeration values are not available in script. The following example shows the VBScript equivalent of the previous example.

<SCRIPT LANGUAGE="VBScript">
<!--
  function fnGetMyPathVB()

    dim oShell
    dim oFolder
    dim oFolderItem

    set oShell = CreateObject("Shell.Application")
    set oFolder = oShell.BrowseForFolder(0, "Choose a Folder", 0)
    set oFolderItem = oFolder.Items.Item

    document.all.item("myPath").innerText = oFolderItem.Path

  end function
-->
</SCRIPT>

In the following JScript example, which is a direct translation of the preceding VBScript example, note how the empty parentheses '()' are used to invoke the Folder.Items and FolderItems.Item methods.

<SCRIPT LANGUAGE="JavaScript">
<!--
  function fnGetMyPathJ()
  {
    var oShell = new ActiveXObject("Shell.Application");

    var oFolder = new Object;
    oFolder = oShell.BrowseForFolder(0, "Choose a folder", 0);

    var oFolderItem = new Object;
    oFolderItem = oFolder.Items().Item();

    document.all.item("myPath").innerText = oFolderItem.Path;
  }
-->
</SCRIPT>


Shell Basics: Extending the Shell

By integrating your application with the Shell, you can extend the Shell's functionality and customize certain aspects of its behavior. In order of increasing complexity, you can extend the Shell by:

  • Putting information in the registry or in special files.
  • Implementing a Shell extension handler.
  • Implementing a namespace extension.

The first approach, which is used by many applications, is discussed in the following documentation.

  • Creating a File Association
  • Customizing Icons
  • Extending Shortcut Menus
  • Customizing Folders with Desktop.ini
  • Creating an AutoRun-enabled CD-ROM Application
  • Using AutoPlay

For a discussion of how to write extension handlers, see Creating Shell Extension Handlers. For a discussion of how to write namespace extensions, see Creating a Shell Namespace Extension.

Note To improve the readability of the sample code in the Shell Basics documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values are in a normal font.


Creating a File Association

Files that contain a particular type of data commonly have the same file name extension. It is appended to the file name and typically consists of a period followed by three alphanumeric characters. For example, ANSI text files commonly have a .txt file name extension.

Although it is customary, file name extensions are not restricted to three letters on systems that support long file names. On Microsoft® Windows® 95 and later systems, you can use any number of characters you like as long as the file name doesn't exceed 255 characters.

Note You can use multiple periods in a file name, but only those characters following the final period will be recognized as a file name extension. Any other periods will be treated as part of the file name. Although file names can contain spaces, do not use spaces in file name extensions.

Any time you create or change a file association, it is important to notify the system that you have made a change with SHChangeNotify, specifying the SHCNE_ASSOCCHANGED event. If you do not call SHChangeNotify, the change might not be recognized until the system is rebooted.

  • Defining a File Class
  • Defining Attributes for a File Class
  • Registering an Application to Handle Arbitrary File Classes
  • Excluding an Application from the Open With Dialog Box

Defining a File Class

Files with a common file name extension can be defined as members of a file class. Defining a file class allows you to extend the Shell by customizing the behavior of all files in the class. The Shell Basics: Extending the Shell section discusses those behaviors that can be customized by adding registry entries or special files, including:

  • Specifying the application used to open the file when it is double-clicked.
  • Adding commands to the shortcut menu.
  • Specifying a custom icon.

For a greater degree of control over the behavior of a file class, you can write one or more Shell extension handlers. For more information, see Creating Shell Extension Handlers.

To define a file class, first create a registry key for the extension, including the period, under HKEY_CLASSES_ROOT. Set the key's value to the ProgID for the associated application. Next, create a second key under HKEY_CLASSES_ROOT for the application's ProgID. Set it to a REG_SZ value that describes the application. For example, to create a file class with an .myp extension and an associated application, MyProgram.exe with a ProgID of MyProgram.1, the registry entries would be:

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    MyProgram.1=MyProgram Application

A user can act on a member of the file class in a variety of ways, such as double-clicking or right-clicking the file in Microsoft® Windows® Explorer. Once these two keys are in place, you can add subkeys to them to customize the behavior of the file class and its associated application. When a user acts on a member of the class, the Shell's response will include the information contained in these keys.

Defining Attributes for a File Class

Assigning attributes to a file class allows you to control some aspects of its behavior. It also allows you to limit the extent to which the user can modify various aspects of the class, such as its icon or verbs, with the Folder Options property sheet. The attributes are defined as binary flags. To assign attributes to a file class, combine the selected attributes with a logical OR to form a single attribute value. Add an EditFlags REG_BINARY value to the class's ProgID key and set it to the attribute value. The following table lists the file class attributes and their numerical values.

Flag | Value | Description
FTA_Exclude | 0x00000001 | Exclude the file class.
FTA_Show | 0x00000002 | Show file classes, such as folders, that aren't associated with a file name extension.
FTA_HasExtension | 0x00000004 | The file class has a file name extension.
FTA_NoEdit | 0x00000008 | The registry entries associated with this file class cannot be edited. New entries cannot be added and existing entries cannot be modified or deleted.
FTA_NoRemove | 0x00000010 | The registry entries associated with this file class cannot be deleted.
FTA_NoNewVerb | 0x00000020 | No new verbs can be added to the file class.
FTA_NoEditVerb | 0x00000040 | Canonical verbs such as open and print cannot be modified or deleted.
FTA_NoRemoveVerb | 0x00000080 | Canonical verbs such as open and print cannot be deleted.
FTA_NoEditDesc | 0x00000100 | The description of the file class cannot be modified or deleted.
FTA_NoEditIcon | 0x00000200 | The icon assigned to the file class cannot be modified or deleted.
FTA_NoEditDflt | 0x00000400 | The default verb cannot be modified.
FTA_NoEditVerbCmd | 0x00000800 | The commands associated with verbs cannot be modified.
FTA_NoEditVerbExe | 0x00001000 | Verbs cannot be modified or deleted.
FTA_NoDDE | 0x00002000 | The DDE-related entries cannot be modified or deleted.
FTA_NoEditMIME | 0x00008000 | The content-type and default-extension entries cannot be modified or deleted.
FTA_OpenIsSafe | 0x00010000 | The file class's open verb can be safely invoked for downloaded files.
FTA_AlwaysUnsafe | 0x00020000 | Do not allow the "Never ask me" check box to be enabled. The user can override this attribute through the File Type dialog box.
FTA_AlwaysShowExt | 0x00040000 | Always show the file class's file name extension, even if the user has selected the "Hide Extensions" option.
FTA_NoRecentDocs | 0x00100000 | Don't add members of this file class to the Recent Documents folder.

The following example assigns the FTA_NoRemove (0x00000010) and FTA_NoNewVerb (0x00000020) attributes to the .myp file class.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    MyProgram.1=MyProgram Application
        EditFlags=00 00 00 30

Registering an Application to Handle Arbitrary File Classes

The most common use of file classes is to associate a file name extension with the application that should be used to open members of the class. The user can then open a file by double-clicking the file icon or by selecting a command such as Open or Edit from the file's shortcut menu. Some applications can be associated with a single file class; other applications can be associated with many file classes. For a detailed discussion of how to implement this behavior, see Extending Shortcut Menus.

In some cases, however, the user might attempt to open a member of a file class with an application that is not associated with the class. For example, if the user double-clicks a file that is not associated with an application, an Open With dialog box appears that allows him or her to specify which application should open the file. The user can also use this dialog box to specify which application is associated with a particular file name extension. The following illustration shows a typical Open With dialog box.

Open With dialog box

In most cases, the application will be asked to open a file that it is capable of handling. For example, many applications can handle .txt files. In other cases, the file might be completely incomprehensible. The ways that applications open arbitrary files can be divided into three general classes:

  • Class 1. Open only those file classes that have a registered association with the application. If the user attempts to have the application open any other file class, return an error. Applications of this type are typically designed to work only with certain proprietary file formats.
  • Class 2. Use the same procedure to open any file. Examine the contents of the file and display the file, if possible. Only return errors for those files that the application cannot handle. Applications of this sort are typically designed to work with a common file format, such as ANSI text, that can be the underlying format of many file classes.
  • Class 3. Have one set of procedures for opening files that have a registered association with the application. Provide a default procedure to open all other files. Applications of this sort are usually a hybrid of the first two classes. They have one or more proprietary formats that need special handling, but they are also capable of handling some standard formats.

Assume, for instance, that the MyProgram application discussed in the preceding sections of this document can also handle .txt files. If a user attempts to use the Open With dialog box to open a .txt file with MyProgram, or associate .txt files with MyProgram, the Shell will attempt to open the file as if it were an .myp file. What happens next depends on how the application opens files. If MyProgram falls into either of the first two classes, there is no need for special handling by the Shell. For class 1, MyProgram would simply examine the file name, see that it lacked an .myp extension, and return an error. For class 2, MyProgram would use its standard procedure for opening all files. However, with Microsoft® Windows® 2000, the Shell can be extended to make class 3 applications easier to implement as well as provide two important new features for users.

What makes the third class of applications more difficult is that, if MyProgram is expecting a proprietary .myp file, it might have problems handling a .txt file. On the other hand, writing a general-purpose routine to open all files the same way can be inefficient. Instead, the Shell allows you to register normal file associations for your proprietary formats, plus a default procedure to be used for arbitrary file types. When a user attempts to open one of your proprietary files, the file will be opened as specified by the file association. If a user attempts to open an arbitrary file type, the file will be opened as specified by the default procedure. The ability to define a default file opening procedure also supports two new features that will be helpful to users:

  • If the user uses the Open With dialog box to associate a file name extension with an application, that choice will always be respected. Applications that are subsequently installed will not be permitted to take over the file association.
  • File associations can roam with the user. For example, assume that the user has associated MyProgram with .htm files on his or her primary computer. When that user attempts to open an .htm file on a different computer, MyProgram will be used, if available.

The procedure for registering an application to accept arbitrary file classes is similar to that used to define shortcut menus for a file class. For a detailed discussion, see Extending Shortcut Menus.

Excluding an Application from the Open With Dialog Box

The applications that are listed in the Open With dialog box are registered as subkeys of HKEY_CLASSES_ROOT\Applications. However, many applications should not be used to open files that are not members of their associated file class. To exclude an application from the Open With dialog box, add a NoOpenWith REG_SZ value name to the application's subkey. For example, the following sample registry entry excludes MyProgram.exe from the Open With dialog box.

HKEY_CLASSES_ROOT
    ...
    Applications
        ...
        MyProgram.exe
            NoOpenWith

It is also possible to exclude an application from the Open With dialog box by appending the application's file name to the Windows Explorer kill list. This option is not recommended and is discussed here only for completeness. The kill list is a REG_SZ value of the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\FileAssociation key named KillList. The kill list is a string consisting of the file names of the applications, separated by semicolons (;).


Customizing Icons

Microsoft® Windows® supplies default icons for every item displayed on the desktop and in Windows Explorer. Mass storage devices, such as disk drives, are also assigned default icons. However, these icons often provide little insight to the user as to the contents of the file or what program is associated with it. You can assign a custom icon to a file system folder by creating a Desktop.ini file. This document discusses how to use the registry to associate custom icons with file classes and drive letters.

  • Assigning a Custom Icon to a File Class
  • Assigning a Custom Icon to a Drive Letter

Assigning a Custom Icon to a File Class

By default, all files are displayed on the desktop and in Windows Explorer with default icons. For example, the following illustration shows this icon used with MyDocs4.xyz.

All the files displayed in this screen shot contain ANSI text. The reason that the files with the .txt extension do not display the default icon is that .txt has been registered as a file class and assigned a custom icon.

Assigning a custom icon to a file class is a simple matter. Create a subkey, under the key for the application's ProgID, and name it DefaultIcon. Assign it a REG_SZ value containing the fully qualified path for the file with the icon. Any file containing an icon is acceptable, including .ico, .exe, and .dll files. If there is more than one icon in the file, the path should be followed by a comma, and then the index of the icon.

The following illustration shows a custom icon that has been assigned to the .myp file class, which was also used in the example in Creating a File Class. The My Documents directory now looks like this:

Custom icon for .myp files

In this example, the icon is in the c:\MyDir\MyProgram.exe file, with an index of two. The registry entry that assigns the custom icon to all .myp files is:

HKEY_CLASSES_ROOT
    .myp=MyProgram.1

    ...
    MyProgram.1=MyProgram Application
        DefaultIcon=C:\MyDir\MyProgram.exe,2

Finally, call SHChangeNotify to notify the Shell to update its cache.

Assigning a Custom Icon and Label to a Drive Letter

For Shell versions 4.71 and later, you can use the registry to replace the standard drive icon with a custom icon. With versions 5.0 and later, you can also add a custom label. Custom drive icons and labels are normally used for removable mass storage devices, such as tape drives, to allow users to easily distinguish them from their system's hard and floppy drives.

To replace the standard drive icon with a custom icon in Windows 2000, add a subkey named for the drive letter to HKEY_CURRENT_USER\Applications\Explorer.exe\Drives\DriveIcons\.

To replace the standard drive icon with a custom icon in all versions of Windows other than Windows 2000, add a subkey named for the drive letter to HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\DriveIcons\.

The drive letter should not be followed by a colon (:). Add a DefaultIcon subkey to the drive letter subkey and set its default value to a string containing the location of the icon. The first part of the string contains the fully-qualified path of the icon's file. If there is more than one icon in the file, the path is followed by a comma, and then by the zero-based index of the icon. To add a custom label, add a DefaultLabel subkey to the drive letter subkey, and set its default value to a string containing the label.

The following example specifies a custom icon and label for the E: drive. The icon is in the C:\MyDir\MyDrive.exe file with a zero-based index of three.

Windows 2000

HKEY_CURRENT_USER
  Applications
    Explorer.exe
      Drives
         DriveIcons
            E
              DefaultIcon=C:\MyDir\MyDrive.exe,3
              DefaultLabel="MyDrive"

All Other Versions of Windows

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            DriveIcons
              E
                DefaultIcon=C:\MyDir\MyDrive.exe,3
                DefaultLabel="MyDrive"

In all versions of Windows, if you change a file class or drive icon you must also call SHUpdateImage to notify the Shell to update any icons currently displayed.


Extending Shortcut Menus

Right-clicking an object with Microsoft® Windows® 95 and later systems usually pops up a shortcut menu. This menu contains a list of commands that the user can select to perform various actions on the object. This section is an introduction to shortcut menus for file system objects.

  • Shortcut Menus for File System Objects
  • Shortcut Menu Verbs
  • Extending the Shortcut Menu for a File Class
  • Extending the Shortcut Menu for Predefined Shell Objects
  • Registering an Application to Handle Arbitrary File Classes
  • Extending the New Submenu

Shortcut Menus for File System Objects

When a user right-clicks an object, such as a file, that is displayed in Microsoft® Windows® Explorer or on the desktop, a shortcut menu appears with a list of commands. The user can then perform an action on the file, such as opening or deleting it, by selecting the appropriate command.

Because shortcut menus are often used for file management, the Shell provides a set of default commands, such as Cut and Copy, that appear on the shortcut menu for any file. Note that although Open With is a default command, it is not displayed for some standard file classes, such as .wav. The following illustration of the sample My Documents directory, which was also used as an example in Customizing Icons, shows a default shortcut menu that was displayed by right-clicking MyDocs4.xyz.

Default shortcut menu for file system objects

The reason that MyDocs4.xyz shows a default shortcut menu is that it is not a member of a registered file class. On the other hand, .txt is a registered file class. If you right-click one of the .txt files, you will instead see a shortcut menu with two additional commands in its upper section: Open and Print.

Customized shortcut menu for file system objects

Once a file class is registered, you can extend its context with additional commands. They are displayed above the default commands when any member of the class is right-clicked. Although most of the commands added in this way are common ones, such as Print or Open, you are free to add any command that a user might find helpful.

All that is required to extend the shortcut menu for a file class is to create a registry entry for each command. A more sophisticated approach is to implement a shortcut menu handler, which allows you to extend the shortcut menu for a file class on a file-by-file basis. For more information, see Creating Shortcut Menu Handlers.

Shortcut Menu Verbs

Each command on the shortcut menu is identified in the registry by its verb. These verbs are the same as those used by ShellExecuteEx when launching applications programmatically. For further information about the use of ShellExecuteEx, see the discussion in Launching Applications.

A verb is a simple text string that is used by the Shell to identify the associated command. Each verb corresponds to the command string used to launch the command in a console window or batch (.bat) file. For example, the open verb normally launches a program to open a file. Its command string typically looks something like this:

"My Program.exe" "%1"

Note If any element of the command string contains or might contain spaces, it must be enclosed in quotation marks. Otherwise, if the element contains a space, it will not parse correctly. For instance, "My Program.exe" will launch the application properly. If you use My Program.exe, the system will attempt to launch "My" with "Program.exe" as its first command line argument. You should always use quotation marks with arguments such as "%1" that are expanded to strings by the Shell, because you cannot be certain that the string will not contain a space.

Verbs can also have a display string associated with them, which is displayed on the shortcut menu instead of the verb string itself. For example, the display string for openas is Open With. Like normal menu strings, including an ampersand (&) in the display string allows keyboard selection of the command.

Canonical Verbs

In general, applications are responsible for providing localized display strings for the verbs they define. However, to provide a degree of language independence, the system defines a standard set of commonly used verbs called canonical verbs. A canonical verb can be used with any language, and the system automatically generates a properly localized display string. For instance, the open verb's display string will be set to Open on an English system, and to Öffnen on a German system.

The canonical verbs include:

  • open
  • print
  • explore
  • find
  • openas
  • properties

The printto verb is also canonical but is never displayed. It allows the user to print a file by dragging it to a printer object.

Extended Verbs

When the user right-clicks an object, the shortcut menu contains all the normal verbs. However, there could be commands that you want to support but not have displayed on every shortcut menu. For example, you could have commands that are not commonly used or that are intended for experienced users. For this reason, you can also define one or more extended verbs. These verbs are also character strings and are similar to normal verbs. They are distinguished from normal verbs by the way they are registered. To have access to the commands associated with extended verbs, the user must right-click an object while pressing the SHIFT key. The extended verbs will then be displayed along with the normal verbs.

Extending the Shortcut Menu for a File Class

The simplest way to extend the shortcut menu for a file class is with the registry. To do this, add a Shell subkey below the key for the ProgID of the application associated with the file class. Optionally, you can define a default verb for the file class by making it the default value of the Shell subkey.

The default verb is displayed first on the shortcut menu. Its purpose is to provide the Shell with a verb it can use when ShellExecuteEx is called but no verb is specified. The Shell does not necessarily select the default verb when ShellExecuteEx is used in this fashion. For Shell versions 5.0 and later, found on Microsoft® Windows® 2000 and later systems, the Shell uses the first available verb from the following list. If none are available, the operation fails.

  • The open verb
  • The default verb
  • The first verb in the registry
  • The openwith verb

For Shell versions prior to version 5.0, omit the third item.

Below the Shell subkey, create one subkey for each verb you want to add. Each of these subkeys will have a REG_SZ value set to the verb's display string. You can omit the display string for canonical verbs because the system will automatically display a properly localized string. If you omit the display string for noncanonical verbs, the verb string will be displayed. For each verb subkey, create a command subkey with the default value set to the command string.

The following illustration shows a shortcut menu for the .myp file class used in Creating a File Association and Customizing Icons. It now has open, doit, print, and printto verbs on its shortcut menu, with doit as the default verb. The shortcut menu looks like this.

Customized shortcut menu

The registry entries used to extend the shortcut menu shown in the preceding illustration are:

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    MyProgram.1=MyProgram Application
        Shell=doit
            open
                commandC:\MyDir\MyProgram.exe "%1"
            doit="&Do It"
                command=C:\MyDir\MyProgram.exe /d "%1"
            print
                command=C:\MyDir\MyProgram.exe /p "%1"
            printto
                command=C:\MyDir\MyProgram.exe /p "%1" "%2" %3 %4

Although the Open With command is above the first separator, it is automatically created by the system and doesn't require a registry entry. The system automatically creates display names for the canonical verbs open and print. Because doit is not a canonical verb, it is assigned a display name, "&Do It", which can be selected by pressing the D key. The printto verb does not appear on the shortcut menu, but including it allows the user to print files by dropping them on a printer icon. In this example, %1 represents the file name and %2 the printer name. You can ignore %3 and %4 for Windows 95 and later systems. For Windows 3.1 systems, %3 represents the driver name and %4 the port name. Unlike most similar arguments, the %3 and %4 arguments of printto should not be enclosed in quotation marks.

Verbs can be suppressed through policy settings by adding a SuppressionPolicy value to the verb's key. Set the value of SuppressionPolicy to the policy ID. If the policy is turned on, the verb and its associated shortcut menu entry are suppressed.

Defining Extended Verbs

You can also use the registry to define one or more extended verbs. The associated commands will be displayed only when the user right-clicks an object while also pressing the SHIFT key. To define a verb as extended, simply add an "extended" REG_SZ value to the verb's subkey. The value should not have any data associated with it. The following sample registry entry shows the example from the previous section, with doit defined as an extended verb.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    MyProgram.1=MyProgram Application
        Shell=doit
            open
                command=C:\MyDir\MyProgram.exe "%1"
            doit="&Do It"
                 extended
                command=C:\MyDir\MyProgram.exe /d "%1"
            print
                command=C:\MyDir\MyProgram.exe /p "%1"
            printto
                command=C:\MyDir\MyProgram.exe /p "%1" "%2" %3 %4

Associating Verbs with DDE Commands

Invoking a verb normally launches the application specified by the verb's command subkey. However, if your application supports DDE, you can instead have the Shell initiate a DDE conversation.

To specify that invoking a verb should initiate a DDE conversation, add a ddeexec subkey to the verb's key. Set the default value of ddeexec to the DDE command string. The ddeexec key has three optional subkeys that provide some control over the DDE process:

  • application. Set the default value of this subkey to the application name to be used to establish the DDE conversation. If there is no application subkey, the default value of the verb's command subkey is used as the application name.
  • topic. Set the default value of this subkey to the topic name of the DDE conversation. If there is no topic subkey, System is used as the topic name.
  • ifexec. Set the default value of this subkey to the DDE command to be used if DDE conversation cannot be initiated. When initiation fails, the application specified by the default value of the verb's command subkey is launched. If an ifexec key exists, its default value will then be used as the DDE command. If there is no ifexec subkey, the default value of the ddeexec key will be used again as the DDE command.

The following example specifies that invoking the open verb for MyProgram.1 initiates a DDE conversation with a DDE command of Open("%1") and an application name of MyProgram.

HKEY_CLASSES_ROOT
    ...
    MyProgram.1=MyProgram Application
        Shell=doit
            open
                command=C:\MyDir\MyProgram.exe "%1"
                ddeexec=Open("%1")
                    application=MyProgram

Extending the Shortcut Menu for Predefined Shell Objects

Many predefined Shell objects have shortcut menus that can be extended. Register the command in much the same way that you register typical file classes, but use the name of the predefined object as the file class name.

A list of predefined objects can be found at: Predefined Shell Objects. Those predefined Shell objects whose shortcut menus can be extended by adding verbs in the registry are marked in the table with the word "Verb."

Registering an Application to Handle Arbitrary File Classes

The preceding sections of this document have discussed how to define shortcut menu items for a particular file class. Among other things, defining the shortcut menu allows you to specify how the associated application opens a member of the file class. However, as discussed in Creating a File Association, applications can also register a separate default procedure to be used when a user attempts to use your application to open a file class that you have not associated with the application. This topic is discussed here because you register the default procedure in much the same way you register shortcut menu items.

The default procedure serves two basic purposes. One is to specify how your application should be invoked to open an arbitrary file class. You could, for instance, use a command-line flag to indicate that an unknown file class is being opened. The other purpose is to define the various characteristics of a file class, such as the shortcut menu items and the icon. If a user associates your application with an additional file class, that class will have these characteristics. If the additional file class was previously associated with another application, these characteristics will replace the originals.

To register the default procedure, place the same registry keys you created for your application's ProgID under the application's subkey of HKEY_CLASSES_ROOT\Applications. You can also include a FriendlyAppName subkey to provide the system with a friendly name for your application. The following registry fragment shows a sample default procedure for MyProgram.exe that defines a friendly name and several shortcut menu items. The command strings include a /a flag to notify the application that it is opening an arbitrary file class. If you include a DefaultIcon subkey, you should use a generic icon.

HKEY_CLASSES_ROOT
    ...
    Applications
        ...
        MyProgram.exe
            FriendlyAppName=MyProgram Application
            Shell
                open
                    commandC:\MyDir\MyProgram.exe /a "%1"
                print
                    command=C:\MyDir\MyProgram.exe /a /p "%1"
                printto
                    command=C:\MyDir\MyProgram.exe /a /p "%1" "%2" %3 %4

Extending the New Submenu

When a user opens the File menu in Windows Explorer, the first command is New. Selecting this command displays a submenu. By default, it contains two commands, Folder and Shortcut, that allow users to create subfolders and shortcuts. This submenu can be extended to include file creation commands for any file class.

To add a file-creation command to the New submenu, your application's files must have a file class associated with them. Include a ShellNew subkey under the file extension key. When the File menu's New command is selected, the Shell will add it to the New submenu. The command's display string will be the descriptive string that is assigned to the program's ProgID.

Assign one or more data values to the ShellNew subkey to specify the file creation method. The available values follow.

Value | Description
Command | Executes an application. This is a REG_SZ value specifying the path of the application to be executed. For example, you could set it to launch a wizard.
Data | Creates a file containing specified data. Data is a REG_BINARY value with the file's data. Data is ignored if either NullFile or FileName is specified.
FileName | Creates a file that is a copy of a specified file. FileName is a REG_SZ value, set to the fully qualified path of the file to be copied.
NullFile | Creates an empty file. NullFile is not assigned a value. If NullFile is specified, Data and FileName are ignored.

The following illustration shows the New submenu for the .myp file class used as an example in Creating a File Association and Customizing Icons. It now has a command, MyProgram Application. When a user selects MyProgram Application from the New submenu, the Shell creates a file named "New MyProgram Application.myp" and passes it to MyProgram.exe.

Custom New menu

The registry entry is now as follows:

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
        ShellNew=NULLFILE
    ...
    MyProgram.1=MyProgram Application
        DefaultIcon=C:\MyDir\MyProgram.exe,2
        Shell=doit
            open
                command=C:\MyDir\MyProgram.exe "%1"
            doit="&Do It"
                command=C:\MyDir\MyProgram.exe /d "%1"
            print
                command=C:\MyDir\MyProgram.exe /p "%1"
            printto
                command=C:\MyDir\MyProgram.exe /p "%1" "%2" %3 %4


Customizing Folders with Desktop.ini

File system folders are commonly displayed with a standard icon and set of properties, which specify, for instance, whether or not the folder is shared. You can customize the appearance and behavior of an individual folder in two ways:

  • Create a Desktop.ini file for the folder
  • Create a Folder.htt template for the folder

Folders can be displayed in either Classic or Web style. For a detailed discussion of these styles, see Web View. The Desktop.ini file, discussed here, applies to both styles. It allows you to assign a custom icon to a folder and control its behavior in a limited way.

To customize the folder's style beyond what is possible with the Desktop.ini file, you must create a custom Folder.htt template for the folder. This file will only affect the appearance of the folder when the Web style is selected. If this template is not present in the folder, the Shell uses a default template. For further discussion of .htt templates, see The Web View Template.

  • Using Desktop.ini Files
  • Creating a Desktop.ini File

Using Desktop.ini Files

Folders are normally displayed with the standard folder icon. The most common use of the Desktop.ini file is to assign a custom icon to a folder. This icon will be displayed in Classic style as well as Web style, and it will appear next to the folder's name anywhere the name appears. You can also use Desktop.ini to create an infotip that displays information about the folder and controls some aspects of the folder's behavior, such as whether it can be shared.

Use the following procedure to customize a folder's style with Desktop.ini:

  • Use PathMakeSystemFolder to make the folder a system folder. You can also make a folder a system folder from the command line by using attrib +s FolderName.
  • Create a Desktop.ini file for the folder. You should mark it as hidden and read-only to protect it from being modified.

Creating a Desktop.ini File

The Desktop.ini file is a text file that allows you to specify how a file system folder will be viewed. There are three sections in the file. The first two, [ExtShellFolderViews] and [{5984FFE0-28D4-11CF-AE66-08002B2E1262}] are necessary only if you want to use a custom Folder.htt template. If you omit them, the system will use the default template. To use a custom Folder.htt template, you must include these two sections into the Desktop.ini file exactly as they are shown:

[ExtShellFolderViews]
Default={5984FFE0-28D4-11CF-AE66-08002B2E1262}
{5984FFE0-28D4-11CF-AE66-08002B2E1262}={5984FFE0-28D4-11CF-AE66-08002B2E1262}

[{5984FFE0-28D4-11CF-AE66-08002B2E1262}]
PersistMoniker=file://Folder.htt

The third section, [.ShellClassInfo], allows you to customize the folder's view by assigning values to several entries:

Entry | Value
ConfirmFileOp | Set this entry to 0 to avoid a "You Are Deleting a System Folder" warning when deleting or moving the folder.
NoSharing | Set this entry to 1 to prevent the folder from being shared.
IconFile | If you want to specify a custom icon for the folder, set this entry to the icon's file name. The .ico file extension is preferred, but it is also possible to specify .bmp files, or .exe and .dll files that contain icons. If you use a relative path, the icon will be available to people who view the folder over the network. You must also set the IconIndex entry.
IconIndex | Set this entry to specify the index for a custom icon. If the file assigned to IconFile only contains a single icon, set IconIndex to 0.
InfoTip | Set this entry to an informational text string. It will be displayed as an infotip when the cursor hovers over the folder. If the user clicks the folder in a Web view, the information text will be displayed in the folder's information block, below the standard information.

The following illustrations are of the Music folder with a custom Desktop.ini file. The folder now:

  • Has a custom icon.
  • Does not display a "You Are Deleting a System Folder" warning if the folder is moved or deleted.
  • Cannot be shared.
  • Displays informational text when the cursor hovers over the folder.

The folder options in the following illustrations have been set to show hidden files, so that Desktop.ini is visible. A folder only needs its own Folder.htt template if it does not use the default template. The Web style view of the folder looks like this:

A view of a folder with a custom icon.

When the cursor hovers over the folder, the infotip is displayed.

Web view of a folder with an infotip.

The Classic style of this folder is similar, with the custom icon replacing the folder icon everywhere the folder name appears.

The following desktop.ini file was used to customize the Music folder, as seen in the preceding illustrations. For instructional purposes, it includes the optional sections that are needed if you want to use a custom Folder.htt template.

[ExtShellFolderViews]
Default={5984FFE0-28D4-11CF-AE66-08002B2E1262}
{5984FFE0-28D4-11CF-AE66-08002B2E1262}={5984FFE0-28D4-11CF-AE66-08002B2E1262}

[{5984FFE0-28D4-11CF-AE66-08002B2E1262}]
PersistMoniker=file://Folder.htt

[.ShellClassInfo]
ConfirmFileOp=0
NoSharing=1
IconFile=Folder.ico
IconIndex=0
InfoTip=Some sensible information.


Creating an AutoRun-enabled CD-ROM Application

Microsoft® AutoRun is a feature of the Microsoft® Windows® operating system. It automates the procedures for installing and configuring products designed for Windows-based platforms that are distributed on CD-ROMs. When users insert an AutoRun-enabled compact disc into their CD-ROM drive, AutoRun automatically runs an application on the CD-ROM that installs, configures, or runs the selected product. If you want your CD-ROM product to display the Microsoft Windows 95 logo, it must be enabled for AutoRun.

AutoRun can be used to install and run CD-ROM applications written for MS-DOS, Windows 3.0 and Windows 3.1, and all 32-bit versions of Windows. Although AutoRun is most commonly used for Windows applications, it can also be used to install, configure, or run MS-DOS-based applications in a Windows MS-DOS session. You can configure each MS-DOS-based application with its own unique icon, Config.sys file, and Autoexec.bat file. Windows creates the correct configuration files for the MS-DOS-based application. The startup application then starts the MS-DOS-based application in a window.

There are two essential requirements that a system must meet in order for AutoRun to work.

  • The system must be running Windows 95, Windows NT 4.0, or later versions. MS-DOS, Windows versions 3.1 and earlier, and Windows NT versions 3.51 and earlier do not support AutoRun. You can use AutoRun-enabled CD-ROMs in such systems. However, the AutoRun features will be ignored, and the CD-ROMs will behave as ordinary CD-ROMs.

  • The CD-ROM drive must have 32-bit device drivers that detect when a user inserts a compact disc and notify the system. Device drivers for MS-DOS or 16-bit versions of Windows do not have this feature.

The following sections discuss how to implement an AutoRun-enabled CD-ROM application.

  • Creating an AutoRun-Enabled Application
  • Autorun.inf Commands
  • Enabling and Disabling AutoRun


Creating an AutoRun-Enabled Application

Creating an AutoRun-enabled CD-ROM application is a straightforward procedure. You simply include two essential files:

  • An Autorun.inf file
  • A startup application

When a user inserts a disc into a CD-ROM drive on a AutoRun-compatible computer, the system immediately checks to see if the disc has a personal computer file system. If it does, the system searches for a file named Autorun.inf. This file specifies setup application that will be run, along with a variety of optional settings. The startup application typically installs, uninstalls, configures, and perhaps runs the application.

  • Creating an Autorun.inf File
  • Tips for Writing AutoRun Startup Applications

Creating an Autorun.inf File

Autorun.inf is a text file located in the root directory of the CD-ROM that contains your application. Its primary function is to provide the system with the name and location of the application's startup program that will be run when the disc is inserted. The Autorun.inf file can also contain optional information including:

  • The name of a file that contains an icon that will represent your application's CD-ROM drive. This icon will be displayed by Microsoft® Windows® Explorer in place of the standard drive icon.
  • Additional commands for the shortcut menu that is displayed when the user right-clicks the CD-ROM icon. You can also specify the default command that is run when the user double-clicks the icon.

Autorun.inf files are similar to .ini files. They consist of one or more sections, each headed by a name enclosed in square brackets. Each section contains a series of commands that will be run by the Shell when the disc is inserted. There are two sections that are currently defined for Autorun.inf files:

  • The [autorun] section contains the default AutoRun commands. All Autorun.inf files must have an [autorun] section.
  • An optional [autorun.alpha] section can be included for Microsoft® Windows NT 4.0 systems running on RISC-based computers. When a disc is inserted in a CD-ROM drive on a RISC-based system, the Shell will run the commands in this section instead of those in the [autorun] section.

Note The Shell checks for an architecture-specific section first. If it does not find one, it uses the information in the [autorun] section. After the Shell finds a section, it ignores all others, so each section must be self-contained.

Each section contains a series of commands that determine how the Autorun operation takes place. There are five commands available:

Command | Description
defaulticon | Specifies the default icon for the application.
icon | Specifies the path and file name of an application-specific icon for the CD-ROM drive.
open | Specifies the path and file name of the startup application.
shell | Defines the default command in the CD-ROM's shortcut menu.
shell\verb | Adds commands to the CD-ROM's shortcut menu.

The following is an example of a simple Autorun.inf file. It specifies Filename.exe as the startup application. The second icon in Filename.exe will represent the CD-ROM drive instead of the standard drive icon.

[autorun]
open=Filename.exe
icon=Filename.exe,1

This Autorun.inf sample runs different startup applications depending on the type of computer:

[autorun]
open=Filename_x86.exe
icon=IconFile.ico

[autorun.alpha]
open=Filename_RISC.exe
icon=IconFile.ico

Tips for Writing AutoRun Startup Applications

There are essentially no constraints on how to write an AutoRun startup application. You can implement it to do whatever you find necessary to install, uninstall, configure, or run your application. However, the following tips provide some guidelines to implementing an effective AutoRun startup application.

  • Users should receive feedback as soon as possible after they insert an AutoRun compact disc into the CD-ROM drive. Startup applications should thus be small programs that load quickly. They should clearly identify the application and provide an easy way to cancel the operation.
  • Typically, the initial part of the startup application presents users with a user interface, such as a dialog box, asking them how they would like to proceed. Check to see if the program is already installed. If not, the next step will probably be the setup procedure. The startup application can take advantage of the time the user spends reading the dialog box by starting another thread to begin loading the setup code. By the time the user clicks OK, your setup program will already be partly if not fully loaded. This approach significantly reduces the user's perception of the amount of time it takes to load your application.
  • If the application has already been installed, the user probably inserted the disk to run the application. As with the setup case, you can start another thread to begin loading application code to shorten the waiting time for the user.
  • Hard disk space may be a limited resource on many systems. Here are a few hints for minimizing hard disk usage:
    • Keep the number of files that must be on the hard disk to a minimum. They should be restricted to files that are essential to running the program or that would take an unacceptably large amount of time to read from the CD-ROM.
    • In many cases, installing nonessential files on the hard disk is not necessary, but may provide benefits such as increased performance. Give the user the option of deciding how to make the tradeoff between the costs and benefits of hard disk storage.
    • Provide a way to uninstall any components that were placed on the hard disk. For more information about uninstalling an application, see Installing Applications.
    • If your application caches data, give the user some control over it. Include options in the startup application such as setting a limit on the maximum amount of cached data that will be stored on the hard disk, or having the application discard any cached data when it terminates.
  • Even though a CD-ROM has an Autorun.inf file, AutoRun can be suppressed programmatically or disabled entirely with the registry. See Enabling and Disabling AutoRun for more information.


Autorun.inf Commands

This document is a reference for the commands that can be used in an Autorun.inf file.

  • icon
  • label
  • open
  • shellexecute
  • Shell
  • Shell\verb

icon

The icon command specifies an icon which represents the AutoRun-enabled drive in the Windows user interface.

icon=iconfilename[,index]

Parameters

iconfilename
Name of an .ico, .bmp, .exe, or .dll file containing the icon information. If a file contains more than one icon, you must also specify zero-based index of the icon.

Remarks

The icon represents the AutoRun-enabled drive in the Microsoft® Windows® user interface. For instance, in Windows Explorer, the drive will have this icon instead of the standard drive icon. The icon's file must be in the same directory as the file specified by the open command.

The following example specifies the second icon in the MyProg.exe file.

icon=MyProg.exe,1

label

The label command specifies a text label to represent the AutoRun-enabled drive in the Windows user interface.

label=LabelText

Parameters

LabelText
A text string containing the label. It may contain spaces.

Remarks

The label represents the AutoRun-enabled drive in the Microsoft® Windows® user interface. If an icon is also specified, the label will be displayed below it.

The following example specifies "My Drive Label" as the drive's label.

label=My Drive Label

open

The open command specifies the path and file name of the application that AutoRun launches when a user inserts a disc in the drive.

open=[exepath\]exefile [param1 [param2] ...]

Parameters

exefile
Fully qualified path of an executable file that will be run when the compact disc is inserted. If only a file name is specified, it must be in drive's root directory. To locate the file in a subdirectory, you must specify a path. You can also include one or more command-line parameters to be passed to the startup application.

Remarks

See Tips for Writing AutoRun Startup Applications for further discussion of startup applications.

shellexecute

Version 5.0. The shellexecute command specifies an application or data file that AutoRun will use to call ShellExecuteEx.

shellexecute=[filepath\]filename[param1, [param2]...]

Parameters

filepath
A string containing the fully-qualified path of the directory that contains the data or executable file. If no path is specified, the file must be in the drive's root directory.
filename
A string containing the file's name. If it is an executable file, it will be launched. If it is a data file, it must be a member of a file class. ShellExecuteEx will launch the default command associated with the file class.
paramx
Any additional parameters that should be passed to ShellExecuteEx.

Remarks

This command is similar to open, but it allows you to use file association information to run the application.

Shell

The Shell command specifies a default command for the drive's shortcut menu.

shell=verb

Parameters

verb
The verb that corresponds to the command. The verb and its associated command must be defined in the Autorun.inf file with a shell/verb command.

Remarks

When a user right-clicks the drive icon, a shortcut menu will appear. If an Autorun.inf file is present, the default shortcut menu command is taken from it. This command is also executed when the user double-clicks the drive's icon.

To specify the default shortcut menu command, first define its verb, command string, and menu text with shell/verb. Then use shell to make it the default shortcut menu command. Otherwise, the default menu item text will be "AutoPlay", which will launch the application specified by the open command.

shell\verb

The shell\verb command adds a custom command to the drive's shortcut menu.

shell\verb\command=Filename.exe
shell\verb=MenuText

Parameters

verb
The command's verb. The shell\verb\command command associates the verb with an executable file. Verbs must not contain embedded spaces. By default, verb is the text that is displayed in the shortcut menu.
Filename.exe
The path and file name of the application that performs the command.
MenuText
This parameter specifies the text that is displayed in the shortcut menu. If it is omitted, verb is displayed. MenuText can be mixed-case and may contain spaces. You can set a shortcut key for the menu item by putting an ampersand (&) in front of the letter.

Remarks

When a user right-clicks the drive icon, a shortcut menu will appear. Adding shell/verb commands to the drive's Autorun.inf file allows you to add commands to this shortcut menu.

There are two parts to this command, which must be on separate lines. The first part is shell/verb/command, and is required. It associates a string, called a verb, with the application to be launched when the command is run. The second part is the shell/verb command, and is optional. It can be included to specify the text that is displayed in the shortcut menu.

To specify a default shortcut menu command, define the verb with shell/verb, and make it the default command with shell.

The following sample Autorun.inf fragment associates the readit verb with the command string "Notepad abc\readme.txt". The menu text is "Read Me", and 'M' is defined as the item's shortcut key. When the user selects this command, the drive's abc\readme.txt file will be opened with Notepad.

shell\readit\command=notepad abc\readme.txt
shell\readit=Read &Me


Enabling and Disabling AutoRun

There are many situations where AutoRun may need to be temporarily or persistently disabled. For example, AutoRun might interfere with the operation of a running application and need to be disabled for the duration. The system provides several ways to disable AutoRun.

  • Suppressing AutoRun Programmatically.
  • Using the Registry to Disable AutoRun.
  • AutoRun for Other Types of Storage Media.

Suppressing AutoRun Programmatically

There are a variety of situations where AutoRun may need to be suppressed programmatically. Two examples are:

  • Your application has a setup program that requires the user to insert another disc that may contain an Autorun.inf file.
  • During the operation of your application, the user may need to insert another disc that may contain an Autorun.inf file.

In either case, you will normally not want to launch another application while the original is in progress.

Users can manually suppress AutoRun by holding down the SHIFT key when they insert the CD-ROM. However, it is usually preferable to handle this operation programmatically rather than depending on the user.

With systems that have Shell version 4.70 and later, Microsoft® Windows® sends a "QueryCancelAutoPlay" message to the foreground window. Your application can respond to this message to suppress AutoRun. This approach is used by system utilities such as the Open common dialog box to disable AutoRun. You will not get a "QueryCancelAutoPlay" message with versions of Windows 95 that do not have the Internet Explorer 4.0 integrated Shell installed.

The following code fragments illustrate how to set up and handle this message. Your application must be running in the foreground window. First, register "QueryCancelAutoPlay" as a Windows message:

uMessage = RegisterWindowMessage(TEXT("QueryCancelAutoPlay"));

Your application's window must be in the foreground to receive this message. The message handler should return TRUE to cancel AutoRun and FALSE to enable it. The following code fragment illustrates how to use this message to disable AutoRun.

UINT g_uQueryCancelAutoPlay = 0;

LRESULT WndProc(HWND hwnd, UINT uMsg,  WPARAM wParam, LPARAM lParam)
{
    switch (uMsg) {
    ...
    default:
        if (!g_uQueryCancelAutoPlay)
        {
            g_uQueryCancelAutoPlay = RegisterWindowMessage(TEXT("QueryCancelAutoPlay"));
        }
        if (uMsg && uMsg == g_uQueryCancelAutoPlay)
        {
            return TRUE;       // cancel auto-play
        }
    }
}

If your application is using a dialog box and needs to respond to a "QueryCancelAutoPlay" message, it cannot simply return TRUE or FALSE. Instead, call SetWindowLong with nIndex set to DWL_MSGRESULT. Set the dwNewLong parameter to TRUE to cancel AutoRun, and FALSE to enable it. For example, the following sample dialog box procedure cancels AutoRun when it receives a "QueryCancelAutoPlay" message.

UINT g_uQueryCancelAutoPlay = 0;

BOOL DialogProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{
    switch (uMsg) {
    ...
    default:
        if (!g_uQueryCancelAutoPlay)
        {
            g_uQueryCancelAutoPlay = RegisterWindowMessage(TEXT("QueryCancelAutoPlay"));
        }
        if (uMsg == g_uQueryCancelAutoPlay)
        {
            SetWindowLong(hDlg, DWL_MSGRESULT, TRUE);
            return 1;
        }
    }
}

Using the Registry to Disable AutoRun

There are two registry values that can be used to persistently disable AutoRun: NoDriveAutoRun and NoDriveTypeAutoRun. The first value disables AutoRun for specified drive letters and the second disables AutoRun for a class of drives. If either of these values is set to disable AutoRun for a particular device, it will be disabled.

Note: The NoDriveAutoRun and NoDriveTypeAutoRun values should only be modified by system administrators to change the value for the entire system for testing or administrative purposes. Applications should not modify these values, as there is no way to reliably restore them to their original values.

The NoDriveAutoRun value disables AutoRun for specified drive letters. It is a REG_DWORD data value, found under the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer key. The first bit of the value corresponds to A:, the second to B:, and so on. To disable AutoRun for one or more drive letters, set the corresponding bits. For example, to disable the A: and C: drives, set NoDriveAutoRun to 0x00000005.

The NoDriveTypeAutoRun value disables AutoRun for a class of drives. It is a REG_DWORD or 4-byte REG_BINARY data value, found under the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer key. By setting the bits of this value's first byte, different drives can be excluded from working with AutoRun.

The following table gives the bits and bitmask constants, that can be set in the first byte of NoDriveTypeAutoRun to disable AutoRun for a particular drive type. For Microsoft® Windows NT and Windows 2000, you must restart Windows Explorer before the changes take effect.

Bit Number | Bitmask Constant | Description
0x04 | DRIVE_REMOVEABLE | Disk can be removed from drive (such as a floppy disk).
0x08 | DRIVE_FIXED | Disk cannot be removed from drive (a hard disk).
0x10 | DRIVE_REMOTE | Network drive.
0x20 | DRIVE_CDROM | CD-ROM drive.
0x40 | DRIVE_RAMDISK | RAM disk.

AutoRun for Other Types of Storage Media

AutoRun is primarily intended for public distribution of applications on CD-ROM and DVD-ROM. However, it is often useful to enable AutoRun on other types of removable storage media. This feature is typically used simplify the debugging of AutoRun.inf files. AutoRun only works on removable storage devices when the following criteria are met:

  • The device must have AutoRun-compatible drivers. To be AutoRun-compatible, a driver must notify the system that a disk has been inserted by sending a WM_DEVICECHANGE message.
  • The root directory of the inserted media must contain an Autorun.inf file.
  • The device must not have AutoRun disabled through the registry.
  • The foreground application has not suppressed AutoRun.

Note: This feature should not be used to distribute applications on floppy disks. Because implementing AutoRun on a floppy disk provides an easy way to spread computer viruses, users should be suspicious of any publicly distributed floppy disk that contains an Autorun.inf file.

Normally, AutoRun starts automatically, but it can also be started manually. If the device meets the criteria listed above, the drive letter's shortcut menu will include an AutoPlay command. To run AutoRun manually, either right-click the drive icon and select AutoPlay from the shortcut menu or double-click the drive icon. If the drivers are not AutoRun-compatible, the shortcut menu will not have an AutoPlay item and AutoRun can not be started.

AutoRun-compatible drivers are provided with some floppy disk drives, as well as some other types of removable media such as Compact Flash cards. AutoRun also works with network drives that are mapped to a drive letter with Windows Explorer or mounted with the Microsoft Management Console (MMC). As with mounted hardware, a mounted network drive must have an Autorun.inf file in its root directory, and must not be disabled through the registry.


Using and Configuring AutoPlay

[This is preliminary documentation and subject to change.]

When the Shell detects the insertion of new media or the attachment of a hot-plug device, the contents of the device or media are determined. AutoPlay, depending on its current settings, does one of the following:

  • Plays the content automatically.
  • Displays a dialog box prompting the user to choose a default handler for a single content type.
  • Presents a list of available handler applications to launch for mixed content. The chosen handler then automatically plays its associated content type.
  • Displays a standard folder view of the files.

If the contents do not meet the criteria for AutoPlay, the event is then passed to Microsoft® Windows Image Acquisition (WIA).

The following topics discuss the setup and use of AutoPlay.

  • Supported Media, Content Types, and Content Locations
  • Defining Single vs. Mixed Content Types
  • Sample Scenarios
  • Assigning Default Handler Applications
  • Handling Media Containing Mixed Content Types
  • AutoPlay User Interfaces

Supported Media, Content Types, and Content Locations

AutoPlay functions by associating supported media or content types with registered handler applications. Microsoft® Windows® registers its own handler applications such as the Windows Media Player. Other applications can register themselves during their installation. For more information, see Assigning Default Handler Applications.

The supported media types are:

  • Removable storage media such as Zip and Jaz
  • Flash media such as CompactFlash™, SmartMedia™, and Memory Stick
  • External hot plug USB or 1394 fixed drives
  • PC cards

The supported content types are listed below. Because of the large size of some removable media, supported file types are looked for only in predetermined locations on media that use volume-type interface and directory structure. These predetermined locations and the file types looked for in each are also listed below.

Content Type | File Types | File Locations
Pictures | *.jpg *.bmp *.gif *.tif | Media root directory DCIM\*\*.jpg DCIM\*\*.bmp DCIM\*\*.gif DC*\*.jpg MSSONY\*\*.tif
Music | *.mp3 *.wma | Media root directory HIFI\*\*.mp3 HIFI\*\*.wma
Video | *.mpg *.asf | Media root directory VIDEO\*.mpg VIDEO\*.asf MSSONY\*\*.mpg

Devices and applications can add other file types and locations. For more information, see Preparing Hardware and Software for Use with AutoPlay.

Defining Single vs. Mixed Content Types

AutoPlay defines three main content categories.

  • Pictures
  • Music
  • Video

A medium is considered to contain a single content type if all of the files on the medium fall into only one of these three categories. Note that this does not mean that the files must be of the same file type; .jpg, .gif, and .bmp are different file types, but one content type (pictures).

If supported content types are present on the medium, but no single content type can account for 100 percent of the total, then the medium is considered to contain mixed content type and is handled accordingly. For more information, see Handling Media Containing Mixed Content Types.

Sample Scenarios

The following scenarios provide a basic understanding of what to expect from AutoPlay.

AutoPlay for Storage Devices with Picture Media

  1. The user attaches a USB SanDisk CompactFlash reader device that already has media containing 90 percent picture content type in the form of .jpg files inserted.
  2. Notification displays Found New Hardware - SanDisk ImageMate.
  3. AutoPlay launches the appropriate image slideshow application.

Similarly, when the user inserts that same CompactFlash media into the reader when the reader is already attached to the system, the media insert event also causes AutoPlay to launch the image slideshow application. The user has the option of going to the Properties page of the SanDisk media device to change the default to another registered AutoPlay application, such as the Scanner and Camera Wizard or Picture It!.

AutoPlay for Music File Playback Devices and Storage Devices Containing Music Media

  1. The user attaches a USB Diamond Rio MP3 Player.
  2. Notification displays Found New Hardware - Diamond Rio MP3 Player.
  3. AutoPlay plays the files using its registered default handler-for instance, Windows Media Player.

Similarly, if the user inserts any media containing .mp3 files (for example, CompactFlash, SmartMedia, Memory Stick, or CD-ROM) that account for 90 percent of the total supported content into a storage device, the media insert event would also cause AutoPlay to play the files using the Windows Media Player. The user can access the property sheet of the storage device and change the default action to another registered AutoPlay application, such as WinAmp or Real Player.

AutoPlay for Video Playback on First Presentation

  1. The user plugs in a 1394 digital video camera for the first time.
  2. The user is presented with a simple dialog box that asks what application to run. The choices are to run one of the registered AutoPlay applications or to open a folder to view files. The user may set the selected behavior to be saved as the default action for future digital video camera hot-plug events.

Assigning Default Handler Applications

A fresh installation of Microsoft® Windows® finds AutoPlay with a set of registered handler applications. Applications registered by default during a Windows installation are as follows:

Media Type | Applications
Pictures | Slide Show (default) Camera and Scanner Wizard
Music | Windows Media Player (default) CD Player
Video | Windows Media Player (default) Movie Maker Net Meeting DVD Player

In the case of non-supported types, users are asked to assign the default setting for the AutoPlay action associated with each storage device on its first introduction to the system. At that time, the user is prompted to choose an action from a provided list of registered applications or to display a folder view listing the media content. The user also has the option of choosing to be prompted each time the media type is detected rather than saving any particular application as a default.

Note Device manufacturers have the option of registering and assigning default applications to be used with their particular products. In these cases, the dialog box offering a choice to the user is not displayed.

To be offered as an option by AutoPlay, newly installed applications must add themselves to the registry. For details, see Preparing Hardware and Software for Use with AutoPlay.

Users can always change the default AutoPlay handler for any storage device or content type. The AutoPlay property page is accessible for change in the following locations.

  • The property sheet of the storage device in My Computer
  • The Device Manager within the System Control Panel
  • The application's user interface through a ShellExecute function that allows the application to call the property page

For examples of user prompts and property pages, see AutoPlay User Interfaces.

Handling Media Containing Mixed Content Types

When AutoPlay is presented with a mixed content medium, it requires user input before it can take action. In this case, the user is presented with a dialog box containing a filtered list of all appropriate registered applications available for the content types present on the media. The user can choose one of these applications to AutoPlay that particular content type, while the rest remain untouched. As the composition of mixed content media varies with each individual disc there is no option to save this choice as a default.

For examples of user prompts, see AutoPlay User Interfaces.

AutoPlay User Interfaces

There are three possible user interfaces.

  • A dialog box that prompts the user to enter an action for a single content type.
  • A dialog box that prompts the user to enter an action for mixed content types.
  • A property page.

Single Content Type Dialog Box

A dialog box similar to the following is displayed when any supported media not yet assigned a default AutoPlay action is presented to the system.

Users can do one of the following:

  • Choose an action from the list of registered applications
  • List the files on the medium in a normal folder view

Users can also save their choice as the default action for this medium.

For an application to be included in the list of possible actions, it must be registered with AutoPlay. For more information, see Preparing Hardware and Software for Use with AutoPlay.

Mixed Media Dialog Box

The following dialog box is displayed when any medium containing a mix of supported file types is presented to the system. This is essentially the same as the single content medium dialog box but with two significant differences. First, the available action options consist of a filtered list of applications relevant to all content types present on the medium. Second, there is no option to choose a permanent default action because the content types and percentages of mixed content media are too unpredictable.

For an application to be included in the list of possible actions, it must be registered with AutoPlay. For more information, see Preparing Hardware and Software for Use with AutoPlay.

Property Page

The following is a sample AutoPlay property page for a DVD/CD-ROM device.

Each device type offers an appropriate subset of content types for AutoPlay configuration. In turn, each content type, when selected, offers an appropriate list of action options in the list box. A different action can be chosen for each content type.


Preparing Hardware and Software for Use with AutoPlay

[This is preliminary documentation and subject to change.]

Devices and applications are largely responsible for providing the information necessary to work with AutoPlay. The following topics discuss some of the necessary implementations.

  • Providing Device Information
  • Sniffing of Devices or Media for Registered Content Types
  • Registering Devices and Applications

Providing Device Information

Hardware manufacturers can provide information about their device through the following methods in decreasing order of precedence.

  • INF file
  • Windows Update
  • CD database

This information can include a friendly name, the manufacturers' branded icon for display in My Computer, and names of specific device handlers that AutoPlay can use to handle events related to their device. Microsoft® Windows® looks for the following information.

  • Default Icon
  • Default Label
  • Device Handler
  • Device Group (Note Device group settings can be used to provide all of the above. However, individual device group settings may be overridden by registering an icon, label, or handler at the device instance level.)

Hardware manufacturers can provide this information at one of the following three levels.

  • Device Class
  • Device Group
  • Device Instance

Device Handlers

Device handlers are the means by which devices are connected to applications. Many devices can point to the same device handler. Therefore, applications registering under existing device handlers can handle events for many devices. Device handlers are specified in subkeys of the DeviceHandlers key as illustrated below for the example device handler "GenericVolumeHandler". Note that the name of the subkey is the name of the device handler itself.

%AutoPlayHandlersPath%
    DeviceHandlers
        GenericVolumeHandler

The device handler key can have two optional subkeys.

  • EventHandlers
  • ContentTypes

Event Handlers

The EventHandler subkey is used when a device does not provide content information or in an instance where no known content types are found on the device. The EventHandler key is registered as a subkey of its device handler.

%AutoPlayHandlersPath%
    DeviceHandlers
        GenericVolumeHandler
            EventHandlers

Specific events are entered as subkeys below the EventHandlers key. These subkeys are named for the event they watch for. In the example below, two subkeys have been registered: MediaArrival and DeviceArrival. s

%AutoPlayHandlersPath%
    DeviceHandlers
        GenericVolumeHandler
            EventHandlers
                MediaArrival
                DeviceArrival

Each of these events has the following values.

Name | Type | Data
Event handler name, for example MediaArrival. This name will match a subkey under %AutoPlayHandlers%\EventHandlers (not to be confused with the EventHandlers key discussed above). | REG_SZ | None
DefaultIcon | REG_EXPAND_SZ (preferred) or REG_SZ | Path and icon index or ID of an icon that represents the event. For example, %SystemRoot%\system32\shell32.dll,123
FriendlyName | REG_SZ | A friendly name for the event, such as plug the device

Content Types

ContentTypes is registered as a subkey of its specific device handler as illustrated below.

%AutoPlayHandlersPath%
    DeviceHandlers
        GenericVolumeHandler
            ContentTypes

If a device provides content information, this key offers the possibility of registering ContentTypeSniffers that sniff out the content of the device when this event is triggered. Those devices that do not expose their content information should not use a sniffer. Instead, they should directly specify an EventHandler. If the ContentTypeSniffers do not find a match for the content of the device, AutoPlay defaults to the EventHandler specified above (GenericVolumeArrival in the example). ContentType values are as follows:

Name | Type | Data
The name of a sniffer defined under the ContentTypeSniffer key. For example, PicturesContentSniffer | REG_SZ | None

For more information, see the the Microsoft Platform Driver Development Kit (DDK) Shell documentation.

Sniffing of Devices or Media for Registered Content Types

There are two methods used to sniff for supported content.

  • Provider-created Desktop.ini File
  • Sniffing for Files and Folders in Known Locations

Provider-created Desktop.ini File

A Desktop.ini file can be provided to catalog the content of the files placed on the media. It is constructed using the following sections:

[<mime type>]
<device-ID + content-ID>=<PnP-ID>

[<device-ID + content-ID>]
<relative folder path>=<file extension list>
Creator=<device friendly name>

Content-IDs are not pre-defined. Device manufacturers must define a content-ID that avoids section name collision if their device supports more than one data format (for example, KodakDC260Pictures and KodakDC260MusicFiles).

The relative folder path tells the system where to sniff for that content type. This is paired with a list of the file extensions to look for in that location.

The Creator entry enables the system to determine whether a picture was created from a camera or copied from another medium. This information may be used in the future.

The following is a sample Desktop.ini file.

[images/jpeg]
KodakDC260Pictures="VID_0001&PID_0001"
SonyXYZPictures="VID_0002&PID_0001"

[audio/x-mp3]
KodakDC260Music="VID_0001&PID_0001"

[KodakDC260Pictures]
DCIM\DC260=*.jpg
DCIM\DC260\2000-04-04=*.jpg
DCIM\DC260\2000-04-05=*.jpg
Creator=Kodak Digital Camera DC 260

[KodakDC260Music]
HIFI\Kodak=*.mp3
Creator=Kodak Digital Camera DC 260

[SonyXYZPictures]
DCIM\SonyXYZ=*.jpg

Sniffing for Files and Folders in Known Locations

Regardless of the presence of a Desktop.ini file, AutoPlay always checks for the following files and folders. When it finds a matching file type, it launches the appropriate content handler.

Content Type | File Types | File Locations
Pictures | *.jpg *.bmp *.gif | \DCIM\* \DCF\*
Music | *.mp3 *.wma | \HIFI\*
Video | *.mpg *.mpeg *.avi | \TS_VIDEO\*

Registering Devices and Applications

Applications provide their AutoPlay parameters through registry keys. This registration consists of two parts.

  • Device Registration
  • Application Registration

Device Registration

A device can provide four pieces of information through the AutoPlay registration.

  • Branded icons
  • A branded name
  • Names and locations of one or more Device Handlers
  • A device group

This information can be provided in several ways.

  • The device can identify itself as being part of a Device Class.
  • The device can identify itself as being part of a Device Group. Thereafter, the device inherits all icons, the branded name, and the Device Handler settings specific to this Device Group. Settings at this level take precedence over settings at the Device Class level.
  • The device can specify settings at the Device Instance level. Settings at this level take precedence over settings at both the Device Group and Device Class levels.

The information is specified using Windows Registry entries. Following are the subkeys and values required for each piece of information as well as the values to register as part of a Device Group.

Registration in a Device Group

Name | Type | Data
DeviceGroup | REG_SZ | Device group name, such as "ZipDrive", "Memory Stick", "SanDisk", and so on.

This value is registered under the following keys as shown below.

HKEY_LOCAL_MACHINE
    SYSTEM
        CurrentControlSet
            Enum
                <PnP-ID>
                    <PnP Inst ID>
                        Device Parameters
                            DeviceGroup

Registering the Default Icon, Branded Device Name, and Device Handlers

Name | Type | Data
Icons | REG_MULTI_SZ | Path and icon index or ID of an icon that represent the device. For example, "%SystemRoot%\system32\shell32.dll,123". Note Multiple icons can be entered in the REG_MULTI_SZ string. The first value is used as the default icon for the device. Other icons, if any, are available for the user to choose should they wish to change the icon.
Label | REG_SZ | The desired friendly name for the device. For example, "USB Zip Drive".
DeviceHandlers | REG_SZ | Name of the device handler, matching the name of a device handler key.

These values can be registered at either the Device Instance or Device Group level under the following keys as shown below. Settings registered for a Device Instance will have precendence over settings registered for a Device Group.

At the Device Instance level

HKEY_LOCAL_MACHINE
    SYSTEM
        CurrentControlSet
            Enum
                <PupID>
                    <PoP Inst ID>
                            Device Parameters
                                Icon
                                Label
                                DeviceHandlers

At the Device Group level

HKEY_LOCAL_MACHINE
    Software
        Microsoft
            Windows
                CurrentVersion
                    Explorer
                        AutoPlayHandlers
                            DeviceGroups
                                <DeviceGroup>
                                    Icon
                                    Label
                                    DeviceHandlers

Application Registration

Applications register themselves to handle specific events for one or more DeviceHandlers. When AutoPlay detects an event for a hardware device, it consults the registration settings for that device to identify one or more device handlers. Device handlers are the means by which devices are connected to applications, and many devices can point to the same device handler. Therefore, applications registering under existing device handlers can handle events for many devices. If a device handler is found, AutoPlay tries to find a registered application to invoke for that specific event. If the device provides content, AutoPlay also takes into consideration the content of the device at the time of the event to find the most suitable registered application.

The values and keys discussed in the following documentation are located under the AutoPlayHandlers key. This registry location will be referred to as %AutoPlayHandlersPath%.

HKEY_LOCAL_MACHINE
    SOFTWARE
        Microsoft
            Windows
                Current Version
                    Explorer
                        AutoPlayHandlers

An application can provide registration information at many levels, depending on its requirements. Following is a description of the possible application registration settings.

  • ContentTypeSniffers
  • ContentTypeHandlers
  • EventHandlers
  • Handlers

ContentTypeSniffers

The ContentTypeSniffer key is registered as a subkey of the AutoPlayHandlers key as illustrated below.

%AutoPlayHandlersPath%
    ContentTypeSniffers

Each individual content type sniffer is registered as a subkey of the ContentTypeSniffer key. The subkey name is the name of the sniffer. For example, PicturesContentSniffer. Content sniffers specify file types to look for and directories in which to look for them. If an event is triggered that calls a content type sniffer and a supported file type is found, that content is then linked to a ContentTypeHandler. Many different device handlers can refer to a specific content type sniffer. In the example below, three content type sniffers have been registered.

%AutoPlayHandlersPath%
    ContentTypeSniffers
        MusicFilesContentSniffer
        VideoFilesContentSniffer
        PictureFilesContentSniffer

Each individual content type sniffer key can have the following values.

Name | Type | Data
RelPattern | REG_MULTI_SZ | A relative path or paths with or without wildcard characters. For example, DCIM\*\*.jpg.
ContentTypeHandler | REG_SZ | The name of a handler defined under the ContentTypeHandler key. For example, PicturesContentHandler

ContentTypeHandlers

Once supported content has been identified on the device that generated the triggering event, the entries under the ContentTypeHandlers key are used to identify an event handler to react to the event. The ContentTypeHandlers key is registered as a subkey of AutoPlayHandlers.

%AutoPlayHandlersPath%
    ContentTypeHandlers

Subkeys of the ContentTypeHandlers key match the data entries under ContentTypeSniffers. The following is an example for the PicturesContentHandler.

%AutoPlayHandlersPath%
    ContentTypeHandlers
        PicturesContentHandler

Each individual content type handler can have two subkeys.

  • EventHandlers
  • FriendlyName

In addition, each content type handler can have the following values.

Name | Type | Data
DefaultIcon | REG_EXPAND_SZ (preferred) or REG_SZ | Path and icon index or ID of an icon that represents the content. For example, %SystemRoot%\system32\shell32.dll,123
FriendlyName | REG_SZ | A friendly name for the content, such as picture files

EventHandlers

Specific events are entered as subkeys below the EventHandlers key. These subkeys are named for the event they watch for. In the example below, four standard subkeys have been registered for media and device arrival and removal.

%AutoPlayHandlersPath%
    ContentTypeHandlers
        PicturesContentHandler
            EventHandlers
                MediaArrival
                MediaRemoval
                DeviceArrival
                DeviceRemoval

Each of these events has the following values.

Name | Type | Data
Event handler name, for example MediaArrival. This name matches a subkey under the EventHandlers key. More than one event handler can be entered for each event. | REG_SZ | None
DefaultIcon | REG_EXPAND_SZ (preferred) or REG_SZ | Path and icon index or ID of an icon. For example, %SystemRoot%\system32\shell32.dll,123

FriendlyName

The FriendlyName subkey has the following values.

Name | Type | Data
Content | REG_SZ | A brief phrase describing the content. This phrase is inserted into the sentence "When Windows detects phrases." seen by the user in the UI. For example, picture files or a DVD.
IconLabel | REG_SZ | A short name for the content that is used as an icon label. For example, Pictures.

EventHandlers

The EventHandlers key is used to register Handlers, which are offered to the user as choices to handle events. The event handler entries registered under this key are arrived at through the individual event subkeys registered under the EventHandler subkey of either a DeviceHandler or ContentTypeHandler key.

Individual event handlers are registered under their own name as subkeys of the EventHandlers key as shown below for the ShowPicturesOnArrival example.

%AutoPlayHandlersPath%
    EventHandlers
        ShowPicturesOnArrival

The individual event handler keys have the following value.

Name | Type | Data
The name of a handler as described under Handlers. For example, MSShowPicturesOnArrival. Any given event handler may have several of these handler entries. | REG_SZ | None

Handlers

Entries under the Handler key specify what to execute for a certain event on a given device. This is a COM component that implements the IHWEventHandler interface that AutoPlay instantiates out of process, then invokes. The names of the subkeys under Handlers are the names of the handlers themselves, such as "MSShowPicturesOnArrival", as illustrated in the following example.

%AutoPlayHandlersPath%
    Handlers
        MSShowPicturesOnArrival

Each individual handler can have the following values.

Name | Type | Data
ProgID | REG_SZ | A string representing the COM component to instantiate. For example, Shell.AutoplayForSlideShow
InitCmdLine | REG_EXPAND_SZ | A string that is passed to the COM component as part of the Init method call.
FriendlyName | REG_SZ | A string describing the action that will occur as well as the application that will be used to carry out the action. For example, View pictures with Windows SlideShow
DefaultIcon | REG_EXPAND_SZ (preferred) or REG_SZ | Path and icon index or ID of an icon that represents the handler application. For example, %SystemRoot%\system32\shell32.dll,123

COM components registered as handlers should register themselves to run as the "Interactive User" by registering a key for the COM component's CLSID at the location shown below.

HKEY_CLASSES_ROOT
    AppID
        <CLSID>

This value should be added to that CLSID key.

Name | Type | Data
RunAs | REG_SZ | Interactive User


Intermediate Shell Techniques

This documentation discusses how applications can interact effectively with the Shell. It assumes a working knowledge of the material covered in Shell Basics, and it focuses on some of the more sophisticated and powerful Shell techniques.

  • Programming the Shell
  • Extending the Shell

Programming the Shell

This section discusses how to use some of the more sophisticated and powerful features of the Shell application programming interface (API) in your application.

  • Standard Shell Interfaces
  • Shell Links
  • Internet Shortcuts
  • The Taskbar
  • Application Desktop Toolbars
  • Using Autocomplete

Extending the Shell

The first item in this section discusses how you can extend the Shell's basic capabilities by writing various Shell extension handlers. These handlers are called by the Shell and allow you to dynamically modify the Shell's behavior when it takes such actions as displaying a file's shortcut menu. A disk cleanup handler allows applications to integrate their cleanup activities with the standard Shell cleanup utility. The final section discusses how to customize the way the contents of a folder are displayed by Windows® Explorer.

  • Creating Shell Extension Handlers
  • Creating a Disk Cleanup Handler
  • Customizing a Folder's Web View

Note To improve the readability of the sample code in the Intermediate Shell Techniques documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values and data are in a normal font.


Intermediate Shell Techniques: Programming the Shell

This section discusses how to use some of the more sophisticated and powerful features of the Shell application programming interface (API) in your application.

  • Standard Shell Interfaces
  • Shell Links
  • Internet Shortcuts
  • The Taskbar
  • Application Desktop Toolbars
  • Using Autocomplete

Note To improve the readability of the sample code in the Intermediate Shell Techniques documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values and data are in a normal font.


Standard Shell Interfaces

A large number of standard interfaces are defined by the Shell and declared in Shlobj.h. Most fall into one of three general categories:

  • Interfaces that are exposed by folders and available for use by applications.
  • Interfaces that are exposed by folders but are used only by the Shell. These interfaces are not generally used by applications but must be implemented by namespace extensions.
  • Interfaces that are used by Shell extensions, such as shell extension handlers or band objects. These interfaces are covered in the discussion of the associated Shell extension.

This documentation covers the first category, those standard Shell interfaces that can be exposed by folders for use by applications. The first section is a brief discussion of the available interfaces. The last section lists the interfaces that are exposed by the Shell folders that are included with the system.

  • Interfaces Exposed by Shell Folder Objects
  • Interfaces Exposed by Standard Shell Folders

Interfaces Exposed by Shell Folder Objects

Shell folder objects can expose a variety of interfaces for use by applications. Applications typically interact with folders primarily through one or more of the standard Shell interfaces.

The primary interface, which must be exposed by all Shell folders, is IShellFolder. To use a folder's other Shell interfaces, an application must first retrieve a pointer to the folder's IShellFolder interface. The procedure for getting this interface pointer is discussed in the Shell Basics document. The other Shell folder interfaces fall into two basic classes:

  • Interfaces that are exposed directly by the folder object. An application retrieves a pointer to these interfaces by calling the folder's IShellFolder::QueryInterface method.
  • Interfaces that are exposed indirectly. To retrieve a pointer to one of these interfaces, an application calls one of several IShellFolder or IShellFolder2 methods, most commonly IShellFolder::GetUIObjectOf. The folder object then creates an object that exposes the requested interface and returns the interface pointer.

Note There are only two interfaces that Shell folders must expose to applications. One is IShellFolder itself. The other is IEnumIDList, which is exposed indirectly through IShellFolder::EnumObjects. The availability of other interfaces depends on the implementation of the particular folder object.

The following two sections list the Shell interfaces that Shell folders can expose for use by applications.

Directly Exposed Interfaces

The following interfaces are exposed directly by the Shell folder object. Applications obtain an interface pointer by calling IShellFolder::QueryInterface.

Interface | Description
IRemoteComputer | Allows an application to enumerate or initialize a virtual folder when it is invoked on a remote object.
IShellIcon | Allows an application to obtain the icon for any object within a folder by using only one instance of the interface.
IShellFolder2 | Extends the capabilities of IShellFolder.

Indirectly Exposed Interfaces

The following interfaces are exposed indirectly. To retrieve an interface pointer, call the specified method. The folder creates an object that exposes the requested interface and returns a pointer to it.

Interface | Description | Pointer returned by
IContextMenu | Allows an application to retrieve information on an object's shortcut menus. | IShellFolder::GetUIObjectOf
IContextMenu2 | Extends IContextMenu. | IShellFolder::GetUIObjectOf
IContextMenu3 | Extends IContextMenu2. | IShellFolder::GetUIObjectOf
IDataObject | Allows an application to specify how its objects should be represented in drag/drop and clipboard operations. | IShellFolder::GetUIObjectOf
IDropTarget | Allows the system to communicate with a folder when a user attempts to drop a data object on an item in the folder during a drag-and-drop operation. | IShellFolder::GetUIObjectOf
IEnumExtraSearch | Allows an application to enumerate the search objects that a folder supports. | IShellFolder2::EnumSearches
IEnumIDList | Allows an application to enumerate the PIDLs of the items in a Shell folder. | IShellFolder::EnumObjects
IExtractIcon | Allows an application to obtain a Shell object's icon. | IShellFolder::GetUIObjectOf
IExtractImage | Allows an application to request a thumbnail image. | IShellFolder::GetUIObjectOf
IExtractImage2 | Extends the capabilities of IExtractImage. | IShellFolder::GetUIObjectOf
IShellDetails | Provides detailed information about the items in a folder. For Shell version 5.0 and later, this interface is superseded by methods included in IShellFolder2. | IShellFolder::CreateViewObject
IShellLink | Allows Shell links to be created, modified, and resolved. | IShellFolder::GetUIObjectOf

Interfaces Exposed by Standard Shell Folders

A number of folders or classes of folders are standard on Windows® 2000 systems. Most of these folders are also found on systems with earlier shell versions, but they will only expose the interfaces that were available with that version. The following table lists the Shell interfaces that the standard Windows 2000 folders expose for use by applications. The standard COM interfaces that they expose, such as IDropTarget, are also listed.

Folder | Direct interfaces | Indirect interfaces
Control Panel | IShellFolder, IShellFolder2 | IContextMenu, IDataObject, IEnumIDList, IExtractIcon
Desktop | IShellFolder, IShellFolder2, IShellIcon | IContextMenu, IDataObject, IDropTarget, IEnumIDList, IExtractIcon
Drive folders | IShellFolder, IShellFolder2 | IContextMenu, IDataObject, IDropTarget, IEnumIDList, IExtractIcon
File system folders | IShellFolder, IShellFolder2, IShellIcon | IContextMenu, IDataObject, IDropTarget, IEnumExtraSearch, IEnumIDList, IExtractImage
Internet Explorer | IShellFolder, IShellFolder2 | IEnumIDList
My Computer | IShellFolder, IShellFolder2, IShellIcon | IContextMenu, IDataObject, IDropTarget, IEnumExtraSearch, IEnumIDList, IExtractImage
My Documents | IShellFolder | IContextMenu, IShellDetails, IDataObject, IDropTarget, IEnumIDList, IExtractImage
My Network Places | IShellFolder, IShellFolder2 | IContextMenu, IDataObject, IDropTarget, IEnumIDList, IExtractIcon
Printers | IRemoteComputer, IShellFolder, IShellFolder2 | IContextMenu, IDataObject, IDropTarget, IEnumIDList, IExtractIcon, IShellDetails
Recycle Bin | IShellFolder, IShellFolder2 | IContextMenu, IDataObject, IEnumIDList, IExtractIcon

Note The IDataObject and IDropTarget interfaces are exposed indirectly through IShellFolder::GetUIObjectOf.


Shell Links

A Shell link is a data object that contains information used to access another object in the Shell's namespace—that is, any object visible through Microsoft® Windows® Explorer. The types of objects that can be accessed through Shell links include files, folders, disk drives, and printers. A Shell link allows a user or an application to access an object from anywhere in the namespace. The user or application does not need to know the current name and location of the object.

  • About Shell Links
  • Using Shell Links

About Shell Links

The user creates a Shell link by choosing the Create Shortcut command from an object's shortcut menu. The system automatically creates an icon for the Shell link by combining the object's icon with a small arrow (known as the system-defined link overlay icon) that appears in the lower left corner of the icon. A Shell link that has an icon is called a shortcut; however, the terms Shell link and shortcut are often used interchangeably. Typically, the user creates shortcuts to gain quick access to objects stored in subfolders or in shared folders on other computers. For example, a user can create a shortcut to a Microsoft® Word document that is located in a subfolder and place the shortcut icon on the desktop. The user can then open the document by double-clicking the shortcut icon. If the document is moved or renamed after the shortcut is created, the system will attempt to update the shortcut the next time the user selects it.

Applications can also create and use Shell links and shortcuts. For example, a word processing application might create a Shell link to implement a list of the most recently used documents. An application creates a Shell link by using the IShellLink interface to create a Shell link object. The application uses the IPersistFile or IPersistStream interface to store the object in a file or stream.

This overview describes the IShellLink interface and explains how to use it to create and resolve Shell links from within a Microsoft® Win32®-based application. Because the design of Shell links is based on the OLE Component Object Model (COM), you should be familiar with the basic concepts of COM and OLE programming before reading this overview.

Link Resolution

If a user creates a shortcut to an object and the name or location of the object is later changed, the system automatically takes steps to update, or resolve, the shortcut the next time the user selects it. However, if an application creates a Shell link and stores it in a stream, the system does not automatically attempt to resolve the link. The application must resolve the link by calling the IShellLink::Resolve method.

When a Shell link is created, the system saves information about the link. When resolving a link—either automatically or with an IShellLink::Resolve call—the system first retrieves the path associated with the Shell link by using a pointer to the Shell link's identifier list. For more information about the identifier list, see Item Identifiers and Identifier Lists. The system searches for the associated object in that path and, if it finds the object, resolves the link. If the system cannot find the object, it calls on the Distributed Link Tracking (DLT) service, if available, to locate the object. If the DLT service is not available or cannot find the object, the system looks in the same directory for an object with the same file creation time and attributes but with a different name. This type of search resolves a link to an object that has been renamed.

If the system still cannot find the object, it searches the directories, the desktop, and local volumes, looking recursively though the directory tree for an object with either the same name or creation time. If the system still does not find a match, it displays a dialog box prompting the user for a location. An application can suppress the dialog box by specifying the SLR_NO_UI value in a call to IShellLink::Resolve.

Initialization of the Component Object Library

Before an application can create and resolve shortcuts, it must initialize the component object library by calling the CoInitialize function. Each call to CoInitialize requires a corresponding call to the CoUninitialize function, which an application should call when it terminates. The call to CoUninitialize ensures that the application does not terminate until it has received all of its pending messages.

Location-Independent Names

The system provides location-independent names for Shell links to objects stored in shared folders. If the object is stored locally, the system provides the local path and file name for the object. If the object is stored remotely, the system provides a Universal Naming Convention (UNC) network resource name for the object. Because the system provides location-independent names, a Shell link can serve as a universal name for a file that can be transferred to other computers.

Link Files

When the user creates a shortcut to an object by choosing the Create Shortcut command from the object's shortcut menu, Windows stores the information it needs to access the object in a link file—a binary file that has the .lnk file name extension. A link file contains the following information:

  • The location (path) of the object referenced by the shortcut (called the corresponding object).
  • The working directory of the corresponding object.
  • The list of arguments that the system passes to the corresponding object when the IContextMenu::InvokeCommand method is activated for the shortcut.
  • The show command used to set the initial show state of the corresponding object. This is one of the SW_ values described in ShowWindow.
  • The location (path and index) of the shortcut's icon.
  • The shortcut's description string.
  • The hot key for the shortcut.

When a link file is deleted, the corresponding object is not affected.

If you create a shortcut to another shortcut, the system simply copies the link file rather than creating a new link file. In this case, the shortcuts will not be independent of each other.

An application can register a file name extension as a shortcut file type. If a file has a file name extension that has been registered as a shortcut file type, the system automatically adds the system-defined link overlay icon (a small arrow) to the file's icon. To register a file name extension as a shortcut file type, you must add the IsShortcut value to the registry description of the file name extension, as shown in the example below. Note that the Shell must be restarted for the overlay icon to take effect.

HKEY_CLASSES_ROOT
  .xyz    (Default) = "XYZApp"
  .
  .
  .
  XYZApp  IsShortcut = ""

Shortcut names

The shortcut's name, which is a string that appears below the Shell link icon, is actually the file name of the shortcut itself. The user can edit the description string by selecting it and entering a new string.

Location of shortcuts in the namespace

A shortcut can exist on the desktop or anywhere in the Shell's namespace. Similarly, the object that is associated with the shortcut can also exist anywhere in the Shell's namespace. An application can use the IShellLink::SetPath method to set the path and file name for the associated object, and the IShellLink::GetPath method to retrieve the current path and file name for the object.

Shortcut working directory

The working directory is the directory where the corresponding object of a shortcut loads or stores files when the user does not identify a specific directory. A link file contains the name of the working directory for the corresponding object. An application can set the name of the working directory for the corresponding object by using the IShellLink::SetWorkingDirectory method and can retrieve the name of the current working directory for the corresponding object by using the IShellLink::GetWorkingDirectory method.

Shortcut command-line arguments

A link file contains command-line arguments that the Shell passes to the corresponding object when the user selects the link. An application can set the command-line arguments for a shortcut by using the IShellLink::SetArguments method. It is useful to set command-line arguments when the corresponding application, such as a linker or compiler, takes special flags as arguments. An application can retrieve the command-line arguments from a shortcut by using the IShellLink::GetArguments method.

Shortcut show commands

When the user double-clicks a shortcut, the system starts the application associated with the corresponding object and sets the initial show state of the application based on the show command specified by the shortcut. The show command can be any of the SW_ values included in the description of the ShowWindow function. An application can set the show command for a shortcut by using the IShellLink::SetShowCmd method and can retrieve the current show command by using the IShellLink::GetShowCmd method.

Shortcut icons

Like other Shell objects, a shortcut has an icon. The user accesses the object associated with a shortcut by double-clicking the shortcut's icon. When the system creates an icon for a shortcut, it uses the bitmap of the corresponding object and adds the system-defined link overlay icon (a small arrow) to the lower left corner. An application can set the location (path and index) of a shortcut's icon by using the IShellLink::SetIconLocation method. An application can retrieve this location by using the IShellLink::GetIconLocation method.

Shortcut descriptions

Shortcuts have descriptions, but the user never sees them. An application can use a description to store any text information. Descriptions are set using the IShellLink::SetDescription method and retrieved using the IShellLink::GetDescription method.

Shortcut hot keys

A shortcut object can have a hot key associated with it. Hot keys allow a user to press a combination of keys to activate a shortcut. An application can set the hot key for a shortcut by using the IShellLink::SetHotkey method and can retrieve the current hot key by using the IShellLink::GetHotkey method.

Item Identifiers and Identifier Lists

The Shell uses object identifiers within the Shell's namespace. All objects visible in the Shell (files, directories, servers, workgroups, and so on) have unique identifiers among the objects within their parent folder. These identifiers are called item identifiers, and they have the SHITEMID data type as defined in the Shlobj.h header file. An item identifier is a variable-length byte stream that contains information that identifies an object within a folder. Only the creator of an item identifier knows the content and format of the identifier. The only part of an item identifier that the Shell uses is the first two bytes, which specify the size of the identifier.

Each parent folder has its own item identifier that identifies it within its own parent folder. Thus, any Shell object can be uniquely identified by a list of item identifiers. A parent folder keeps a list of identifiers for the items it contains. The list has the ITEMIDLIST data type. Item identifier lists are allocated by the Shell and may be passed across Shell interfaces, such as IShellFolder. It is important to remember that each identifier in an item identifier list is only meaningful within the context of its parent folder.

An application can set a shortcut's item identifier list by using the IShellLink::SetIDList method. This method is useful when setting a shortcut to an object that is not a file, such as a printer or disk drive. An application can retrieve a shortcut's item identifier list by using the IShellLink::GetIDList method.

Using Shell Links

This section contains examples that demonstrate how to create and resolve shortcuts from within a Win32-based application. This section assumes you are familiar with Win32, C++, and OLE COM programming.

Creating a Shortcut to a File

The CreateLink sample function in the following example creates a shortcut. The parameters include a pointer to the name of the file to link to, a pointer to the name of the shortcut that you are creating, and a pointer to the description of the link. The description consists of the string, "Shortcut to file name," where file name is the name of the file to link to.

Because CreateLink calls the CoCreateInstance function, it is assumed that the CoInitialize function has already been called. CreateLink uses the IPersistFile interface to save the shortcut and the IShellLink interface to store the file name and description.

// CreateLink - uses the Shell's IShellLink and IPersistFile interfaces
//   to create and store a shortcut to the specified object.
// Returns the result of calling the member functions of the interfaces.
// lpszPathObj - address of a buffer containing the path of the object.
// lpszPathLink - address of a buffer containing the path where the
//   Shell link is to be stored.
// lpszDesc - address of a buffer containing the description of the
//   Shell link.

HRESULT CreateLink(LPCSTR lpszPathObj,
    LPCSTR lpszPathLink, LPCSTR lpszDesc)
{
    HRESULT hres;
    IShellLink* psl;

    // Get a pointer to the IShellLink interface.
    hres = CoCreateInstance(CLSID_ShellLink, NULL,
        CLSCTX_INPROC_SERVER, IID_IShellLink, (LPVOID *) &psl);
    if (SUCCEEDED(hres)) {
        IPersistFile* ppf;

        // Set the path to the shortcut target and add the
        // description.
        psl->SetPath(lpszPathObj);
        psl->SetDescription(lpszDesc);

       // Query IShellLink for the IPersistFile interface for saving the
       // shortcut in persistent storage.
        hres = psl->QueryInterface(&IID_IPersistFile,
            (LPVOID*)&ppf);

        if (SUCCEEDED(hres)) {
            WCHAR wsz[MAX_PATH];

            // Ensure that the string is Unicode.
            MultiByteToWideChar(CP_ACP, 0, lpszPathLink, -1,
                wsz, MAX_PATH);

            // Save the link by calling IPersistFile::Save.
            hres = ppf->Save(wsz, TRUE);
            ppf->Release();
        }
        psl->Release();
    }
    return hres;
}

Resolving a Shortcut

An application may need to access and manipulate a shortcut that was previously created. This operation is referred to as resolving the shortcut.

The application-defined ResolveIt function in the following example resolves a shortcut. Its parameters include a window handle, a pointer to the path of the shortcut, and the address of a buffer that receives the new path to the object. The window handle identifies the parent window for any message boxes that the Shell may need to display. For example, the Shell can display a message box if the link is on unshared media, if network problems occur, if the user needs to insert a floppy disk, and so on.

The ResolveIt function calls the CoCreateInstance function and assumes that the CoInitialize function has already been called. Note that ResolveIt needs to use the IPersistFile interface to store the link information. IPersistFile is implemented by the IShellLink object. The link information must be loaded before the path information is retrieved, which is shown later in the example. Failing to load the link information causes the calls to the IShellLink::GetPath and IShellLink::GetDescription member functions to fail.

HRESULT ResolveIt(HWND hwnd, LPCSTR lpszLinkFile, LPSTR lpszPath)
{
    HRESULT hres;
    IShellLink* psl;
    char szGotPath[MAX_PATH];
    char szDescription[MAX_PATH];
    WIN32_FIND_DATA wfd;

    *lpszPath = 0; // assume failure

    // Get a pointer to the IShellLink interface.
    hres = CoCreateInstance(CLSID_ShellLink, NULL,
        CLSCTX_INPROC_SERVER, IID_IShellLink, (LPVOID *) &psl);
    if (SUCCEEDED(hres)) {
        IPersistFile* ppf;

        // Get a pointer to the IPersistFile interface.
        hres = psl->QueryInterface(IID_IPersistFile, (void**)&ppf);
        if (SUCCEEDED(hres)) {
            WCHAR wsz[MAX_PATH];

            // Ensure that the string is Unicode.
            MultiByteToWideChar(CP_ACP, 0, lpszLinkFile, -1, wsz,
                MAX_PATH);

            // Load the shortcut.
            hres = ppf->Load(wsz, STGM_READ);
            if (SUCCEEDED(hres)) {

                // Resolve the link.
                hres = psl->Resolve(hwnd, 0);
                if (SUCCEEDED(hres)) {

                    // Get the path to the link target.
                    hres = psl->GetPath(szGotPath,
                        MAX_PATH, (WIN32_FIND_DATA *)&wfd,
                        SLGP_SHORTPATH );
                    if (FAILED(hres))
                        HandleErr(hres); // application-defined function

                    // Get the description of the target.
                    hres = psl->GetDescription(szDescription, MAX_PATH);
                    if (FAILED(hres))
                        HandleErr(hres);
                    lstrcpy(lpszPath, szGotPath);
                }
            }
        // Release the pointer to the IPersistFile interface.
        ppf->Release();
        }
    // Release the pointer to the IShellLink interface.
    psl->Release();
    }
    return hres;
}

Creating a Shortcut to a Nonfile Object

Creating a shortcut to a nonfile object, such as a printer, is similar to creating a shortcut to a file except that rather than setting the path to the file, you must set the identifier list to the printer. To set the identifier list, call the IShellLink::SetIDList method, specifying the address of an identifier list.

Each object within the Shell's namespace has an item identifier. The Shell often concatenates item identifiers into null-terminated lists consisting of any number of item identifiers. For more information about item identifiers, see Item Identifiers and Identifier Lists.

In general, if you need to set a shortcut to an item that does not have a file name, such as a printer, you will already have a pointer to the object's IShellFolder interface. IShellFolder is used to create namespace extensions.

Once you have the class identifier for IShellFolder, you can call the CoCreateInstance function to retrieve the address of the interface. Then you can call the interface to enumerate the objects in the folder and retrieve the address of the item identifier for the object that you are searching for. Finally, you can use the address in a call to the IShellLink::SetIDList member function to create a shortcut to the object.


Internet Shortcuts

The Internet shortcut object is used to create desktop shortcuts to Internet sites. Like shortcuts to items in the file system, Internet shortcuts take the form of an icon on the desktop. When the user clicks the icon, the browser is launched and displays the site associated with the shortcut.

Creating Internet Shortcuts

You can create an Internet shortcut by using a WebBrowser control or with the URL of the page.

Creating an Internet Shortcut from a WebBrowser Control

If your application hosts a WebBrowser control, you can use the Internet shortcut object to create shortcuts in the following way:

  1. Create an instance of the Internet shortcut object with CoCreateInstance, using a CLSID of CLSID_InternetShortcut.
  2. Pass the pointer to the WebBrowser's IUnknown interface to the Internet shortcut object with IObjectWithSite::SetSite.
  3. Call the Internet shortcut object's IPersistFile::Save method when you want to create a shortcut to the page being viewed by the WebBrowser control.

A shortcut will be created in the location specified in IPersistFile::Save. This location enables the WebBrowser control to restore its state, which includes the task of loading of the correct documents into framesets.

Creating an Internet Shortcut from a URL

You can also create an Internet shortcut if you have the URL of the page to which you want to link:

  1. Create an instance of the Internet shortcut object with CoCreateInstance, using a CLSID of CLSID_InternetShortcut.
  2. Use the IUniformResourceLocator::SetURL method to set the URL in the shortcut.
  3. Use the IPersistFile::Save method to save the shortcut file to a desired location.

Accessing Property Storage

The Internet shortcut object contains several properties that you can access through the object's IPropertySetStorage interface with the following procedure:

  1. Get the IPropertySetStorage interface by calling QueryInterface with IID_IPropertySetStorage.
  2. Access the Internet shortcut property storage set by calling IPropertySetStorage::Open with FMTID_Intshcut or FMTID_InternetSite to obtain the IPropertyStorage interface.
  3. Read the property storage information with IPropertyStorage::ReadMultiple by passing the appropriate property ID.

With version 4.70 or higher of Shell32.dll, you can also retrieve the IPropertySetStorage interface by calling IShellFolder::BindToStorage with the pidl parameter set to the .URL file and the riid parameter set to IID_IPropertySetStorage.

The following property IDs can be requested for FMTID_Intshcut.

PROPID | Variant Type | Description
PID_IS_URL | VT_LPWSTR | URL to which the shortcut leads
PID_IS_NAME | VT_LPWSTR | Name of the Internet shortcut
PID_IS_WORKINGDIR | VT_LPWSTR | Working directory for the shortcut
PID_IS_HOTKEY | VT_UI2 | Hotkey for the shortcut
PID_IS_SHOWCMD | VT_I4 | Show command for shortcut
PID_IS_ICONINDEX | VT_I4 | Index of the icon
PID_IS_ICONFILE | VT_LPWSTR | File that contains the icon
PID_IS_WHATSNEW | VT_LPWSTR | What's New text
PID_IS_AUTHOR | VT_LPWSTR | Author
PID_IS_DESCRIPTION | VT_LPWSTR | Description text of site
PID_IS_COMMENT | VT_LPWSTR | User annotated comment

The following property IDs can be requested for FMTID_InternetSite.

PROPID | Variant Type | Description
PID_INTSITE_WHATSNEW | VT_LPWSTR | What's New text
PID_INTSITE_AUTHOR | VT_LPWSTR | Author
PID_INTSITE_LASTVISIT | VT_FILETIME | Time site was last visited
PID_INTSITE_LASTMOD | VT_FILETIME | Time site was last modified
PID_INTSITE_VISITCOUNT | VT_UI4 | Number of times user has visited
PID_INTSITE_DESCRIPTION | VT_LPWSTR | Description text of site
PID_INTSITE_COMMENT | VT_LPWSTR | User annotated comment
PID_INTSITE_FLAGS | VT_UI4 | Indicates use of PIDISF_ flags (see below)
PID_INTSITE_CONTENTLEN | N/A | Not currently supported
PID_INTSITE_CONTENTCODE | N/A | Not currently supported
PID_INTSITE_RECURSE | N/A | Not currently supported
PID_INTSITE_WATCH | N/A | Not currently supported
PID_INTSITE_SUBSCRIPTION | VT_UI8 | SUBSCRIPTIONCOOKIE value for subscription manager
PID_INTSITE_URL | VT_LPWSTR | URL to which the shortcut leads
PID_INTSITE_TITLE | VT_LPWSTR | Title
PID_INTSITE_CODEPAGE | VT_UI4 | Codepage of the document
PID_INTSITE_TRACKING | N/A | Not currently supported
PID_INTSITE_ICONINDEX | VT_I4 | Index of the icon
PID_INTSITE_ICONFILE | VT_LPWSTR | File that contains the icon

The following are the Internet site flags.

Flag | Description
PIDISF_RECENTLYCHANGED | Indicates that a site was recently changed
PIDISF_CACHEDSTICKY | Not currently supported
PIDISF_CACHEIMAGES | Not currently supported
PIDISF_FOLLOWALLLINKS | Not currently supported

Interfaces

The Internet shortcut object exposes a number of interfaces.

OLE interfaces

  • IDataObject
  • IPersistFile
  • IPersistStream
  • IOleCommandTarget
  • IPropertySetStorage
  • IObjectWithSite

Shell interfaces

  • IContextMenu2
  • IExtractIcon
  • INewShortcutHook
  • IShellExtInit
  • IShellLink
  • IShellPropSheetExt
  • IQueryInfo

Internet shortcut interfaces

  • IUniformResourceLocator

Functions

There are several utility functions that can be used with the Internet shortcut object.

Internet shortcut utility functions

  • InetIsOffline
  • MIMEAssociationDialog
  • TranslateURL
  • URLAssociationDialog


The Taskbar

The Microsoft® Windows® interface includes a special application desktop toolbar called the taskbar. You can use the taskbar for such tasks as switching between open windows and starting new applications. This topic has the following two sections.

  • About the Taskbar
  • Using the Taskbar

About the Taskbar

The taskbar includes the following:

  • Start menu
  • Quick Launch bar
  • Taskbar buttons
  • Status area

The Start menu contains commands that can access programs, documents, and settings. These commands include Programs, Documents, Settings, Find, Help, Run, and Shut Down.

The Quick Launch bar contains shortcuts to applications. Windows provides default entries, such as Internet Explorer, and the user may add any further shortcuts that they choose. A single click on the application's icon in this area launches the application.

The Shell places a button on the taskbar whenever an application creates an unowned window—that is, a window that doesn't have a parent and that has the appropriate extended style bits (see Managing Taskbar Buttons, below). To switch to a window, the user clicks its window button.

Applications can put icons in the status area to indicate the status of an operation or to notify the user about an event. For example, an application might put a printer icon in the status area to show that a print job is under way. The status area is located at the right edge of the taskbar (if the taskbar is horizontal) or at the bottom (if the taskbar is vertical). The status area also displays the current time if the Show clock check box is selected in the taskbar properties.

The user can right-click the taskbar to display the shortcut menu. The shortcut menu includes commands to cascade windows, tile windows, minimize all windows, and set taskbar properties. The shortcut menu also provides the option to add or remove the Quick Launch bar and the Address, Links, and Desktop toolbars from the taskbar. You can add new toolbars to this menu by registering them under the CATID_DeskBand category. For more information, see Implementing Band Objects.

Taskbar Display Options

The taskbar supports two display options: Auto Hide and Always On Top. To set these options, the user must open the taskbar shortcut menu, click Properties, and select or clear the Auto Hide check box or the Always On Top check box. There is no way to set these options programmatically. To retrieve the state of these display options, use the ABM_GETSTATE message. If you would like to be notified when the state of these display options changes, process the ABN_STATECHANGE notification message in your window procedure. To change the state of these display options, use the ABM_SETSTATE message.

The work area is the portion of the screen not obscured by the taskbar. To retrieve the size of the work area, call the SystemParametersInfo function with the SPI_GETWORKAREA value set. To retrieve the rectangle coordinates that describe the location of the taskbar, use the ABM_GETTASKBARPOS message.

It is possible to cover the taskbar by explicitly setting the size of the window rectangle equal to the size of the screen with SetWindowPos. For Microsoft® Windows® 2000 systems or later, the window must lack either WS_CAPTION or WS_THICKFRAME, or else the window must be sized so that the client area covers the entire screen. Also particular to those systems, if the taskbar is set to Always On Top, it will remain hidden only while the application is the foreground application.

Adding Shortcuts to the Start Menu

To add an item to the Programs submenu on Microsoft® Windows NT® 4.0, Windows® 2000 and later, or Windows® 95 and later, follow these steps.

  1. Create a shell link by using the IShellLink interface.
  2. Obtain the PIDL of the Programs folder by using SHGetSpecialFolderLocation, passing CSIDL_PROGRAMS
    3. .
  3. Add the Shell link to the Programs folder. You can also create a folder in the Programs folder and add the link to that folder.

For systems prior to Windows NT 4.0 and Windows 95, use the shell dynamic data exchange interface to add items to the Programs submenu of the Start menu, just as you would use it to add items to a group in Program Manager.

Managing Taskbar Buttons

The Shell creates a button on the taskbar whenever an application creates a window that isn't owned. To ensure that the window button is placed on the taskbar, create an unowned window with the WS_EX_APPWINDOW extended style. To prevent the window button from being placed on the taskbar, create the unowned window with the WS_EX_TOOLWINDOW extended style. As an alternative, you can create a hidden window and make this hidden window the owner of your visible window.

The Shell will remove a window's button from the taskbar only if the window's style supports visible taskbar buttons. If you want to dynamically change a window's style to one that doesn't support visible taskbar buttons, you must hide the window first (by calling ShowWindow with SW_HIDE), change the window style, and then show the window.

The window button typically contains the application icon and title. However, if the application does not contain a system menu, the window button is created without the icon.

If you want your application to get the user's attention when the window is not active, use the FlashWindow function to let the user know that a message is waiting. This function flashes the window button. Once the user clicks the window button to activate the window, your application can display the message.

Modifying the contents of the taskbar

Version 4.71 and later of Shell32.dll adds the capability to modify the contents of the taskbar. From an application, you can now add, remove, and activate taskbar buttons. Activating the item does not activate the window; it shows the item as pressed on the taskbar.

The taskbar modification capabilities are implemented in a COM object (CLSID_TaskbarList) that exposes the ITaskbarList interface (IID_ITaskbarList). You must call the ITaskbarList::HrInit method to initialize the object. You can then use the methods of the ITaskbarList interface to modify the contents of the taskbar.

Adding, Modifying, and Deleting Icons in the Status Area

Use the Shell_NotifyIcon function to add, modify, or delete icons from the status area. The dwMessage parameter of Shell_NotifyIcon is a message to the taskbar that specifies the action to be taken. The pnid parameter is a pointer to a NOTIFYICONDATA structure that is used to identify the icon and pass any additional information that is needed for the system to process the message.

You can perform the following actions with status area icons.

  • To add an icon to the taskbar's status area, call Shell_NotifyIcon with the dwMessage parameter set to NIM_ADD. The NOTIFYICONDATA structure is used to specify the icon's handle and identifier, and any ToolTip text. If the user has selected the Show Clock check box in the taskbar properties, the system places the icon to the immediate left of the clock. Otherwise, the icon appears on the right side or at the bottom of the taskbar. Any existing icons are shifted to the left to make room for the new icon.
  • To modify an icon's information, including its icon handle, ToolTip text, and callback message identifier, call Shell_NotifyIcon with dwMessage set to NIM_MODIFY.
  • To delete an icon from the status area, call Shell_NotifyIcon with the dwMessage parameter set to NIM_DELETE.

When you have completed a user interface operation, return focus to the status area by calling Shell_NotifyIcon with dwMessage set to NIM_SETFOCUS. For example, you could do this when a taskbar icon displays a shortcut menu, but the user cancels it by pressing the ESCAPE key.

Receiving status area callback messages

Applications commonly put icons in the status area of the taskbar to serve as status indicators. You can provide additional information when the user performs mouse actions, such as moving the mouse pointer over the icon or clicking the icon.

The system notifies you of mouse and keyboard events by sending an application-defined callback message that is associated with a particular icon. In this way, the system can notify an application when the user, for instance, clicks the icon or selects it by pressing a key.

You define an icon's callback message when you add the icon to the taskbar. The callback message identifier is specified in the uCallbackMessage member of the NOTIFYICONDATA structure passed with NIM_ADD. When an event occurs, the system sends the callback message to the window procedure of the window specified by the hWnd member. The wParam parameter of the message contains the identifier of the taskbar icon in which the event occurred. The lParam parameter holds the mouse or keyboard message associated with the event. For example, when the mouse pointer moves onto a taskbar icon, lParam contains WM_MOUSEMOVE.

The results of various mouse events can be summarized as follows:

  • When the user moves the mouse pointer over the icon, the system displays the ToolTip text that was specified in NOTIFYICONDATA.
  • When the user clicks the icon, your application receives a WM_LBUTTONDOWN notification.
  • When the user right-clicks the icon, your application receives a WM_RBUTTONDOWN notification.
  • When the user double-clicks the icon, your application receives a WM_LBUTTONDBLCLK notification.

Typically, clicking the icon causes the application to display a window with additional information, right-clicking displays a shortcut menu, and double-clicking executes the default shortcut menu command.

For an example of how to change the ToolTip text associated with a status area icon, see Balloon ToolTips for Status Bar Icons.

Versions 5.0 and later of the Shell handle Shell_NotifyIcon mouse and keyboard events in different ways than earlier Shell versions found on Windows NT 4.0, Windows 95, and Windows 98. The differences are as follows:

  • If a user requests a notify icon's shortcut menu with the keyboard, the version 5.0 Shell sends the associated application a WM_CONTEXTMENU message. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
  • If a user selects a notify icon with the keyboard and activates it with the space bar or ENTER key, the version 5.0 Shell sends the associated application an NIN_KEYSELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
  • If a user selects a notify icon with the mouse and activates it with the ENTER key, the version 5.0 Shell sends the associated application an NIN_SELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
  • If a user passes the mouse pointer over an icon with which a balloon ToolTip is associated, the version 5.0 Shell sends the following messages.
    • NIN_BALLOONSHOW - Sent when the balloon is shown (balloons are queued).
    • NIN_BALLOONHIDE - Sent when the balloon disappears—for example, when the icon is deleted. This message is not sent if the balloon is dismissed because of a timeout or a mouse click.
    • NIN_BALLOONTIMEOUT - Sent when the balloon is dismissed because of a timeout.
    • NIN_BALLOONUSERCLICK - Sent when the balloon is dismissed because of a mouse click.

You can select which way the Shell should behave by calling Shell_NotifyIcon with dwMessage set to NIM_SETVERSION. Set the uVersion member of the NOTIFYICONDATA structure to indicate whether you want version 5.0 or pre-version 5.0 behavior.

Taskbar Creation Notification

With Microsoft® Internet Explorer 4.0 and later, the Shell notifies applications that the taskbar has been created. When the taskbar is created, it registers a message with the TaskbarCreated string and then broadcasts this message to all top-level windows. When your taskbar application receives this message, it should assume that any taskbar icons it added have been removed and add them again. This feature generally applies only to services that are already running when the Shell begins execution. The following example shows a very simplified method for handling this case.

LRESULT CALLBACK WndProc(HWND hWnd, UINT uMessage, WPARAM wParam,
    LPARAM lParam)
{
static UINT s_uTaskbarRestart;

switch(uMessage)
    {
    case WM_CREATE:
        s_uTaskbarRestart = RegisterWindowMessage(TEXT("TaskbarCreated"));
        break;

    default:
        if(uMessage == s_uTaskbarRestart)
            AddTaskbarIcons();
        break;
    }
return DefWindowProc(hWnd, uMessage, wParam, lParam);
}

Using the Taskbar

This section includes examples that demonstrate how to add icons to the taskbar status area and how to process callback messages for taskbar icons.

Adding and Deleting Taskbar Icons in the Status Area

You add an icon to the taskbar status area by filling in a NOTIFYICONDATA structure and then passing the structure to Shell_NotifyIcon with dwMessage set to NIM_ADD. The structure members must specify the handle to the window that is adding the icon, as well as the icon identifier and icon handle. You can also specify ToolTip text for the icon. If you need to receive mouse messages for the icon, specify the identifier of the callback message that the system should use to send the message to the window procedure.

The function in the following example demonstrates how to add an icon to the taskbar.

// MyTaskBarAddIcon - adds an icon to the taskbar status area.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window to receive callback messages.
// uID - identifier of the icon.
// hicon - handle to the icon to add.
// lpszTip - ToolTip text.
BOOL MyTaskBarAddIcon(HWND hwnd, UINT uID, HICON hicon, LPSTR lpszTip)
{
    BOOL res;
    NOTIFYICONDATA tnid;

    tnid.cbSize = sizeof(NOTIFYICONDATA);
    tnid.hWnd = hwnd;
    tnid.uID = uID;
    tnid.uFlags = NIF_MESSAGE | NIF_ICON | NIF_TIP;
    tnid.uCallbackMessage = MYWM_NOTIFYICON;
    tnid.hIcon = hicon;
    if (lpszTip)
        lstrcpyn(tnid.szTip, lpszTip, sizeof(tnid.szTip));
    else
        tnid.szTip[0] = '\0';

    res = Shell_NotifyIcon(NIM_ADD, &tnid);

    if (hicon)
        DestroyIcon(hicon);

    return res;
}

To delete an icon from the taskbar status area, fill a NOTIFYICONDATA structure and call Shell_NotifyIcon with dwMessage set to NIM_DELETE. When deleting a taskbar icon, specify only the cbSize, hWnd, and uID members of the structure. For example

// MyTaskBarDeleteIcon - deletes an icon from the taskbar status area.
// Returns TRUE if successful, or FALSE otherwise.
// hwnd - handle to the window that added the icon.
// uID - identifier of the icon to delete.
BOOL MyTaskBarDeleteIcon(HWND hwnd, UINT uID)
{
    BOOL res;
    NOTIFYICONDATA tnid;

    tnid.cbSize = sizeof(NOTIFYICONDATA);
    tnid.hWnd = hwnd;
    tnid.uID = uID;

    res = Shell_NotifyIcon(NIM_DELETE, &tnid);
    return res;
}

Receiving Mouse Events

If you specify a callback message for a taskbar icon, the system sends the message to your application whenever a mouse event occurs in the icon's bounding rectangle. The wParam parameter of the message specifies the identifier of the taskbar icon, and the lParam parameter of the message specifies the message that the system generated as a result of the mouse event.

The function in the following example is from an application that adds both battery and printer icons to the taskbar. The application calls the function when it receives a callback message. The function determines whether the user has clicked one of the icons and, if a click has occurred, calls an application-defined function to display status information.

// On_MYWM_NOTIFYICON - processes callback messages for taskbar icons.
// wParam - first message parameter of the callback message.
// lParam - second message parameter of the callback message.
void On_MYWM_NOTIFYICON(WPARAM wParam, LPARAM lParam)
{
    UINT uID;
    UINT uMouseMsg;

    uID = (UINT) wParam;
    uMouseMsg = (UINT) lParam;

    if (uMouseMsg == WM_LBUTTONDOWN) {
        switch (uID) {
            case IDI_MYBATTERYICON:

                // The user clicked the battery icon. Display the
                // battery status.
                ShowBatteryStatus();
                break;

            case IDI_MYPRINTERICON:

                // The user clicked the printer icon. Display the
                // status of the print job.
                ShowJobStatus();
                break;

            default:
                break;
        }
     }
     return;
 }


Using Application Desktop Toolbars

An application desktop toolbar (also called an appbar) is a window that is similar to the Microsoft® Windows® taskbar. It is anchored to an edge of the screen, and it typically contains buttons that give the user quick access to other applications and windows. The system prevents other applications from using the desktop area occupied by an appbar. Any number of appbars can exist on the desktop at any given time.

This topic contains the following sections.

  • About Application Desktop Toolbars
  • Using Application Desktop Toolbars

About Application Desktop Toolbars

Windows provides an application programming interface (API) that lets you take advantage of appbar services provided by the system. The services help ensure that application-defined appbars operate smoothly with one another and with the taskbar. The system maintains information about each appbar and sends the appbars messages to notify them about events that can affect their size, position, and appearance.

Sending Messages

An application uses a special set of messages, called appbar messages, to add or remove an appbar, set an appbar's size and position, and retrieve information about the size, position, and state of the taskbar. To send an appbar message, an application must use the SHAppBarMessage function. The function's parameters include a message identifier, such as ABM_NEW, and the address of an APPBARDATA structure. The structure members contain information that the system needs to process the given message.

For any given appbar message, the system uses some members of the APPBARDATA structure and ignores the others. However, the system always uses the cbSize and hWnd members, so an application must fill these members for every appbar message. The cbSize member specifies the size of the structure, and the hWnd member is the handle to the appbar's window.

Some appbar messages request information from the system. When processing these messages, the system copies the requested information into the APPBARDATA structure.

Registration

The system keeps an internal list of appbars and maintains information about each bar in the list. The system uses the information to manage appbars, perform services for them, and send them notification messages.

An application must register an appbar (that is, add it to the internal list) before it can receive appbar services from the system. To register an appbar, an application sends the ABM_NEW message. The accompanying APPBARDATA structure includes the handle to the appbar's window and an application-defined message identifier. The system uses the message identifier to send notification messages to the window procedure of the appbar window. For more information about appbar notification messages, see Appbar Notification Messages.

An application unregisters an appbar by sending the ABM_REMOVE message. Unregistering an appbar removes it from the system's internal list of appbars. The system no longer sends notification messages to the appbar or prevents other applications from using the screen area occupied by the appbar. An application should always send ABM_REMOVE before destroying an appbar.

Appbar Size and Position

An application should set an appbar's size and position so that it does not interfere with any other appbars or the taskbar. Every appbar must be anchored to a particular edge of the screen, and multiple appbars can be anchored to an edge. However, if an appbar is anchored to the same edge as the taskbar, the system ensures that the taskbar is always on the outermost edge.

To set the size and position of an appbar, an application first proposes a screen edge and bounding rectangle for the appbar by sending the ABM_QUERYPOS message. The system determines whether any part of the screen area within the proposed rectangle is occupied by the taskbar or another appbar, adjusts the rectangle (if necessary), and returns the adjusted rectangle to the application.

Next, the application sends the ABM_SETPOS message to set the new bounding rectangle for the appbar. Again, the system may adjust the rectangle before returning it to the application. For this reason, the application should use the adjusted rectangle returned by ABM_SETPOS to set the final size and position. The application can use the MoveWindow function to move the appbar into position.

By using a two-step process to set the size and position, the system enables the application to provide intermediate feedback to the user during the move operation. For example, if the user drags an appbar, the application might display a shaded rectangle indicating the new position before the appbar actually moves.

An application should set the size and position of its appbar after registering it and whenever the appbar receives the ABN_POSCHANGED notification message. An appbar receives this notification message whenever a change occurs in the taskbar's size, position, or visibility state and whenever another appbar on the same side of the screen is resized, added, or removed.

Whenever an appbar receives the WM_ACTIVATE message, it should send the ABM_ACTIVATE message. Similarly, when an appbar receives a WM_WINDOWPOSCHANGED message, it must call ABM_WINDOWPOSCHANGED. Sending these messages ensures that the system properly sets the z-order of any autohide appbars on the same edge.

Autohide Application Desktop Toolbars

An autohide appbar is one that is normally hidden but becomes visible when the user moves the mouse cursor to the screen edge with which the appbar is associated. The appbar hides itself again when the user moves the mouse cursor out of the bar's bounding rectangle.

Although the system allows a number of different appbars at any given time, it allows only one autohide appbar at a time for each screen edge on a first-come, first-served basis. The system automatically maintains the z-order of an autohide appbar (within its z-order group only).

An application uses the ABM_SETAUTOHIDEBAR message to register or unregister an autohide appbar. The message specifies the edge for the appbar and a flag that specifies whether the appbar is to be registered or unregistered. The message fails if an autohide appbar is being registered but one is already associated with the specified edge. An application can retrieve the handle to the autohide appbar associated with an edge by sending the ABM_GETAUTOHIDEBAR message.

An autohide appbar does not need to register as a normal appbar; that is, it does not need to be registered by sending the ABM_NEW message. An appbar that is not registered by ABM_NEW overlaps any appbars anchored on the same edge of the screen.

Appbar Notification Messages

The system sends messages to notify an appbar about events that can affect its position and appearance. The messages are sent in the context of an application-defined message. The application specifies the identifier of the message when it sends the ABM_NEW message to register the appbar. The notification code is in the wParam parameter of the application-defined message.

An appbar receives the ABN_POSCHANGED notification message when the taskbar's size, position, or visibility state changes, when another appbar is added to the same edge of the screen, or when another appbar on the same edge of the screen is resized or removed. An appbar should respond to this notification message by sending ABM_QUERYPOS and ABM_SETPOS messages. If an appbar's position has changed, it should call the MoveWindow function to move itself to the new position.

The system sends the ABN_STATECHANGE notification message whenever the taskbar's autohide or always-on-top state has changed—that is, when the user selects or clears the Always on top or Auto hide check box on the taskbar's property sheet. An appbar can use this notification message to set its state to conform to that of the taskbar, if desired.

When a full-screen application is started or when the last full-screen application is closed, an appbar receives the ABN_FULLSCREENAPP notification message. The lParam parameter indicates whether the full-screen application is opening or closing. If it is opening, the appbar must drop to the bottom of the z-order. The appbar should restore its z-order position when the last full-screen application has closed.

An appbar receives the ABN_WINDOWARRANGE notification message when the user selects the Cascade, Tile Horizontally, or Tile Vertically command from the taskbar's shortcut menu. The system sends the message two times—before rearranging the windows (lParam is TRUE) and after arranging the windows (lParam is FALSE).

An appbar can use ABN_WINDOWARRANGE messages to exclude itself from the cascade or tile operation. To exclude itself, the appbar should hide itself when lParam is TRUE and show itself when lParam is FALSE. If an appbar hides itself in response to this message, it does not need to send the ABM_QUERYPOS and ABM_SETPOS messages in response to the cascade or tile operation.

Using Application Desktop Toolbars

This section includes examples that demonstrate how to perform the following tasks.

  • Registering an Application Desktop Toolbar (appbar)
  • Setting the Appbar Size and Position
  • Processing Appbar Notification Messages

Registering an Application Desktop Toolbar

An application must register an appbar by sending the ABM_NEW message. Registering an appbar adds it to the system's internal list and provides the system with a message identifier to use to send notification messages to the appbar. Before exiting, an application must unregister the appbar by sending the ABM_REMOVE message. Unregistering removes the appbar from the system's internal list and prevents the bar from receiving appbar notification messages.

The function in the following example either registers or unregisters an appbar, depending on the value of a Boolean flag parameter.

// RegisterAccessBar - registers or unregisters an appbar.
// Returns TRUE if successful, or FALSE otherwise.
// hwndAccessBar - handle to the appbar
// fRegister - register and unregister flag
//
// Global variables
//     g_uSide - screen edge (defaults to ABE_TOP)
//     g_fAppRegistered - flag indicating whether the bar is registered
BOOL RegisterAccessBar(HWND hwndAccessBar, BOOL fRegister)
{
    APPBARDATA abd;

    // Specify the structure size and handle to the appbar.
    abd.cbSize = sizeof(APPBARDATA);
    abd.hWnd = hwndAccessBar;

    if (fRegister) {

        // Provide an identifier for notification messages.
        abd.uCallbackMessage = APPBAR_CALLBACK;

        // Register the appbar.
        if (!SHAppBarMessage(ABM_NEW, &abd))
            return FALSE;
        g_uSide = ABE_TOP;       // default edge
        g_fAppRegistered = TRUE;
    } else {

        // Unregister the appbar.
        SHAppBarMessage(ABM_REMOVE, &abd);
        g_fAppRegistered = FALSE;
    }
    return TRUE;
}

Setting the Appbar Size and Position

An application should set an appbar's size and position after registering the appbar, after the user user moves or sizes the appbar, and whenever the appbar receives the ABN_POSCHANGED notification message. Before setting the size and position of the appbar, the application queries the system for an approved bounding rectangle by sending the ABM_QUERYPOS message. The system returns a bounding rectangle that does not interfere with the taskbar or any other appbar. The system adjusts the rectangle purely by rectangle subtraction; it makes no effort to preserve the rectangle's initial size. For this reason, the appbar should readjust the rectangle, as necessary, after sending ABM_QUERYPOS.

Next, the application passes the bounding rectangle back to the system by using the ABM_SETPOS message. Then it calls the MoveWindow function to move the appbar into position.

The following example shows how to set an appbar's size and position.

// AppBarQuerySetPos - sets the size and position of an appbar.
// uEdge - screen edge to which the appbar is to be anchored
// lprc - current bounding rectangle of the appbar
// pabd - address of the APPBARDATA structure with the hWnd and
//     cbSize members filled
void PASCAL AppBarQuerySetPos(UINT uEdge, LPRECT lprc, PAPPBARDATA pabd)
{
    int iHeight = 0;
    int iWidth = 0;

    pabd->rc = *lprc;
    pabd->uEdge = uEdge;

    // Copy the screen coordinates of the appbar's bounding
    // rectangle into the APPBARDATA structure.
    if ((uEdge == ABE_LEFT) ||
            (uEdge == ABE_RIGHT)) {
        iWidth = pabd->rc.right - pabd->rc.left;
        pabd->rc.top = 0;
        pabd->rc.bottom = GetSystemMetrics(SM_CYSCREEN);
    } else {
        iHeight = pabd->rc.bottom - pabd->rc.top;
        pabd->rc.left = 0;
        pabd->rc.right = GetSystemMetrics(SM_CXSCREEN);
    }

    // Query the system for an approved size and position.
    SHAppBarMessage(ABM_QUERYPOS, pabd);

    // Adjust the rectangle, depending on the edge to which the
    // appbar is anchored.
    switch (uEdge) {
        case ABE_LEFT:
            pabd->rc.right = pabd->rc.left + iWidth;
            break;

        case ABE_RIGHT:
            pabd->rc.left = pabd->rc.right - iWidth;
            break;

        case ABE_TOP:
            pabd->rc.bottom = pabd->rc.top + iHeight;
            break;

        case ABE_BOTTOM:
            pabd->rc.top = pabd->rc.bottom - iHeight;
            break;
    }

    // Pass the final bounding rectangle to the system.
    SHAppBarMessage(ABM_SETPOS, pabd);

    // Move and size the appbar so that it conforms to the
    // bounding rectangle passed to the system.
    MoveWindow(pabd->hWnd, pabd->rc.left, pabd->rc.top,
        pabd->rc.right - pabd->rc.left,
        pabd->rc.bottom - pabd->rc.top, TRUE);
}

Processing Appbar Notification Messages

An appbar receives a notification message when the state of the taskbar changes, when a full-screen application starts (or the last one closes), or when an event occurs that can affect the appbar's size and position. The following example shows how to process the various notification messages.

// AppBarCallback - processes notification messages sent by the system.
// hwndAccessBar - handle to the appbar
// uNotifyMsg - identifier of the notification message
// lParam - message parameter
void AppBarCallback(HWND hwndAccessBar, UINT uNotifyMsg,
    LPARAM lParam)
{
    APPBARDATA abd;
    UINT uState;

    abd.cbSize = sizeof(abd);
    abd.hWnd = hwndAccessBar;

    switch (uNotifyMsg) {
        case ABN_STATECHANGE:

            // Check to see if the taskbar's always-on-top state has
            // changed and, if it has, change the appbar's state
            // accordingly.
            uState = SHAppBarMessage(ABM_GETSTATE, &abd);
            SetWindowPos(hwndAccessBar,
                (ABS_ALWAYSONTOP & uState) ? HWND_TOPMOST : HWND_BOTTOM,
                0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);
            break;

        case ABN_FULLSCREENAPP:

            // A full-screen application has started, or the last full-
            // screen application has closed. Set the appbar's
            // z-order appropriately.
            if (lParam) {
                SetWindowPos(hwndAccessBar,
                    (ABS_ALWAYSONTOP & uState) ?
                                            HWND_TOPMOST : HWND_BOTTOM,
                    0, 0, 0, 0,
                    SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);
            } else {
                uState = SHAppBarMessage(ABM_GETSTATE, &abd);
                if (uState & ABS_ALWAYSONTOP)
                    SetWindowPos(hwndAccessBar, HWND_TOPMOST,
                        0, 0, 0, 0,
                        SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE);
        }

        case ABN_POSCHANGED:

            // The taskbar or another appbar has changed its
            // size or position.
            AppBarPosChanged(&abd);
            break;
    }
}

The following function adjusts an appbar's bounding rectangle and then calls the application-defined AppBarQuerySetPos function (included in the previous section) to set the bar's size and position accordingly.

// AppBarPosChanged - adjusts the appbar's size and position.
// pabd - address of an APPBARDATA structure that contains information
//     used to adjust the size and position
void PASCAL AppBarPosChanged(PAPPBARDATA pabd)
{
    RECT rc;
    RECT rcWindow;
    int iHeight;
    int iWidth;

    rc.top = 0;
    rc.left = 0;
    rc.right = GetSystemMetrics(SM_CXSCREEN);
    rc.bottom = GetSystemMetrics(SM_CYSCREEN);

    GetWindowRect(pabd->hWnd, &rcWindow);
    iHeight = rcWindow.bottom - rcWindow.top;
    iWidth = rcWindow.right - rcWindow.left;

    switch (g_uSide) {
        case ABE_TOP:
            rc.bottom = rc.top + iHeight;
            break;

        case ABE_BOTTOM:
            rc.top = rc.bottom - iHeight;
            break;

        case ABE_LEFT:
            rc.right = rc.left + iWidth;
            break;

        case ABE_RIGHT:
            rc.left = rc.right - iWidth;
            break;
        }
        AppBarQuerySetPos(g_uSide, &rc, pabd);
    }


Using Autocomplete

The IAutoComplete interface is exposed by the autocomplete object (CLSID_AutoComplete). It allows applications to initialize, enable, and disable the object.

Autocompletion expands strings that have been partially entered in an edit control into complete strings. For example, when a user starts to enter a URL in the Address edit control that is embedded in the Microsoft® Internet Explorer toolbar, autocompletion expands the string into one or more complete URL options that are consistent with the existing partial string. A partial URL string such as "mic" might be expanded to "http://www.microsoft.com" or "http://www.microsoft.com/windows". Autocompletion is typically used with edit controls or with controls that have an embedded edit control, such as the ComboBoxEx control.

  • Enabling Autocomplete with SHAutoComplete
  • Enabling Autocomplete Manually
  • Autocomplete Modes
  • Finer Control of CLSID_ACListISF

Enabling Autocomplete with SHAutoComplete

The SHAutoComplete function provides autocomplete functionality for an application to attach to an edit control. SHAutoComplete is a very simple function that can autocomplete a file path or URL.

Enabling Autocomplete Manually

If you want more detailed control over the autocomplete behavior, or if you want to add a custom source of autocompleted strings, you must manage the autocomplete object yourself.

Creating a Simple Autocomplete Object

The following steps show how to create and initialize a simple autocomplete object. A simple autocomplete object completes strings from a single source. Error checking has been intentionally omitted in this example.

  1. Create the autocomplete object.
    IAutoComplete *pac;
    CoCreateInstance(CLSID_AutoComplete, NULL, CLSCTX_INPROC_SERVER,
                     IID_IAutoComplete, (LPVOID*)&pac);
  2. Create the autocomplete source.

    You can use a predefined autocomplete source, or you can write your own custom autocomplete source.

    Using a predefined autocomplete source:

    IUnknown *punkSource;
    CoCreateInstance(clsidSource, NULL, CLSCTX_INPROC_SERVER,
                     IID_IACList, (LPVOID*)&punkSource);

    The following autocomplete sources are provided by the system.

    • CLSID_ACLHistory: An autocomplete source that matches against the URL list in the user's History list.
    • CLSID_ACLMRU: An autocomplete source that matches against the URL list in the user's Recently Used list.
    • CLSID_ACListISF: An autocomplete source that matches against items in the Shell namespace, including files on the user's computer as well as items in virtual folders such as My Computer and Control Panel.

    Using a custom autocomplete source:

    IUnknown *punkSource;
    CCustomAutoCompleteSource *pcacs = new CCustomAutoCompleteSource();
    hr = pcacs->QueryInterface(IID_IUnknown, (void **) &punkSource);
    pcacs->Release();

    You can write your own autocomplete source object by implementing an object that exposes the IEnumString interface. Implementing the IACList and IACList2 interfaces is optional.

  3. Set the options on the autocomplete source.

    If you want, you can customize the behavior of the autocomplete source by setting its options. This is particularly useful for the CLSID_ACListISF autocomplete source. For a list of valid options, see the documentation for IACList2::SetOptions.

    IACList2 *pal2;
    if (SUCCEEDED(punkSource->QueryInterface(IID_IACList2, (LPVOID*)&pal2)))
    {
        pal2->SetOptions(ACLO_FILESYSONLY);
        pal2->Release();
    }
  4. Initialize the autocomplete object.

    In this example, hwndEdit is the edit control for which autocomplete is to be enabled, and punkSource is the IUnknown interface pointer created in step 2. For a description of the optional pwszRegKeyPath and pwszQuickComplete parameters, see the documentation for IAutoComplete::Init.

    pac->Init(hwndEdit, punkSource, NULL, NULL);
  5. Set the options of the autocomplete object.

    If you want, you can customize the behavior of the autocomplete object by setting its options. For a description of the possible options, see the documentation for IACList2::SetOptions.

    IAutoComplete2 *pac2;
    if (SUCCEEDED(pac->QueryInterface(IID_IAutoComplete2, (LPVOID*)&pac2)))
    {
        pac2->SetOptions(ACO_AUTOSUGGEST);
        pac2->Release();
    }
  6. Release the objects.
    pac->Release();
    punkSource->Release();

    The autocomplete object will remain attached to the edit control even after you release it. You might not want to release these interfaces if you need to access them later. For example, you might want to change the autocomplete options at a later point.

Creating a Compound Autocomplete Object

A compound autocomplete object completes strings from multiple sources. For example, the Internet Explorer Address bar uses a compound autocomplete object because the user might type the name of a file in the current folder, or the user might begin typing a URL. The following steps show how to create and initialize a compound autocomplete object:

  1. Create the autocomplete object.
    IAutoComplete *pac;
    CoCreateInstance(CLSID_AutoComplete, NULL, CLSCTX_INPROC_SERVER,
                     IID_IAutoComplete, (LPVOID*)&pac);
  2. Create the autocomplete compound source object manager.

    The autocomplete compound source allows multiple autocomplete sources to be combined into a single autocomplete source.

    IObjMgr *pom;
    CoCreateInstance(CLSID_ACLMulti, NULL, CLSCTX_INPROC_SERVER,
                     IID_IObjMgr, (LPVOID*)&pom);
  3. Create and initialize each of the autocomplete sources you want to use.

    Repeat steps 2 and 3 from the Simple Autocomplete Object example as many times as necessary.

  4. Attach each autocomplete source to the object manager.

    For each autocomplete source you created in step 3, attach it to the object manager.

    pom->Append(punkSource);
  5. Initialize the autocomplete object.

    This is the same as step 4 of the Simple Autocomplete Object example, except that instead of passing the simple autocomplete source to IAutoComplete::Init, you pass the compound source object manager.

    pac->Init(hwndEdit, pom, NULL, NULL);
  6. Set the options of the autocomplete object.

    Same as in the simple case.

  7. Release the objects.
    pac->Release();
    pom->Release();
    punkSource->Release(); // repeat for each source you created in step 3

    As in the simple case, you can release the objects as soon as you are finished using them, but you might want to retain the interfaces so you can change options later.

Autocomplete Modes

Autocompletion has two modes for displaying the completed string: autoappend and autosuggest. The modes are independent, so you can enable either or both. To specify the mode, call IAutoComplete2::SetOptions.

  • Autoappend: In autoappend mode, autocompletion appends the remainder of the most likely candidate string to the existing characters, highlighting the appended characters. The edit control behaves as if the user had entered the entire string manually and then highlighted the appended characters. If the user continues to enter characters, they are added to the existing partial string. If the user adds a character that is identical to the next highlighted character, the highlighting for that character is turned off. The remaining characters will still be highlighted. If the user adds a character that does not match the next highlighted character, autocompletion attempts to generate a new candidate string based on the larger partial string. It appends the remainder of the new candidate string to the current partial string, as before. If no candidate string can be found, only the typed characters appear and the edit box behaves as it would without autocompletion. This process continues until the user accepts a string.
  • Autosuggest: In autosuggest mode, autocompletion displays a drop-down list, with one or more suggested complete strings, beneath the edit control. The user can select one of the suggested strings, usually by clicking it with the mouse, or continue typing. As typing progresses, the drop-down list might be modified, based on the current partial string. If you set the ACO_SEARCH flag in the dwFlag parameter of IAutoComplete2::SetOptions, autocomplete provides the option to search for the current partial string at the bottom of the drop-down list. It will be displayed even if there are no suggested strings. If the user selects this option, your application should launch a search engine to assist the user.

Finer Control of CLSID_ACListISF

One reason you might want to retain the interface pointers to the various objects involved in autocomplete is if you want to adjust the behavior dynamically. The most common example of this is with the CLSID_ACListISF object, which autocompletes from the Shell namespace and has the option (ACLO_CURRENTDIR) of enumerating from the current directory as well.

An example of a situation where the settings need to be changed dynamically is when Internet Explorer changes the Address bar's current directory whenever you navigate to a new folder.

There are two ways to specify the directory that the CLSID_ACListISF object should treat as current. Aside from the way the directory is passed, they are equivalent.

In the following, assume that palISF is a pointer to the IACList interface of a CLSID_ACListISF object:

  • Using IPersistFolder:

    To tell the CLSID_ACListISF object that a particular ITEMIDLIST should be treated as the current directory, you can use the object's IPersistFolder interface. Since an ITEMIDLIST can refer to a virtual folder, this method is more flexible than using ICurrentWorkingDirectory.

    IPersistFolder *ppf;
    if (SUCCEEDED(pal->QueryInterface(IID_IPersistFolder, (LPVOID*)&ppf)))
    {
        ppf->Initialize(pidlCurrentDirectory);
        ppf->Release();
    }
  • Using ICurrentWorkingDirectory:

    To give the CLSID_ACListISF object a path as the current directory, you can use the object's ICurrentWorkingDirectory interface.

    ICurrentWorkingDirectory *pcwd;
    if (SUCCEEDED(pal->QueryInterface(IID_ICurrentWorkingDirectory, (LPVOID*)&pcwd)))
    {
        pcwd->SetDirectory(pwszDirectory);
        pcwd->Release();
    }


Intermediate Shell Techniques: Extending the Shell

The majority of this section discusses how you can extend the Shell's basic capabilities by writing various Shell extension handlers. These handlers are called by the Shell and allow you to dynamically modify the Shell's behavior when it takes an action such as displaying a file's shortcut menu. A disk cleanup handler allows applications to integrate their cleanup activities with the standard Shell cleanup utility. The final section discusses how to customize the way the contents of a folder are displayed by Microsoft® Windows® Explorer.

  • Creating Shell Extension Handlers
  • Creating a Disk Cleanup Handler
  • Customizing a Folder's Web View

Note To improve the readability of the sample code in the Intermediate Shell Techniques documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values and data are in a normal font.


Creating Shell Extension Handlers

The Shell Basics section discusses how to extend the capabilities of the Shell with registry entries and .ini files. While this approach to extending the Shell is simple, and adequate for many purposes, it is limited. For example, if you use the registry to specify a custom icon for a file class, the same icon will appear for every file in that class. Extending the Shell with the registry does not allow you to vary the icon for different members of the class. Other aspects of the Shell, such as the Properties property sheet that can be displayed when a file is right-clicked, cannot be modified at all with the registry.

A more powerful and flexible approach to extending the Shell is to implement shell extension handlers. These handlers can be implemented for a variety of actions that the Shell can take. Before taking the action, the Shell queries the extension handler, giving it the opportunity to modify the action. A common example is a shortcut menu extension handler. If one is implemented for a file class, it will be queried every time one of the files is right-clicked. The handler can then specify additional menu items on a file-by-file basis, rather than having the same set for the entire file class.

This document discusses how to implement the extension handlers that allow you to modify a variety of Shell actions. The following handlers are associated with a particular file class and allow you to specify on a file-by-file basis.

Handler | Description
Shortcut menu handler | Called before a file's shortcut menu is displayed. It allows you to add items to the shortcut menu on a file-by-file basis.
Data handler | Called when Shell objects are dragged and dropped. It allows you to provide additional clipboard formats to the drop target.
Drop handler | Called when a data object is dragged over or dropped on a file. It allows you to make a file into a drop target.
Icon handler | Called before a file's icon is displayed. It allows you to replace the file's default icon with a custom icon on a file-by-file basis.
Property sheet handler | Called before an object's Properties property sheet is displayed. It allows you to add or replace pages.
Thumbnail Image Handler | Provides an image to be displayed when the user selects the Thumbnail view.
Infotip handler | Provides pop-up text when the user hovers the mouse pointer over the object.

Others are not associated with a particular file class but are called before some Shell operations.

Handler | Description
Column handler | Called by Microsoft® Windows® Explorer before it displays the Details view of a folder. It allows you to add custom columns to the Details view.
Copy hook handler | Called when a folder or printer object is about to be moved, copied, deleted, or renamed. It allows you to approve or veto the operation.
Drag-and-drop handler | Called when a file is dragged with the right mouse button. It allows you to modify the shortcut menu that is displayed.
Icon Overlay Handler | Called before a file's icon is displayed. It allows you to specify an overlay for the file's icon.
Search handler | Called to launch a search engine. It allows you to implement a custom search engine accessible from the Start menu or Windows Explorer.

The details of how to implement specific extension handlers are covered in the sections listed above. The remainder of this document covers some implementation issues that are common to all Shell extension handlers.

  • Implementing Shell Extension Handlers
  • Registering Shell Extension Handlers

Implementing Shell Extension Handlers

Much of the implementation of a Shell extension handler object is dictated by its type. There are, however, some common elements. This section discusses those aspects of implementation that are shared by all Shell extension handlers.

All Shell extension handlers are in-process COM objects. They must be assigned a GUID and registered as described in Registering Shell Extension Handlers. They are implemented as DLLs and must export the following standard functions:

  • DllMain. The standard entry point to the DLL.
  • DllGetClassObject. Exposes the object's class factory
  • DllCanUnloadNow. COM calls this function to determine whether the object is serving any clients. If not, the system can unload the DLL and free the associated memory.

Like all COM objects, Shell extension handlers must implement an IUnknown interface and a class factory. Most must also implement either an IPersistFile or IShellExtInit interface. The Shell uses these interfaces to initialize the handler.

The IPersistFile interface must be implemented by:

  • Icon handlers.
  • Data handlers.
  • Drop handlers.

The IShellExtInit interface must be implemented by:

  • Shortcut menu handlers.
  • Drag and drop handlers.
  • Property sheet handlers.

Implementing IPersistFile

The IPersistFile interface is intended to permit an object to be loaded from or saved to a disk file. It has six methods in addition to IUnknown, five of its own, and the GetClassID method that it inherits from IPersist. With Shell extensions, IPersist is used only to initialize a Shell extension handler object. Because there is typically no need to read from or write to the disk, only the GetClassID and Load methods require a nontoken implementation.

The Shell calls GetClassID first, and the function returns the CLSID of the extension handler object. The Shell then calls Load and passes in two values. The first, pOleStr, is a Unicode string with the name of the file or folder that Shell is about to operate on. The second is dwFlags, which indicates the file access mode. Because there is normally no need to access files, dwFlags is typically zero. The method stores these values as needed for future reference.

The following code fragment illustrates how a typical Shell extension handler implements the GetClassID and Load methods. It is designed to handle either ANSI or Unicode. CLSID_SampleExtHandler is the extension handler object's GUID, and CSampleExtHandler is the name of the class used to implement the interface. The m_szFileName and m_dwMode variables are private variables that are used to store the file's name and access flags.

TCHAR m_szFileName[MAX_PATH]; //The file name
DWORD m_dwMode; //The file access mode

CSampleExtHandler::GetClassID(CLSID *pCLSID)
{
    *pCLSID = CLSID_SampleExtHandler;
}

CSampleExtHandler::Load(LPCOLESTR pOleStr, DWORD dwMode)
{
#ifdef UNICODE //If the handler is Unicode, copy the string
    lstrcpyn(m_szFileName, (LPWSTR) pOleStr, ARRAYSIZE(m_szFileName));

#else //If the handler is ANSI, first convert the string to ANSI
    WideCharToMultiByte(CP_ACP,
                        0,
                        pWide,
                        -1,
                        m_szFileName,
                        ARRAYSIZE(m_szFileName),
                        NULL,
                        NULL);
#endif

    m_dwMode = dwMode;

    return S_OK;
}

Implementing IShellExtInit

The IShellExtInit interface has only one method, IShellExtInit::Initialize, in addition to IUknown. The method has three parameters that the Shell can use to pass in various types of information. The values passed in depend on the type of handler, and some can be set to NULL:

  • pIDFolder holds a folder's PIDL. For property sheet extensions, it is NULL. For shortcut menu extensions, it is the PIDL of the folder that contains the item whose shortcut menu is being displayed. For nondefault drag-and-drop handlers, it is the PIDL of the target folder.
  • pDataObject holds a pointer to a data object's IDataObject interface. The data object holds one or more file names in CF_HDROP format.
  • hRegKey holds a registry key for the file object or folder type.

The IShellExtInit::Initialize method stores the file name, IDataObject pointer, and registry key as needed for future use. The following code fragment illustrates an implementation of IShellExtInit::Initialize. For simplicity, this example assumes that the data object contains only a single file. In general, it might contain multiple files that will each need to be extracted.

LPCITEMIDLIST m_pIDFolder; //The folder's PIDL.
TCHAR m_szFileName[MAX_PATH]; //The file name.
IDataObject *m_pDataObject; //The IDataObject pointer.
HKEY m_hRegKey; //The file or folder's registry key.

STDMETHODIMP CShellExt::Initialize(LPCITEMIDLIST pIDFolder,
                                       IDataObject *pDataObj,
                                       HKEY hRegKey)
{
    //Store the PIDL.
    if(pIDFolder)
    {
        m_pIDFolder = pIDFolder;
    }

    // If Initialize has already been called, release the old
    // IDataObject pointer.
    if (m_pDataObj)
    {
        m_pDataObj->Release();
    }

    // If a data object pointer was passed in, save it and
    // extract the file name.
    if (pDataObj)
    {
        m_pDataObj = pDataObj;
        pDataObj->AddRef();

        STGMEDIUM   medium;
        FORMATETC   fe = {CF_HDROP, NULL, DVASPECT_CONTENT, -1,
                          TYMED_HGLOBAL};
        UINT        uCount;

        if(SUCCEEDED(m_pDataObj->GetData(&fe, &medium)))
        {
        // Get the file name from the CF_HDROP.
            uCount = DragQueryFile((HDROP)medium.hGlobal, (UINT)-1,
                                    NULL, 0);
            if(uCount)
                DragQueryFile((HDROP)medium.hGlobal, 0, m_szFile,
                              sizeof(m_szFile));

            ReleaseStgMedium(&medium);
        }
    }

    // Duplicate the registry handle.
    if (hRegKey)
        RegOpenKeyEx(   hRegKey,
                        NULL,
                        0L,
                        MAXIMUM_ALLOWED,
                        &m_hRegKey);
    return S_OK;
}

CSampleExtHandler is the name of the class used to implement the interface. The m_pIDFolder, m_pDataObject, m_szFileName, and m_hRegKey variables are private variables used to store the information that is passed in. For simplicity, this example assumes that only one file name will be held by the data object. After the FORMATETC structure is retrieved from the data object, DragQueryFile is used to extract the file name from the FORMATETC structure's medium.hGlobal member. If a registry key is passed in, the method uses RegOpenKeyEx to open the key and assigns the handle to m_hRegKey.

Infotip Customization

There are two ways to customize infotips. One way is to implement an object that supports IQueryInfo and then register the object under the proper subkey in the registry (see below). Alternatively, you can specify either a fixed string or a list of certain file properties to be displayed.

To display a fixed string for a namespace extension, create a subkey called InfoTip beneath the CLSID key of your namespace extension. Set the data of that subkey to be the string you wish to be displayed.

HKEY_CLASSES_ROOT
   CLSID
      {CLSID}
         InfoTip="InfoTip string for your namespace extension"

To display a fixed string for a file type, create a subkey called InfoTip beneath the ProgId key of the file type you wish to supply infotips for. Set the data of that subkey to be the string you wish to be displayed.

HKEY_CLASSES_ROOT
   ProgId
      InfoTip="InfoTip string for all files of this type"

If you want the Shell to show certain file properties in the infotip for a specific file type, create a subkey called InfoTip beneath the ProgId key of that file type. Set the data of that subkey to be a semicolon-delineated list of canonical property names or {fmtid}, pid pairs

HKEY_CLASSES_ROOT
   ProgId
      InfoTip="propname;propname;{fmtid},pid;{fmtid},pid"

where propname is a canonical property name and {fmtid},pid is a FMTID/PID pair.

The following property names can be used.

Property Name | Description | Retrieved From
Author | Author of the document | OLE document properties (PIDSI_AUTHOR)
Title | Title of the document | OLE document properties (PIDSI_TITLE)
Subject | Subject summary | OLE document properties (PIDSI_SUBJECT)
Comment | Document comments | OLE document properties (PIDSI_COMMENT) or folder/drive properties
PageCount | Number of pages | OLE document properties (PIDSI_PAGECOUNT)
Name | Friendly name | Standard folder view
OriginalLocation | Location of original file | Briefcase folder and Recycle Bin folder
DateDeleted | Date file was deleted | Recycle Bin folder
Type | Type of file | Standard folder details view
Size | Size of file | Standard folder details view
SyncCopyIn | Same as OriginalLocation | Same as OriginalLocation
Modified | Date last modified | Standard folder details view
Created | Date created | Standard folder details view
Accessed | Date last accessed | Standard folder details view
InFolder | Directory containing the file | Document search results
Rank | Quality of search match | Document search results
FreeSpace | Available storage space | Disk drives
NumberOfVisits | Number of visits | Favorites folder
Attributes | File Attributes | Standard folder details view
Company | Company name | OLE document properties (PIDDSI_COMPANY)
Category | Document category | OLE document properties (PIDDSI_CATEGORY)
Copyright | Media copyright | OLE document properties (PIDMSI_COPYRIGHT)
HTMLInfoTipFile | HTML InfoTip file | Desktop.ini file for folder

Registering Shell Extension Handlers

A Shell extension handler object must be registered before the Shell can use it. This section is a general discussion of how to register a Shell extension handler.

Any time you create or change a Shell extension handler, it is important to notify the system that you have made a change with SHChangeNotify, specifying the SHCNE_ASSOCCHANGED event. If you do not call SHChangeNotify, the change might not be recognized until the system is rebooted.

There are some additional factors that apply to Microsoft® Windows® NT and Windows 2000 systems. For details, see Registering Shell Extension Handlers on Windows NT and Windows 2000 Systems.

As with all COM objects, you must create a GUID for the handler using a tool such as UUIDGEN.exe. Create a key under HKEY_CLASSES_ROOT\CLSID whose name is the string form of the GUID. Because Shell extension handlers are in-process servers, you must create an InProcServer32 key under the GUID key with the default value set to the path of the handler's DLL. Use the Apartment threading model.

Any time the Shell takes an action that can involve a Shell extension handler, it checks the appropriate registry key. The key under which an extension handler is registered thus controls when it will be called. For instance, it is a common practice to have a shortcut menu handler called when the Shell displays a shortcut menu for a member of a file class. In this case, the handler must be registered under the file class's ProgID key.

Handler Names

To enable a Shell extension handler, create a subkey with the Handler Subkey Name (see below) under the ShellEx subkey of either the ProgID (for file classes) or the Shell object type name (for predefined Shell objects).

For example, if you wanted to register a shortcut menu extension handler for MyProgram.1, you would begin by creating the following subkey.

HKEY_CLASSES_ROOT\MyProgram.1\ShellEx\ContextMenuHandlers

For the following handlers, create a subkey underneath the "Handler Subkey name" key whose name is the string version of the CLSID of the Shell extension. Multiple extensions can be registered under the "Handler Subkey Name" key by creating multiple subkeys. (For backward compatibility with Windows 95, you can also create a key under the "Handler Subkey name" key with a descriptive name and store the string version of the CLSID of the Shell extension as the default value of the key. This older method of registering Shell extensions is deprecated but is described here for completeness.)

Handler | Interface | Handler Subkey Name
Column provider handler | IColumnProvider | ColumnHandlers
Shortcut menu handler | IContextMenu | ContextMenuHandlers
Copyhook handler | ICopyHook | CopyHookHandlers
Drag-and-drop handler | IContextMenu | DragDropHandlers
Property sheet handler | IShellPropSheetExt | PropertySheetHandlers

For the following handlers, the default value of the "Handler Subkey Name" key is the string version of the CLSID of the Shell extension. Only one extension can be registered for these handlers.

Handler | Interface | Handler Subkey Name
Data handler | IDataObject | DataHandler
Drop handler | IDropTarget | DropHandler
Icon handler | IExtractIconA/W | IconHandler
Thumbnail image handler | IExtractImage | {BB2E617C-0920-11d1-9A0B-00C04FC2D6C1}
Infotip handler | IQueryInfo | {00021500-0000-0000-C000-000000000046}
Shell link (ANSI) | IShellLinkA | {000214EE-0000-0000-C000-000000000046}
Shell link (UNICODE) | IShellLinkW | {000214F9-0000-0000-C000-000000000046}
Structured storage | IStorage | {0000000B-0000-0000-C000-000000000046}
Property set storage | IPropertySetStorage | {0000013A-0000-0000-C000-000000000046}

Predefined Shell Objects

The Shell defines additional objects under HKEY_CLASSES_ROOT which can be extended in the same way as file types. For example, to add a property sheet handler for all files, you can register under HKEY_CLASSES_ROOT\*\shellex\PropertySheetHandlers.

The following table gives the various subkeys of HKEY_CLASSES_ROOT under which extension handlers can be registered. Note that many extension handlers cannot be registered under all of the listed subkeys. For further details, see the specific handler's documentation.

Subkey | Description | Possible Handlers | Version
* | All files | Shortcut Menu, Property Sheet, Verbs (see below) | All
AllFileSystemObjects | All files and file folders | Shortcut Menu, Property Sheet, Verbs | 4.71
Folder | All folders | Shortcut Menu, Property Sheet, Verbs | All
Directory | File folders | Shortcut Menu, Property Sheet, Verbs | All
Directory\Background | File folder background | Shortcut Menu only | 4.71
Network | Entire network (under My Network Places) | Shortcut Menu, Property Sheet, Verbs | All
Network\Type\# | All objects of type # (see below) | Shortcut menu, Property Sheet, Verbs | 4.71
NetShare | All network shares | Shortcut menu, Property Sheet, Verbs | 4.71
NetServer | All network servers | Shortcut menu, Property Sheet, Verbs | 4.71
network_provider_name | All objects provided by network provider "network_provider_name" | Shortcut menu, Property Sheet, Verbs | All
Printers | All printers | Shortcut Menu, Property Sheet | All
AudioCD | Audio CD in CD drive | Verbs only | All
DVDFile | DVD drive (Windows 98) | Shortcut Menu, Property Sheet, Verbs | 4.71
DVD | DVD drive (Windows 2000) | Shortcut Menu, Property Sheet, Verbs | 4.71

Notes:

  • The file folder background shortcut menu is accessed by right-clicking within a file folder, but not over any of the folder's contents.
  • "Verbs" are special commands registered under HKEY_CLASSES_ROOT\Subkey\Shell\Verb.
  • For Network\Type\#, "#" is a network provider type code in decimal. The network provider type code is the high word of a network type. The list of network types is given in the Winnetwk.h header file (WNNC_NET_* values). For example, WNNC_NET_SHIVA is 0x00330000, so the corresponding type key would be HKEY_CLASSES_ROOT\Network\Type\51.
  • "network_provider_name" is a network provider name as specified by WNetGetProviderName, with the spaces converted into underscores. For example, if the Microsoft® Networking network provider is installed, its provider name is "Microsoft Windows Network", and the corresponding network_provider_name is Microsoft_Windows_Network.

Example of an Extension Handler Registration

To enable a particular handler, create a subkey under the extension handler type key with the name of the handler. The Shell does not use the handler's name, but it must be different from all other names under that type subkey. Set the default value of the name subkey to the string form of the handler's GUID.

The following example illustrates registry entries that enable shortcut menu and property sheet extension handlers for the .myp file class used as an example in Shell Basics.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    ClsID
    ...
        {00000000-1111-2222-3333-444444444444}
            InProcServer32=C:\MyDir\MyCommand.dll
                ThreadingModel=Apartment
        {11111111-2222-3333-4444-555555555555}
            InProcServer32="C:\MyDir\MyPropSheet.dll
                ThreadingModel=Apartment
    ...
    MyProgram.1=MyProgram Application
        Shellex
            ContextMenuHandler
                MyCommand={00000000-1111-2222-3333-444444444444}
            PropertySheetHandlers
                MyPropSheet={11111111-2222-3333-4444-555555555555}

The registration procedure discussed in this section must be followed for all Windows systems. However, with Windows NT and Windows 2000 systems, an additional step might be necessary.

Registering Shell Extension Handlers on Windows NT and Windows 2000 Systems

Because Windows NT and Windows 2000 systems are designed to be used in a managed environment, installing a Shell extension handler might be somewhat different than for Windows 95 and Windows 98 systems. In particular, access to the registry could be administratively restricted, requiring a somewhat different approach to installation than described in the previous section.

Note The following discussion applies to both Windows NT and Windows 2000 systems. However, with Windows 2000 and later systems, setup programs should generally not write directly to the registry. Instead, setup should be accomplished with Windows Installer packages. These tools ensure that software runs well under Windows 2000, and provides access to new capabilities, such as per-user class registration. For more information, see Zero Administration for Windows.

Shell extension handlers run in the Shell process. Because it is a system process, the administrator of a Windows NT system can limit Shell extension handlers to those on an approved list by setting the EnforceShellExtensionSecurity value of the HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer key to 1 (one).

To place a Shell extension handler on the approved list, create a REG_SZ value whose name is the string form of the handler's GUID under HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Shell Extensions\Approved. For example, the following example adds the MyCommand and MyPropSheet handlers to the approved list.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Shell Extensions
            Approved
              {00000000-1111-2222-3333-444444444444}=MyCommand
                  Shortcut Menu Handler
              {11111111-2222-3333-4444-555555555555}=MyPropSheet
                  Property Sheet Handler

The Shell does not use the value that is assigned to the GUID, but it should be set to make inspecting the registry easier.

Your setup application can add values to the Approved key only if the person installing the application has sufficient privileges. If the attempt to add an extension handler fails, you should inform the user that administrative privileges are required to fully install the application. If the handler is essential to the application, you should fail the setup and notify the user to contact an administrator.

While there is no need to add values to the Approved key on Windows 95 or Windows 98 systems, there is no harm in doing so. The system will simply ignore them. However, there is no guarantee that the key will exist on these systems. Your setup program must be able to handle this case.


Creating Shortcut Menu Handlers

When a user right-clicks a Shell object, the Shell displays its shortcut menu. For file system objects there are a number of standard items, such as Cut and Copy, that are on the menu by default. If the object is a file that is a member of a class, additional items can be specified in the registry. Finally, the Shell checks the registry to see if the file class is associated with any shortcut menu handlers. If it is, the Shell queries the handler for additional shortcut menu items.

A shortcut menu handler is a shell extension handler that adds commands to an existing shortcut menu. Shortcut menu handlers are associated with a particular file class and are called any time a shortcut menu is displayed for a member of the class. While you can add items to a file class shortcut menu with the registry, the items will be the same for all members of the class. By implementing and registering such a handler, you can dynamically add items to an object's shortcut menu, customized for the particular object.

A closely related Shell extension handler is the drag-and-drop handler. It is a shortcut menu handler that adds items to the shortcut menu that is displayed when a user drags and drops a file with the right mouse button.

The procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to shortcut menu handlers.

  • How Shortcut Menu Handlers Work
  • Registering a Shortcut Menu Handler
  • Implementing IContextMenu
  • Implementing Drag-and-Drop Handlers

How Shortcut Menu Handlers Work

Shortcut menu handlers are a type of Shell extension handler. Like all such handlers, they are in-process COM objects implemented as dynamic-link libraries (DLLs). Shortcut menu handlers must export two interfaces in addition to IUnknown: IShellExtInit and IContextMenu. Optionally, a shortcut menu handler can also export IContextMenu2 and IContextMenu3. These interfaces handle the messaging needed to implement ownerdraw menu items.

The IShellExtInit interface is used by the Shell to initialize the handler. When the Shell calls IShellExtInit::Initialize, it passes in a data object with the object's name and the PIDL of the folder that contains the file. The hRegKey parameter is not used with shortcut menu handlers. The IShellExtInit::Initialize method must extract the file name from the data object and store the name and the folder's PIDL for later use. For further details, see Implementing IShellExtInit.

The remainder of the operation takes place through the handler's IContextMenu interface. The Shell first calls IContextMenu::QueryContextMenu. It passes in an HMENU handle that the method can use to add items to the shortcut menu. If the user selects one of the commands, IContextMenu::GetCommandString is called to retrieve the Help string that will be displayed on the Microsoft® Windows® Explorer status bar. If the user clicks one of the handler's items, the Shell calls IContextMenu::InvokeCommand. The handler can then execute the appropriate command.

Registering a Shortcut Menu Handler

Shortcut menu handlers are associated with either a file class or a folder. For file classes, the handler is registered under the file class's HKEY_CLASSES_ROOT\ProgID\Shellex\ContextMenuHandlers subkey. Create a subkey of ContextMenuHandlers named for the handler, and set the subkey's default value to the string form of the handler's CLSID GUID.

You can also associate a shortcut menu handler with different kinds of folders. Register the handler the same way you would for a file class, but under the HKEY_CLASSES_ROOT\FolderType\Shellex\ContextMenuHandlers subkey, where FolderType is the name of the type of folder.

For a discussion of how to register Shell extension handlers and more information about which folder types you can register handlers for, see Registering Shell Extension Handlers.

If a file class has a shortcut menu associated with it, double-clicking an object normally launches the default command. The handler's IContextMenu::QueryContextMenu method is not called. To specify that the handler's IContextMenu::QueryContextMenu method should be called when an object is double-clicked, create a ShellEx\MayChangeDefaultMenu subkey of the handler's CLSID key. When an object associated with the handler is double-clicked, IContextMenu::QueryContextMenu will be called with the CMF_DEFAULTONLY flag set in the uFlags parameter.

Note Setting the MayChangeDefaultMenu key forces the system to load the handler's DLL when an associated item is double-clicked. If your handler does not change the default verb, you should not set MayChangeDefaultMenu. Doing so causes the system to load your DLL unnecessarily. Shortcut menu handlers should set this key only if they might need to change the shortcut menu's default verb.

The following example illustrates registry entries that enable a shortcut menu handler for the .myp file class used as an example in Shell Basics. The handler's CLSID key includes a MayChangeDefaultMenu subkey to guarantee that the handler is called when the user double-clicks a related object.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    CLSID
    ...
        {00000000-1111-2222-3333-444444444444}
            InProcServer32=C:\MyDir\MyCommand.dll
                ThreadingModel=Apartment
            ShellEx
                MayChangeDefaultMenu
    ...
    MyProgram.1=MyProgram Application
        Shellex
            ContextMenuHandler
                MyCommand={00000000-1111-2222-3333-444444444444}

Implementing IContextMenu

Most of the operation described in How Shortcut Menu Handlers Work is handled by the IContextMenu interface. This section discusses how to implement its three methods.

QueryContextMenu Method

The Shell calls IContextMenu::QueryContextMenu to allow the shortcut menu handler to add its menu items to the menu. It passes in the HMENU handle in the hmenu parameter. The indexMenu parameter is set to the index to be used for the first menu item that is to be added.

Any menu items that are added by the handler must have identifiers that fall between the idCmdFirst and idCmdLast parameters. Typically, the first command identifier is set to idCmdFirst, which is incremented by one (1) for each additional command. This practice ensures that you don't exceed idCmdLast and maximizes the number of available identifiers in case the Shell calls more than one handler.

An item identifier's command offset is the difference between the identifier and idCmdFirst. Store the offset of each item that your handler adds to the shortcut menu because the Shell might use it to identify the item if it subsequently calls GetCommandString or InvokeCommand.

You should also assign a verb to each command you add. A verb is a language-independent string that can be used instead of the offset to identify the command when InvokeCommand is called. It is also used by functions such as ShellExecuteEx to execute shortcut menu commands.

Only three of the flags that can be passed in through the uFlags parameter are relevant to shortcut menu handlers.

CMF_DEFAULTONLY | The user has selected the default command, usually by double-clicking the object. QueryContextMenu should return control to the Shell without modifying the menu.
CMF_NODEFAULT | No item in the menu should be the default item. The method should add its commands to the menu.
CMF_NORMAL | The shortcut menu will be displayed normally. The method should add its commands to the menu.

Use either InsertMenu or InsertMenuItem to add menu items to the list. Then return an HRESULT value with the severity set to SEVERITY_SUCCESS. Set the code value to the offset of the largest command identifier that was assigned, plus one (1). For example, assume that idCmdFirst is set to 5 and you add three items to the menu with command identifiers of 5, 7, and 8. The return value should be MAKE_HRESULT(SEVERITY_SUCCESS, 0, 8 - 5 + 1).

The following example shows a simple implementation of QueryContextMenu that inserts a single command. The identifier offset for the command is IDM_DISPLAY, which is set to zero. The m_pszVerb and m_pwszVerb variables are private variables used to store the associated language-independent verb string in both Unicode and ANSI formats.

#define IDM_DISPLAY 0

STDMETHODIMP CMenuExtension::QueryContextMenu(HMENU hMenu,
                                               UINT indexMenu,
                                               UINT idCmdFirst,
                                               UINT idCmdLast,
                                               UINT uFlags)
{

    if(!(CMF_DEFAULTONLY & uFlags))
    {
        InsertMenu(hMenu,
                    indexMenu,
                    MF_STRING | MF_BYPOSITION,
                    idCmdFirst +IDM_DISPLAY,
                    "&Display File Name");

        StrCpyA(m_pszVerb, "display");
        StrCpyW(m_pwszVerb, L"display");

        return MAKE_HRESULT(SEVERITY_SUCCESS, 0, USHORT(IDM_DISPLAY + 1));
    }

    return MAKE_HRESULT(SEVERITY_SUCCESS, 0, USHORT(0));
}

GetCommandString Method

If a user highlights one of the items added by a shortcut menu handler, the handler's IContextMenu::GetCommandString method is called to request a Help text string that will be displayed on the Microsoft® Windows® Explorer status bar. This method can also be called to request the verb string that is assigned to a command. Either ANSI or Unicode verb strings can be requested.

The idCmd parameter holds the identifier offset of the command that was defined when QueryContextMenu was called. If a Help string is requested, uFlags will be set to either GCS_HELPTEXTA or GCS_HELPTEXTW, depending on whether an ANSI or Unicode string is desired. Copy the Help string to the pszName buffer, casting it to an LPWSTR for the Unicode case. The verb string is requested by setting uFlags to either GCS_VERBA or GCS_VERBW. Copy the appropriate string to pszName, just as with the Help string. The GCS_VALIDATEA and GCS_VALIDATEW flags are not used by shortcut menu handlers.

The following example shows a simple implementation of GetCommandString that corresponds to the QueryContextMenu example given in the QueryContextMenu Method section. Since the handler adds only one menu item, there is only one set of strings that can be returned. The method simply tests whether idCommand is valid and, if it is, returns the requested ANSI or Unicode string.

The lstrcpyn function is used to copy the requested string to pszName to ensure that the copied string doesn't exceed the size of the buffer given by uMaxNameLen. The ANSI and Unicode versions of the function are used explicitly, because the format defined when the handler is compiled might not match the requested format.

STDMETHODIMP CMenuExtension::GetCommandString(UINT idCommand,
                                               UINT uFlags,
                                               LPUINT lpReserved,
                                               LPSTR pszName,
                                               UINT uMaxNameLen)
{
    HRESULT  hr = E_INVALIDARG;

    if(idCommand != IDM_DISPLAY)
    {
        return hr;
    }

    switch(uFlags)
    {
        case GCS_HELPTEXTA:
            lstrcpynA(pszName, "Display File Name", uMaxNameLen);
            hr = S_OK;
            break;

        case GCS_HELPTEXTW:
            lstrcpynW((LPWSTR)pszName, L"Display File Name",
                       uMaxNameLen);
            hr = S_OK;
            break;

        case GCS_VERBA:
            lstrcpynA(pszName, m_pszVerb, uMaxNameLen);
            hr = S_OK;
            break;

        case GCS_VERBW:
            lstrcpynW((LPWSTR)pszName, m_pwszVerb, uMaxNameLen);
            hr = S_OK;
            break;

        default:
            hr = S_OK;
            break;
    }
    return hr;
}

InvokeCommand Method

This method is called when a user clicks a menu item to tell the handler to run the associated command. The pici parameter points to a structure that contains the needed information.

Although pici is declared in Shlobj.h as a CMINVOKECOMMANDINFO structure, in practice it often points to a CMINVOKECOMMANDINFOEX structure. This structure is an extended version of CMINVOKECOMMANDINFO and has several additional members that allow Unicode strings to be passed.

Check the cbSize member of pici to determine which structure was passed in. If it is a CMINVOKECOMMANDINFOEX structure and the fMask member has the CMIC_MASK_UNICODE flag set, cast pici to CMINVOKECOMMANDINFOEX. This allows your application to use the Unicode information contained in the last five members of the structure.

The structure's lpVerb or lpVerbW member is used to identify the command to be executed. There are two ways to identify commands:

  • The command's verb string
  • The command's identifier offset

To distinguish between these two cases, check the high-order word of lpVerb for the ANSI case or lpVerbW for the Unicode case. If the high-order word is nonzero, lpVerb or lpVerbW holds a verb string. If the high-order word is zero, the command offset is in the low-order word of lpVerb.

The following example shows a simple implementation of InvokeCommand that corresponds to the QueryContextMenu and GetCommandString samples given in the previous sections. The method first determines which structure is being passed in. It then determines whether the command is identified by its offset or verb. If lpVerb or lpVerbW holds a valid verb or offset, the method displays a message box.

STDMETHODIMP CShellExtension::InvokeCommand(LPCMINVOKECOMMANDINFO lpcmi)
{
    BOOL fEx = FALSE;
    BOOL fUnicode = FALSE;

    if(lpcmi>cbSize = sizeof(CMINVOKECOMMANDINFOEX))
    {
        fEx = TRUE;
        if((lpcmi>fMask & CMIC_MASK_UNICODE))
        {
            fUnicode = TRUE;
        }
    }

    if( !fUnicode && HIWORD(lpcmi>lpVerb))
    {
        if(StrCmpIA(lpcmi>lpVerb, m_pszVerb))
        {
            return E_FAIL;
        }
    }

    else if( fUnicode && HIWORD(((CMINVOKECOMMANDINFOEX *) lpcmi)>lpVerbW))
    {
        if(StrCmpIW(((CMINVOKECOMMANDINFOEX *)lpcmi)>lpVerbW, m_pwszVerb))
        {
            return E_FAIL;
        }
    }

    else if(LOWORD(lpcmi>lpVerb) != IDM_DISPLAY)
    {
        return E_FAIL;
    }

    else
    {
        MessageBox(lpcmi>hwnd,
                   "The File Name",
                   "File Name",
                   MB_OK|MB_ICONINFORMATION);
    }

    return S_OK;
}

Creating Drag-and-Drop Handlers

When a user right-clicks a Shell object to drag an object, a shortcut menu is displayed when the user attempts to drop the object. The following illustration shows a typical drag-and-drop shortcut menu.

Drag-and-drop shortcut menu

A drag-and-drop handler is a shortcut menu handler that can add items to this shortcut menu. Drag-and-drop handlers are typically registered under the DragDropHandlers subkey of the Shellex subkey of the Directory subkey. Add a subkey to the DragDropHandlers subkey named for the drag-and-drop handler, and set the subkey's default value to the string form of the handler's CLSID GUID. The following example enables the MyDD drag-and-drop handler.

HKEY_CLASSES_ROOT
    Directory
        Shellex
            DragDropHandlers
                MyDD={MyDD CLSID GUID}

The basic procedure for implementing a drag-and-drop handler is the same as for conventional shortcut menu handlers. However, shortcut menu handlers normally use only the IDataObject pointer passed to the handler's IShellExtInit::Initialize method to extract the object's name. A drag-and-drop handler could implement a more sophisticated data handler to modify the behavior of the dragged object.


Creating Data Handlers

When a file is copied to the clipboard or dragged and dropped, the Shell creates a data object that supports a variety of standard clipboard formats. For files that are members of a file class, you can extend the available clipboard formats by implementing and registering a data handler. When a member of the file class is transferred, the Shell delegates calls to the data object's IDataObject interface to the data handler if one of the custom formats is used.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to data handlers.

  • Registering Data Handlers
  • Implementing Data Handlers

Registering Data Handlers

Data handlers are registered under the file class's HKEY_CLASSES_ROOT\ProgID\Shellex\DataHandler subkey. Create a subkey of DataHandler named for the handler, and set the subkey's default value to the string form of the handler's CLSID GUID. For a general discussion of how to register Shell extension handlers, see Creating Shell Extension Handlers.

The following example illustrates registry entries that enable a data handler for the .myp file class used as an example in Shell Basics.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    CLSID
    ...
        {00000000-1111-2222-3333-444444444444}
            InProcServer32=C:\MyDir\MyCommand.dll
                ThreadingModel=Apartment
    ...
    MyProgram.1=MyProgram Application
        Shellex
            DataHandler
                MyCommand={00000000-1111-2222-3333-444444444444}

Implementing Data Handlers

Like all Shell extension handlers, data handlers are in-process COM objects implemented as DLLs. They export two interfaces in addition to IUnknown: IPersistFile and IDataObject.

The Shell initializes the handler through its IPersistFile interface. It uses this interface to request the handler's CLSID and provides it with the file's name. For a general discussion of how to implement Shell extension handlers, including the IPersistFile interface, see Creating Shell Extension Handlers.

Once the data handler is initialized, the Shell delegates calls from the data object to the handler's IDataObject interface if one of the custom formats is used.


Creating Drop Handlers

By default, files are not drop targets. You can make the members of a file class into drop targets by implementing and registering a drop handler.

If a drop handler is registered for a file class, it is called whenever an object is dragged over or dropped on a member of the class. The Shell manages the operation by calling the appropriate methods on the handler's IDropTarget interface.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to drop handlers.

  • Registering Drop Handlers
  • Implementing Drop Handlers

Registering Drop Handlers

Drop handlers are registered under the file class's HKEY_CLASSES_ROOT\ProgID\Shellex\DropHandler subkey. Create a subkey of DropHandler named for the handler, and set the subkey's default value to the string form of the handler's CLSID GUID. For a general discussion of how to register Shell extension handlers, see Creating Shell Extension Handlers.

The following example illustrates registry entries that enable a drop handler for the .myp file class used as an example in Shell Basics.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    CLSID
    ...
        {00000000-1111-2222-3333-444444444444}
            InProcServer32=C:\MyDir\MyCommand.dll
                ThreadingModel=Apartment
    ...
    MyProgram.1=MyProgram Application
        Shellex
            DropHandler
                MyCommand={00000000-1111-2222-3333-444444444444}

Implementing Drop Handlers

Like all Shell extension handlers, drop handlers are in-process COM objects implemented as DLLs. They export two interfaces in addition to IUnknown: IPersistFile and IDropTarget.

The Shell initializes the handler through its IPersistFile interface. It uses this interface to request the handler's CLSID and provides it with the file's name. For a general discussion of how to implement Shell extension handlers, including the IPersistFile interface, see Creating Shell Extension Handlers.

Once the drop handler is initialized, the Shell calls the appropriate method on the handler's IDropTarget interface.


Creating Icon Handlers

A file class often has a custom icon associated with it, to make its members easily recognizable in Microsoft® Windows® Explorer. The simplest way to assign a custom icon to a file class is to register the icon's file. For a complete discussion of how to statically register an icon for a file class, see the Customizing Icons section of Shell Basics. However, an icon registered in this way will be the same for all members of the file class. You can have much more flexibility in assigning icons to the members of the file class by implementing an icon handler.

An icon handler is a type of Shell extension handler that allows you to dynamically assign icons to the members of a file class. Every time a file from the class is displayed, the Shell queries the handler for the appropriate icon. For instance, an icon handler can assign different icons to different members of the class, or vary the icon based on the current state of the file.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to icon handlers.

  • Registering Icon Handlers
  • Implementing Icon Handlers

Registering Icon Handlers

When you statically register an icon for a file class, you create a DefaultIcon subkey under the ProgID for the file class. Its default value is set to the file that contains the icon. To register an icon handler, you must still have the DefaultIcon subkey, but its default value must be set to "%1". Add an IconHandler subkey to the Shellex subkey of the ProgID subkey, and set its default value to the string form of the handler's CLSID GUID. For a general discussion of how to register Shell extension handlers, see Creating Shell Extension Handlers.

The following example modifies the registry entry from Customizing Icons so that the .myp file class now uses a shortcut menu handler instead of a statically defined icon.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    MyProgram.1=MyProgram Application
        DefaultIcon=%1
        Shellex
        IconHandler={The handler's CLSID GUID}

Implementing Icon Handlers

Like all Shell extension handlers, icon handlers are in-process COM objects implemented as DLLs. They must export two interfaces in addition to IUnknown: IPersistFile and IExtractIcon.

The Shell initializes the handler through its IPersistFile interface. It uses this interface to request the handler's CLSID and provides it with the file's name. The rest of the operation takes place through the IExtractIcon interface. For a general discussion of how to implement Shell extension handlers, including the IPersistFile interface, see Creating Shell Extension Handlers. The remainder of this document discusses how to implement the IExtractIcon interface.

Implementing the IExtractIcon Interface

After the interface is initialized, the Shell uses the handler's IExtractIcon interface to request the appropriate icon. The interface has two methods: IExtractIcon::GetIconLocation and IExtractIcon::Extract.

Icons are identified by their location in the file system. The IExtractIcon::GetIconLocation method is called to request this information. Set the szIconFile parameter to the file name. If there is more than one icon in the file, set piIndex to the icon's index. Assign appropriate values to the two flag variables. If you do not want to specify a file name, or if you do not want the Shell to extract the icon, set the GIL_NOTFILENAME flag in the piIndex parameter. You do not need to assign a value to szIconFile, but the handler must provide icon handles when the Shell calls IExtractIcon::Extract.

If you return a file name, the Shell normally attempts to load the icon from its cache. To prevent the loading of a cached icon, set the GIL_DONTCACHE flag in the piIndex parameter. If a cached icon is not loaded, the Shell then calls IExtractIcon::Extract to request the icon handle.

If a file and index were specified by IExtractIcon::GetIconLocation, they are passed to IExtractIcon::Extract in the pszFile and nIconIndex parameters, respectively. If a file name is provided, your handler can return S_FALSE to have the Shell extract the icon. Otherwise, your handler must extract or otherwise produce large and small icons, and assign their HICON handles to the phiconLarge and phiconSmall parameters. The Shell adds the icons to its cache to expedite subsequent calls to the handler.


Creating Icon Overlay Handlers

Icon overlays are small images placed at the lower-left corner of the icon that represents a Shell object. They are normally added to an object's icon to provide some extra information. For instance, a commonly used icon overlay is the small arrow that indicates that the icon represents a link, rather than the actual file or folder. In addition to the standard icon overlays that are provided by the system, you can request custom icon overlays for specified Shell objects by implementing and registering an icon overlay handler.

Note The number of different icon overlay handlers that the system can support is limited by the amount of space available for icon overlays in the system image list. There are currently fifteen slots allotted for icon overlays, some of which are reserved by the system. For this reason, icon overlay handlers should be implemented only if there are no satisfactory alternatives.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to icon overlay handlers.

  • How Icon Overlay Handlers Work
  • Registering Icon Overlay Handlers
  • Implementing Icon Overlay Handlers

How Icon Overlay Handlers Work

Icon overlay handlers are COM objects that are associated with a particular icon overlay. All communication between the Shell and the handler takes place through the handler's IShellIconOverlayIdentifier interface.

When the Shell starts up, it initializes all icon overlay handlers by calling two of their IShellIconOverlayIdentifier methods:

  • The Shell calls IShellIconOverlayIdentifier::GetOverlayInfo to request the location of the handler's icon overlay. The icon overlay handler returns the name of the file containing the overlay image, and its index within that file. The Shell then adds the icon overlay to the system image list.
  • The Shell calls IShellIconOverlayIdentifier::GetPriority to determine the icon overlay's priority. The priority value is a number from zero to 100, with 100 indicating the lowest priority. If more than one icon overlay is requested for a particular file, the Shell uses this value to help it determine which icon overlay to display.

Before painting an object's icon, the Shell passes the object's name to each icon overlay handler's IShellIconOverlayIdentifier::IsMemberOf method. An icon overlay handler is normally associated with a particular group of files. For example, the icon overlay handler might request an overlay for all members of a file class, such as all files with an .myp file name extension. If a handler wants to have its icon overlay displayed, it returns S_OK. The Shell then calls the handler's IShellIconOverlayIdentifier::GetOverlayInfo method to determine which icon to display.

Note Once the image has been loaded into the system image list during initialization, it cannot be changed. After initialization, the file name and index are used only to identify the icon overlay. The system will not load a new icon overlay. When IShellIconOverlayIdentifier::GetOverlayInfo is called, your handler must return the same file name and index that was specified when the function was first called.

Although only one icon overlay can be displayed, it is possible for an object to have icon overlays requested by more than one handler. In that case, the Shell resolves the conflict by displaying the highest priority icon overlay. The Shell resolves many such conflicts with an internal set of rules. If these rules are not sufficient, the Shell compares the priority values that were specified by the handlers' IShellIconOverlayIdentifier::GetPriority method during initialization.

Registering Icon Overlay Handlers

In addition to normal COM registration, you must also create a subkey named for the handler under the ShellIconIdentifiers subkey of HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer. Set the default value of the subkey to the string form of the object's CLSID GUID. The following example illustrates how to register an icon overlay handler named MyOverlay.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            ShellIconOverlayIdentifiers
              MyOverlay={MyOverlay CLSID GUID}

Implementing Icon Overlay Handlers

Icon overlay handlers are in-process COM objects, implemented as DLLs. They export one interface in addition to IUnknown: IShellIconOverlayIdentifier. This interface has three methods: IShellIconOverlayIdentifier::GetOverlayInfo, IShellIconOverlayIdentifier::GetPriority, and IShellIconOverlayIdentifier::IsMemberOf.

Implementing GetOverlayInfo

This method is first called during initialization. The method returns the fully qualified path of the file containing the icon overlay image, and its zero-based index within the file. The Shell then adds the image to the system image list. Icon overlays can be contained in any of the standard file types, including .exe, .dll, and .ico.

After initialization is complete, the Shell calls GetOverlayInfo when it needs to display the handler's icon overlay. The method should return the same file name and index that it did during initialization. Although the Shell uses the image that is cached in the system image list rather than loading the image from the file, an icon overlay is still identified by its file name and index.

Implementing GetPriority

This method is called only during initialization. It assigns a priority value to the handler's icon overlay. The value can range from zero to 100, where 100 is the lowest priority. The purpose of this priority value is to help the Shell resolve the conflict that arises when multiple icon overlays are specified for a single object. The Shell first uses an internal set of rules to determine the highest priority icon overlay. If these rules do not resolve the conflict, the values assigned to the icon overlays by GetPriority determine priority.

The priority value set by GetPriority is not a reliable way to resolve conflicts between unrelated icon overlay handlers. There is no way for your handler to determine what priority values other handlers are using. Normally, you should set the value to zero. However, the priority value is useful when you have implemented two or more icon overlay handlers that can request icon overlay icons for the same object. By setting the priority values appropriately, you can specify which of the requested icon overlays will be displayed.

Implementing IsMemberOf

The Shell calls this method to determine whether it should display a handler's icon overlay for a particular object. It specifies the object by passing its name to the method. If a handler wants to have its icon overlay displayed, IsMemberOf returns S_OK. If not, it returns S_FALSE.

Icon overlay handlers are normally intended to work with a particular group of files. A typical example is a file class, identified by a specific file name extension. An icon overlay handler can request an icon overlay for all members of the file class. Some handlers request an icon overlay only if a member of the file class is in a particular state. However, icon overlay handlers are free to request their icon overlay for any object that they want.


Creating Property Sheet Handlers

When a user right-clicks a Shell object, the shortcut menu that is displayed normally includes a Properties item. Selecting that item launches a property sheet that allows the user to view, and in some cases modify, the object's properties. You can customize this property sheet by implementing and registering a property sheet handler

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to property sheet handlers.

  • How Property Sheet Handlers Work
  • Registering and Implementing a Property Sheet Handler for a File Class
  • Registering and Implementing a Property Sheet Handler for a Mounted Drive
  • Registering and Implementing a Property Sheet Handler for a Control Panel Application

How Property Sheet Handlers Work

The following illustration shows the Properties property sheet for a Microsoft® Windows® 2000 text file.

This illustration shows the default Properties property sheet that is displayed for any file. For many such property sheets, you can add one or more pages to the property sheet by implementing and registering a property sheet handler.

Property sheet handlers are most commonly registered for a file class. Each handler can add one custom page to the Properties property sheet for the class. These pages typically give users access to properties that are specific to the particular file class. A class consisting of text documents could, for instance, display a page that listed the title and author, and an abstract of the document. A special case of this type of property sheet handler is used to add a page to the Properties property sheet for a mounted drive.

The other use for property sheet handlers is to replace pages in the property sheets displayed by Control Panel applications. A mouse manufacturer, for instance, can use a property sheet handler to replace the Buttons page on the Control Panel's Mouse Properties property sheet with a page that is customized for the characteristics of its mouse.

Like all Shell extension handlers, property sheet handlers are in-process COM objects implemented as DLLs. They must export two interfaces in addition to IUnknown: IShellExtInit and IShellPropSheetExt.

The IShellExtInit interface is used by the Shell to initialize the handler. When the Shell calls IShellExtInit::Initialize, it passes in a data object with the object's name, and the PIDL of the folder that contains the file. The hRegKey parameter is not used with property sheet handlers. The Initialize method must extract the file name from the data object, and store the name and the folder's PIDL for later use. For further details, see Implementing IShellExtInit.

The remainder of the operation takes place through the handler's IShellPropSheetExt interface. If the property sheet is associated with a file class, the Shell calls IShellPropSheetExt::AddPages to allow the handler to add a page to the property sheet. If the property sheet is associated with a Control Panel application, the Shell calls IShellPropSheetExt::ReplacePage to allow the handler to replace a page.

Registering and Implementing a Property Sheet Handler for a File Class

When the user right-clicks a member of a file class to display the Properties property sheet, the Shell calls the property sheet handlers that are registered for the file class. Each handler can add one custom page to the default property sheet.

Registering a Property Sheet Handler for a File Class

In addition to normal COM registration, add a PropertySheetHandlers subkey to the Shellex subkey of the ProgID key of the application associated with the file class. Create a subkey of PropertySheetHandlers with the handler's name, and set the default value to the string form of the property sheet handler's CLSID GUID.

To add more than one page to the property sheet, register a handler for each page. The maximum number of pages that a property sheet can support is 24. To register multiple handlers, create a key under the Shellex key for each handler, with the default value set to the handler's CLSID GUID. It is not necessary to create a distinct object for each handler, so multiple handlers can all have the same GUID value. The pages will be displayed in the order that their keys are listed under Shellex.

The following example illustrates a registry entry that enables two property sheet extension handlers for the .myp file class used as an example in Shell Basics. In this example, a separate object is used for each page, but a single object could also be used for both.

HKEY_CLASSES_ROOT
    .myp=MyProgram.1
    ...
    CLSID
    ...
        {Page 1 Property Sheet Handler CLSID GUID}
            InProcServer32="C:\MyDir\MyPropSheet1.dll
                ThreadingModel=Apartment
        {Page 2 Property Sheet Handler CLSID GUID}
            InProcServer32="C:\MyDir\MyPropSheet2.dll
                ThreadingModel=Apartment
    ...
    MyProgram.1=MyProgram Application
        Shellex
            PropertySheetHandlers
                MyPropSheet1={Page1 Property Sheet Handler CLSID GUID}
                MyPropSheet2={Page2 Property Sheet Handler CLSID GUID}

For a general discussion of how to register Shell extension handlers, see Creating Shell Extension Handlers.

Implementing a Property Sheet Handler for a File Class

In addition to the general implementation discussed in How Property Sheet Handlers Work, a property sheet handler for a file class must also have an appropriate implementation of IShellPropSheetExt. Only the IShellPropSheetExt::AddPages method needs a nontoken implementation. The Shell doesn't call IShellPropSheetExt::ReplacePage.

Implementing the AddPages Method

The IShellPropSheetExt::AddPages method allows a property sheet handler to add a page to a property sheet. The method has two input parameters. The first, lpfnAddPage, is a pointer to an AddPropSheetPageProc callback function that is used to provide the Shell with the information needed to add the page to the property sheet. The second, lParam, is a Shell-defined value that is not processed by the handler. It is simply passed back to the Shell when the callback function is called.

The general procedure for implementing IShellPropSheetExt::AddPages is:

  1. Assign appropriate values to the members of a PROPSHEETPAGE structure. In particular:
    • Assign the variable that holds the handler's reference count to the pcRefParent member. This practice prevents the handler object from being unloaded while the property sheet is still being displayed.
    • You can also implement a PropSheetPageProc callback function and assign its pointer to a pfnCallback member. This function is called when the page is created and when it is about to be destroyed.
  2. Create the page's HPAGE handle by passing the PROPSHEETPAGE structure to CreatePropertySheetPage.
  3. Call the function pointed to by lpfnAddPage. Set its first parameter to the HPAGE handle created in the previous step. Set its second parameter to the lParam value passed in to AddPages by the Shell.
  4. Any messages associated with the page will be passed to the dialog box procedure that was assigned to the pfnDlgProc member of the PROPSHEETPAGE structure.
  5. If you assigned a PropSheetPageProc callback function to pfnCallback, it will be called when the page is about to be destroyed. Your handler can then perform any needed cleanup operations, such as releasing any references it holds.

The following code sample illustrates a simple IShellPropSheetExt::AddPages implementation.

STDMETHODIMP CShellPropSheetExt::AddPages(LPFNADDPROPSHEETPAGE
    lpfnAddPage, LPARAM lParam)
{
    PROPSHEETPAGE  psp;
    HPROPSHEETPAGE hPage;

    psp.dwSize        = sizeof(psp);
    psp.dwFlags       = PSP_USEREFPARENT | PSP_USETITLE | PSP_USECALLBACK;
    psp.hInstance     = g_hInst;
    psp.pszTemplate   = MAKEINTRESOURCE(IDD_PAGEDLG);
    psp.hIcon         = 0;
    psp.pszTitle      = TEXT("Extension Page");
    psp.pfnDlgProc    = (DLGPROC)PageDlgProc;
    psp.pcRefParent   = &g_DllRefCount;
    psp.pfnCallback   = PageCallbackProc;
    psp.lParam        = (LPARAM)this;

    hPage = CreatePropertySheetPage(&psp);

    if(hPage)
    {
        if(lpfnAddPage(hPage, lParam))
        {
            this->AddRef();
            return S_OK;
        }
        else
        {
            DestroyPropertySheetPage(hPage);
        }

    }
    else
    {
        return E_OUTOFMEMORY;
    }
    return E_FAIL;
}

The g_hInst variable is the instance handle for the DLL, and IDD_PAGEDLG is the resource ID of the page's dialog box template. The PageDlgProc function is the dialog box procedure that handles the page's messages. The g_DllRefCount variable holds the object's reference count. The AddPages method calls AddRef to increment it. However, the reference count is released by the callback function, PageCallbackProc, when the page is about to be destroyed.

Registering and Implementing a Property Sheet Handler for a Mounted Drive

Each mounted drive has a Properties sheet that can be displayed by the user. The following illustration shows a Properties property sheet for a CD-ROM drive.

CD-ROM Properties property sheet

There are a wide variety of devices that can be mounted as drives. Because the default property sheet, designed for disk drives, might not be sufficient for some devices, a property sheet handler can be implemented to add a page that is specific to the mounted device. The basic implementation of this type of property sheet handler is identical to that discussed in Implementing a Property Sheet Handler for a File Class, with two exceptions:

  • The data object passed to the handler's IShellExtInit::Initialize method may contain the drive path in the CFSTR_MOUNTEDVOLUME format instead of the CF_HDROP format. The CF_HDROP format is used when the device is mounted to a drive letter. The CFSTR_MOUNTEDVOLUME format is used with NTFS file systems when the remote device is mounted to a folder rather than to a drive letter.
  • The handler's GUID is registered under the HKEY_CLASSES_ROOT\Drive\Shellex\PropertySheetHandlers key.

Registering and Implementing a Property Sheet Handler for a Control Panel Application

Many Control Panel applications display Properties property sheets to allow users to view and modify various device and system settings. Three of them, Mouse, Keyboard, and Display, allow property sheet handlers to replace one or more of their pages with a custom page. The following illustration shows the Mouse Properties property sheet.

Property sheet handlers for Control Panel applications are similar to those for file classes, with three primary exceptions:

  • They are called by a Control Panel application, not the Shell.
  • They are registered differently.
  • The Control Panel application calls IShellPropSheetExt::ReplacePage to replace a page. It does not call IShellPropSheetExt::AddPages.

Registering a Property Sheet Handler for a Control Panel Application

A Control Panel application property sheet handler must be registered under the control panel's subkey. This key can be in either of two locations, depending on whether the handler is to be per-user or per-computer. For per-user registration, the control panel's subkey is HKEY_CURRENT_USER\REGSTR_PATH_CONTROLPANEL. For per-computer registration, it is HKEY_LOCAL_MACHINE\REGSTR_PATH_CONTROLSFOLDER. The REGSTR_PATH_CONTROLPANEL and REGSTR_PATH_CONTROLPANEL macros are defined in Regstr.h.

The three Control Panel applications that allow property sheet handlers to replace pages have a subkey under the Control Panel's subkey, named for the application. They are named Mouse, Keyboard, and Display. The application's subkey must have a Shellex subkey with a PropertySheetHandlers subkey. To register a property sheet handler, add its GUID to the PropertySheetHandlers subkey associated with the Control Panel application. To do so, create a subkey of the PropertySheetHandlers subkey, named for the property sheet handler, and set its default value to the string form of the handler's GUID.

The following example registers a property sheet handler for the Mouse Control Panel application on a per-computer basis. To register it on a per-user basis, replace REGSTR_PATH_CONTROLSFOLDER with REGSTR_PATH_CONTROLPANEL.

HKEY_LOCAL_MACHINE
    REGSTR_PATH_CONTROLSFOLDER
        Mouse
            Shellex
                PropertySheetHandlers
                    MyPropHandler={MyPropHandler CLSID GUID}

Implementing a Property Sheet Handler for a Control Panel Application

The procedure for implementing a Control Panel property sheet handler is very similar to that discussed in Implementing a Property Sheet Handler for a File Class. The primary difference is that now IShellPropSheetExt::ReplacePage needs a nontoken implementation instead of IShellPropSheetExt::AddPages.

When a Control Panel application is about to display its property sheet, it calls the property sheet handler's IShellPropSheetExt::ReplacePage method once for each page that can be replaced. The uPageID parameter is set to the page's ID. The IDs for the available pages are defined in Cplext.h. The currently available IDs are listed in the following table.

Page ID | Description | Control Panel application
CPLPAGE_MOUSE_BUTTONS | The Buttons page | Mouse
CPLPAGE_MOUSE_PTRMOTION | The Motion page | Mouse
CPLPAGE_MOUSE_WHEEL | The Wheel page | Mouse
CPLPAGE_KEYBOARD_SPEED | The Speed page | Keyboard
CPLPAGE_DISPLAY_BACKGROUND | The Background page | Display

Otherwise, the procedure for creating and replacing a page is identical to that for adding a page. For further information, see Implementing a Property Sheet Handler for a File Class.


Creating Column Handlers

The Microsoft® Windows® Explorer Details view normally displays several standard columns. Each column lists information, such as the file size or type, for each file in the current folder. By implementing and registering a column handler, you can make custom columns available for display.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to column handlers.

  • How Column Handlers Work
  • Registering Column Handlers
  • Implementing Column Handlers

How Column Handlers Work

The following illustration shows a Windows Explorer Details view.

With Windows 2000, the folder can also support a number of columns that, by default, are not displayed. The user can display additional columns by right-clicking one of the column headers and selecting the More... command from the menu. A dialog box then appears that lists the available columns for the folder and allows the user to select which columns to display. The following illustration shows this dialog box for the preceding example.

By creating a column handler, you can create custom columns and add them to that list. For example, a collection of files that contain music could use a column handler to display columns listing the artist and piece contained by each file.

A column handler is a global object that is called every time Windows Explorer displays the Details view. However, column handlers are typically used to display custom columns only for members of a particular file class. Before it displays the Details view, Windows Explorer queries all registered column handlers for their column characteristics. If the user has selected one of the handler's columns, Windows Explorer queries the handler for the associated data. When a column handler receives a request for data, it provides it if the file is a member of its supported class. Otherwise, it ignores the request by returning S_FALSE.

Registering Column Handlers

Column handlers are registered under the HKEY_CLASSES_ROOT\Folder\shellex\ColumnHandlers subkey. Create a subkey of ColumnHandlers named with the string form of the handler's CLSID GUID. For a general discussion of how to register Shell extension handlers, see Creating Shell Extension Handlers. The following example illustrates how to register a column handler.

HKEY_CLASSES_ROOT
  Folder
    Shellex
      ColumnHandlers
        ...
        {My Column Handler CLSID GUID}

Implementing Column Handlers

Like all Shell extension handlers, column handlers are in-process COM objects implemented as DLLs. They export the IColumnProvider interface in addition to IUnknown.

Windows Explorer calls the three methods exported by IColumnProvider to request the information it needs to display the column. The procedure used by Windows Explorer is:

  1. Call IColumnProvider::Initialize to specify the folder that is about to be displayed.
  2. Call IColumnProvider::GetColumnInfo to retrieve the column's identifier and characteristics.
  3. If the column has been selected by the user, call IColumnProvider::GetItemData for each file in the folder to retrieve the data that belongs in the file's column entry.

The Initialize Method

Windows Explorer calls Initialize to initialize the column handler. The method has three parameters, but only wszFolder is currently used. It is set to the folder whose Details view is about to be displayed. Store the folder name for future use and initialize the handler object as needed.

The GetColumnInfo Method

Windows Explorer next calls GetColumnInfo to request the column's identifier and characteristics. It passes in an index for the column in the dwIndex parameter. This index is an arbitrary value that is used to enumerate columns. Windows Explorer also passes in a pointer to an SHCOLUMNINFO structure. This structure is used to return the column's identifier and characteristics. GetColumnInfo should assign appropriate values to the members of the structure and return.

Columns are identified by their OLE property set ID (FMTID) and an associated property ID (PID). The first member of the SHCOLUMNINFO structure, scid, is a pointer to an SHCOLUMNID structure that is used to identify the column. Its fmtid member holds the column's FMTID, and its pid member holds the column's PID. For example, a standard FMTID/PID pair that is commonly used to identify columns is the Author PID of the Summary Information property set. For a general discussion of FMTIDs and PIDs, see Storing Information with System Objects.

If possible, your handler should use existing FMTIDs and PIDs to identify the column it supports. If you use a custom SHCOLUMNID structure, the column will display data only for those files that are supported by the handler. If the folder contains other files, their entries will be blank. If a folder contains files from more than one file class, using standard FMTID/PID values could make it possible to merge data from different classes into the same column.

Set the vt member to the VARIANT type of the data you want to display in the column. The most commonly used type is VT_LPSTR, as most columns display their data as character strings. The remaining members of the SHCOLUMNINFO structure are used to define the characteristics of the column. Assign values as appropriate.

The GetItemData Method

If the column handler's column has been selected, Windows Explorer calls GetItemData for each file in the folder that is to be displayed. The pscid parameter is a pointer to an SHCOLUMNID structure that identifies the column. The pscd parameter points to an SHCOLUMNDATA structure that identifies the particular file.

The pvarData parameter returns the data that should be displayed in the handler's column for the file specified by pscd. If that file is supported by your column handler, assign its data value to pvarData and return S_OK. If the file is not supported by your column handler, return S_FALSE without assigning a value to pvarData.

Many folders will contain a number of files that are not supported by any particular column handler. To improve efficiency, GetItemData should first check the pwszExt member of the structure pointed to by pscd. This member holds the file name extension. If the extension indicates that the file is not a member of a file class supported by your handler, avoid unnecessary processing by immediately returning S_FALSE.


Creating Copy Hook Handlers

Normally, users and applications can copy, move, delete, or rename folders with few restrictions. By implementing a copy hook handler, you can control whether or not these operations take place. For instance, implementing such a handler allows you to prevent critical folders from being renamed or deleted. Copy hook handlers can also be implemented for printer objects.

Copy hook handlers are global. The Shell calls all registered handlers every time an application or user attempts to copy, move, delete, or rename a folder or printer object. The handler does not perform the operation itself. It only approves or vetoes it. If all handlers approve, the Shell does the operation. If any handler vetoes the operation, it is canceled and the remaining handlers are not called. Copy hook handlers are not informed of the success or failure of the operation, so they cannot be used to monitor file operations.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to copy hook handlers.

  • Registering Copy Hook Handlers
  • Implementing Copy Hook Handlers

Registering Copy Hook Handlers

Copy hook handlers for folders are registered under the HKEY_CLASSES_ROOT\Directory\Shellex\CopyHookHandlers key. Create a subkey of CopyHookHandlers named for the handler, and set the subkey's default value to the string form of the handler's CLSID GUID.

The following example adds the MyCopyHandler subkey to the Shell's list of copy hook handlers.

HKEY_CLASSES_ROOT
    Directory
        Shellex
            CopyHookHandlers
                ...
                MyCopyHandler={MyCopyHandler CLSID GUID}

Copy hook handlers for printer objects are registered in essentially the same way. The only difference is that you must register them under the HKEY_CLASSES_ROOT\Printers\Shellex\CopyHookHandlers key.

Implementing Copy Hook Handlers

Like all Shell extension handlers, copy hook handlers are in-process COM objects implemented as DLLs. They export one interface in addition to IUnknown: ICopyHook. The Shell initializes the handler directly, so there is no need for an initialization interface such as IShellExtInit.

The ICopyHook interface has a single method, ICopyHook::CopyCallback. When a folder is about to be moved, the Shell calls this method. It passes in a variety of information, including:

  • The folder's name.
  • The folder's destination or new name.
  • The operation that is being attempted.
  • The attributes of the source and destination folders.
  • A window handle that can be used to display a user interface.

When your handler's ICopyHook::CopyCallback method is called, it returns one of the three following values to indicate to the Shell how it should proceed.

Value | Description
IDYES | Allows the operation.
IDNO | Prevents the operation on this folder. The Shell can continue with any other operations that have been approved, such as a batch copy operation.
IDCANCEL | Prevents the current operation and cancels any pending operations.


Creating Search Handlers

The Shell supports several search utilities that allow users to locate namespace objects such as files or printers. You can create a custom search engine and make it available to users by implementing and registering a search handler.

The general procedures for implementing and registering a Shell extension handler are discussed in Creating Shell Extension Handlers. This document focuses on those aspects of implementation that are specific to search handlers.

  • How Search Handlers Work
  • Registering Search Handlers
  • Implementing Search Handlers

How Search Handlers Work

Users have two ways to select a search engine. The first way is from the Start menu. With systems earlier than Microsoft® Windows® 2000, selecting the Find command on the Start menu displays a submenu of the available search engines. With Windows 2000, the Start menu's Find command is renamed Search, but it displays the submenu of search engines in much the same way. The following illustration shows the submenu of search engines associated with the Start menu on a Windows 2000 system.

The Start menu's Search submenu

Users can also launch a search from Windows Explorer. On systems earlier than Windows 2000, they click the Find command on the Tools menu to display essentially the same menu as the one associated with the Start menu. However, Windows Explorer for Windows 2000 handles search engines in a very different way. Instead of handling search engines as a submenu of the Tools menu, there is now a Search button on the toolbar. Clicking this button opens the Explorer bar's Search pane. The following illustration shows the Search For Files And Folders search pane.

The Windows Explorer Bar's Search pane

There are a number of differences in how Windows 2000 and earlier systems manage search handlers that affect both implementation and registration.

Pre-Windows 2000 | Windows 2000 and later
Search handlers are implemented as a type of shortcut menu handler. | Search handlers can be implemented as shortcut menu handlers, or as DHTML documents.
Search handlers can be either static or dynamic. Static handlers are loaded only when they are selected by the user. Dynamic handlers are loaded by the Shell at startup and are not terminated until the Shell exits. | Handlers implemented as shortcut menu handlers can be either static or dynamic. Handlers implemented as DHTML documents must be static.
Search handlers appear on the Find submenu of the Start menu and the Find submenu of the Windows Explorer Tools menu. | Search handlers appear only on the Search submenu of the Start menu. To make a custom search pane available through the Windows Explorer menu bar, you must implement it as a band object. It is then listed on the Explorer Bar submenu of the Windows Explorer View menu.

Registering Search Handlers

Search handlers are registered under the file class's HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\FindExtensions subkey. From this point, the registration procedure depends on whether the handler is to be static or dynamic. For a general discussion of how to register Shell extension handlers, see Creating Shell Extension Handlers.

Registering a Static Search Handler

Static search handlers are loaded only when they are launched by the user. This approach works best for DLLs that are small and can be loaded quickly. If you are using DHTML to implement your handler, it must be static. To register a static extension handler, create a subkey named for the handler under the Static subkey of the FindExtensions subkey. The name is not used by the system, but it must not be identical to other search handler names under the FindExtensions subkey.

Shortcut menu-based search handlers

If your handler is implemented as a shortcut menu handler, set the default value of the handler's name subkey to the object's CLSID GUID. Under the handler's name subkey, create a subkey named 0 (zero) and set its default value to the string that will be displayed in the Search or Find submenu. You can enable keyboard shortcuts in the usual way, by preceding the shortcut character with an ampersand (&). You can have an optional small icon displayed to the right of the menu text by creating a DefaultIcon subkey under the 0 subkey. Set its default value to a string containing the path of the file containing the icon, followed by a comma, followed by the icon's zero-based index.

The following example registers the MySearchEngine search handler. The menu text is "My Search Engine", with M specified as the shortcut key. The icon is in C:\MyDir\MySearch.dll, with an index of 2.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            FindExtensions
              Static
                MySearchEngine={MySearchEngine CLSID GUID}
                  0=&My Search Engine
                    DefaultIcon=c:\MyDir\MySearch.dll,2

DHTML-based search handlers

With Windows 2000, you can also implement a search handler as a DHTML document. Its name is listed in the Search submenu of the Start menu. When the user selects it, it launches Windows Explorer with the Explorer bar opened to the search document. You can also specify a DHTML document to be displayed to the right of the Explorer bar. There is no way to launch a third-party handler from the default Search pane. Search engines can be launched directly from Windows Explorer, but only if they are implemented as as band objects.

To register a DHTML-based search handler, set the handler's name subkey to the string form of CLSID_ShellSearchExt (currently {169A0691-8DF9-11d1-A1C4-00C04FD75D13}) and create the following subkeys:

  1. Create a 0 (zero) subkey under the name subkey and set its default value to the menu text.
  2. To have an icon displayed next to the menu text, create a DefaultIcon subkey under 0 and set its default value to the icon's path and index.
  3. Create a SearchGUID subkey under 0. Assign a GUID to the DHTML document and set the default value of SearchGUID to its string form. This GUID does not need to be registered under HKEY_CLASSES_ROOT\CLSID.
  4. Create a Url subkey under SearchGUID. Set its default value to the path of the HTM document that will appear in the Explorer bar.
  5. Create a UrlNavNew subkey under SearchGUID. Set its default value to the path of the HTML document that will appear to the right of the Explorer bar.

The following example registers the MySearchEngine search handler implemented as a DHTML document. The menu text is "My Search Engine", with M specified as the shortcut key. The icon is in C:\MyDir\MySearch.dll, with an index of 2. The Explorer bar's DHTML document is C:\MyDir\MySearch.htm, and the document that will be displayed to the right of the Explorer bar is C:\MyDir\MySearchPage.htm.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            FindExtensions
              Static
                MySearchEngine={169A0691-8DF9-11d1-A1C4-00C04FD75D13}
                  0=&My Search Engine
                    DefaultIcon=c:\MyDir\MySearch.dll,2
                      SearchGUID={My Search GUID}
                        Url=C:\MyDir\MySearch.htm
                        UrlNavNew=\MyDir\MySearchPage.htm

Registering a Dynamic Search Handler

If your handler is implemented as a shortcut menu handler, you can also register it as a dynamic handler. In that case, it will be loaded with the Shell and will terminate only when the Shell exits. Dynamic search handlers respond much more quickly than static handlers when they are launched by the user. This approach works best if your handler's DLL might take a long time to load, or if it is likely to be called frequently.

Dynamic search handlers are registered under the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Explorer\FindExtensions subkey. Create a subkey of FindExtensions named for the handler, and set its default value to the handler's CLSID GUID. Menu icons are not supported for dynamic search handlers. The following example registers MySearchEngine as a dynamic search handler.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            FindExtensions
              MySearchEngine={MySearchEngine CLSID GUID}
                  0=&My Search Engine

Unlike static search handlers, you do not specify the menu text in the registry. When the handler is loaded, the Shell will call the handler's IContextMenu::QueryContextMenu method to add items to the Find or Search submenu.

Implementing Search Handlers

Search handlers can be implemented as shortcut menu handlers for all versions of Windows. For Windows 2000, they can also be implemented as DHTML documents.

For a general discussion of how to implement shortcut menu handlers, see Creating Shortcut Menu Handlers. Search handlers differ from standard shortcut menu handlers in only a few ways.

For static menu handlers, the Find or Search submenu is created from the information in the registry. There is no need to have the handler add a menu item, as a normal shortcut menu handler would. The Shell manages static menu handlers in the following way:

  • When the user launches the handler's menu item, the Shell loads the handler's DLL and calls IContextMenu::InvokeCommand to notify the handler to launch the search engine. The IShellExtInit::Initialize and IContextMenu::QueryContextMenu methods are not called.
  • When IContextMenu::InvokeCommand is called, the lpVerb member of the CMINVOKECOMMANDINFO structure that is passed in identifies the command. The low-order word of lpVerb is set to the numerical equivalent of the command's subkey name. Since this subkey is normally named 0, lpVerb is usually set to zero. The handler should then launch the search engine.

Dynamic search handlers are implemented in much the same way as normal shortcut menu handlers. The primary exception is that when IShellExtInit::Initialize is called, the pidlFolder and lpdobj arguments are set to NULL.

DHTML-based search handlers are implemented as a normal DHTML document. They can include any HTML, DHTML, or scripting technology that is supported by Microsoft® Internet Explorer.


Creating a Disk Cleanup Handler

Because applications continue to get larger, hard disk space is at a premium on many computers. Available space is also reduced by the many temporary files that applications create for backup or performance reasons. When disk space gets low, it becomes necessary to reduce the amount of space used by applications. Disk space can be freed using a variety of means including:

  • Deleting some files.
  • Compressing some files.
  • Moving some files to a backup disk or tape.
  • Transferring some files to a remote server.

Files that are good candidates for cleanup include:

  • Files that the user will never need again.
  • Temporary files that exist only for performance reasons.
  • Files that can be restored if needed from the installation CD.
  • Data files that have possibly been superseded by newer versions, such as old backup files.
  • Older files that have not been used in a long time.

Deletion is most appropriate for files that the user will never need again—for example, files that are temporarily cached for performance reasons. Deletion is also appropriate for files that are easily restored, such as graphics files that can be reloaded from an installation CD. Files that the user might need in the future or that would be difficult to reconstruct are better candidates for compression or backup.

Expecting a user to manually clean up the file system is not a good solution. The user may not know where many of the files are located, or how to recognize which ones can be safely removed. In addition, there's the risk that the user might delete essential files.

The Windows Disk Cleanup Utility

Starting with Microsoft® Windows® 98, the Windows operating system includes Disk Cleanup, a utility that makes it much easier for the user to manage available hard disk space. The Disk Cleanup utility is designed to free up as much disk space as possible and decrease the risk that the user will delete essential files accidentally.

Disk cleanup can be initiated in three ways:

  • The user can initiate disk cleanup by clicking Start; pointing to Program Files, Accessories, and System Tools; and then clicking Disk Cleanup.
  • The system notifies the user with a message box that unused disk space has reached critical mode. The threshold for critical mode depends on the size of the disk drive, but it is typically reached when unused disk space falls below 25-50 MB. The user is given the option of cleaning the disk manually or starting the Disk Cleanup utility.
  • The user can have the Windows Maintenance Wizard run the Disk Cleanup utility automatically at scheduled times.

The basic challenge inherent in disk cleanup is to free as much disk space as possible, without deleting essential files. Because there isn't a standard way to mark files for cleanup, no single application can reliably detect and clean up all unessential files. The Disk Cleanup utility solves this problem by splitting the cleanup operation between the disk cleanup manager and a collection of disk cleanup handlers.

When the Disk Cleanup utility is run, the user sees the following dialog box.

The disk cleanup manager is part of part of the operating system. It displays the dialog box shown in the preceding illustration, handles user input, and manages the cleanup operation. The actual selection and cleanup of unneeded files is done by the disk cleanup handlers shown in the disk cleanup manager's list box.

Each handler is responsible for a well-defined set of files. For example, the highlighted handler is responsible for cleaning up downloaded program files. The user has the option of enabling or disabling individual handlers by clicking their check box. By clicking the Settings button, which this handler has labeled "View Files," the user can request that the handler display a user interface (UI). The UI is typically a dialog box that allows the user to specify which files or classes of files to clean up, and which cleanup method to use.

Although Windows comes with a number of disk cleanup handlers, they aren't designed to handle files produced by third-party applications. Instead, the disk cleanup manager is designed to be flexible and extensible. Any developer can extend the available disk cleanup services by implementing and registering a disk cleanup handler.

All applications that produce temporary files can and should implement and register a disk cleanup handler. Doing so gives users a convenient and reliable way to manage the application's temporary files. When you implement the handler, you can decide which files will be affected, and determine how the actual cleanup will happen.

Implementation Basics

Cleanup handlers are in-process server Component Object Model (COM) objects. After implementing the required interfaces, you can choose how to select files, free disk space, and display the optional UI. A handler needs to perform these five basic tasks:

  • Initialize the handler object.
  • Scan the disk to determine how much disk space can be freed.
  • Display the optional UI to get feedback from the user about which files to clean up and how.
  • Do the cleanup.
  • Shut down.

To allow the disk cleanup manager to manage these tasks, a handler must export either IEmptyVolumeCache for Windows 98, or IEmptyVolumeCache2 for Microsoft® Windows 2000. Note that IEmptyVolumeCache2 inherits from IEmptyVolumeCache. Because IEmptyVolumeCache2 has only one additional method, InitializeEx, relatively little extra work is required to implement both. Unless your handler will only be used with one of these operating systems, it should export both interfaces.

To export these interfaces, you must implement six methods:

Initialize | Used by Windows 98 to initialize the handler.
InitializeEx | Used by Windows 2000 to initialize the handler (exported by IEmptyVolumeCache2 only).
GetSpaceUsed | Asks the handler how much disk space it can free.
Purge | Notifies the handler to start cleaning up files.
ShowProperties | Asks the handler to display its UI.
Deactivate | Notifies the handler that the disk cleanup manager is shutting down.

Initialize/InitializeEx

The two initialization methods are quite similar and are called when the Disk Cleanup utility is run. The Windows 98 disk cleanup manager calls its handler's IEmptyVolumeCache::Initialize method. The Windows 2000 disk cleanup manager, however, will try calling IEmptyVolumeCache2::InitializeEx first. The disk cleanup manager passes in information, such as the handler's registry key and the disk volume that is to be cleaned. The methods can return the display text and set one or more flags.

The primary difference between the two methods is how the display text for the disk cleanup manager is handled. These three strings can be specified:

Display | Name that will be displayed in the manager's list box.
Description | Descriptive text that is displayed below the manager's list box when the handler's name is highlighted.
AdvancedButtonText | Text for the optional Settings button that users can click to request that the handler display its UI.

For Initialize, the Display and Description strings can be specified by assigning values to the ppwszDisplayName and ppwszDescription parameters. If you set the parameters to NULL, the disk cleanup manager will display the default values from the registry. The Settings button text can only be specified in the registry. For more information, see Registering a Disk Cleanup Handler.

For InitializeEx, no text will be taken from the registry. You must specify the Display and Description text by assigning properly localized strings to the ppwszDisplayName and ppwszDescription parameters. If you choose to display the optional Settings button, you must specify the button text by assigning a value to the ppwszBtnText parameter.

The pdwFlags parameter contains a set of flags that are used by both Initialize and InitializeEx. Two flags can be set by the disk cleanup manager:

  • If the disk cleanup manager is being run on a schedule, it will set the EVCF_SETTINGSMODE flag in the pdwFlags parameter. You must, however, assign values to the ppwszDisplayName and ppwszDescription parameters. If this flag is set, the disk cleanup manager will not call GetSpaceUsed, Purge, or ShowProperties. The handler's Initialize or InitializeEx methods must handle scanning for unessential files and performing the cleanup. You should ignore the pcwszVolume parameter, and clean up any unneeded files regardless of what drive they are on. Because there is no opportunity for user feedback, only those files that are extremely safe to clean up should be touched.
  • If the EVCF_OUTOFDISKSPACE flag is set, the user's disk drive is critically short of space. The handler should be aggressive about deleting files, even if it results in a performance loss. The handler, however, should not delete files that would cause an application to fail or the user to lose data.

The remaining flags can be set by the disk cleanup handler and returned to the disk cleanup manager. The description for each flag gives a brief summary. For more information, see the method reference pages.

EVCF_HASSETTINGS | Set this flag if your handler has a UI to display, and the disk cleanup manager will display the Settings button. If the button is clicked, the manager will call ShowProperties.
EVCF_ENABLEBYDEFAULT | The handler is enabled by default. It will run every time a disk cleanup takes place, unless the user disables it by clearing its check box in the disk cleanup manager's list of handlers.
EVCF_ENABLEBYDEFAULT_AUTO | The handler is automatically enabled to run during scheduled cleanups.
EVCF_REMOVEFROMLIST | After the handler has been run, delete its name from the list of available handlers.
EVCF_DONTSHOWIFZERO | Only display the handler in the list box if the value returned by GetSpaceUsed indicates that the handler can free some disk space.

GetSpaceUsed

The disk cleanup manager calls this method to find out how much space a disk cleanup handler can free. It displays the returned value to the right of the handler's name in the list box. When this method is called, the handler should scan its files, determine which of them are cleanup candidates, and return the amount of disk space that it can free.

Because scanning can be a lengthy process, the disk cleanup manager uses the picb parameter to pass in a pointer to its IEmptyVolumeCacheCallBack interface handle. The handler should use the interface periodically during the scan to call IEmptyVolumeCacheCallBack::ScanProgress.

The ScanProgress method serves two purposes:

  • The disk cleanup manager displays a progress bar to keep the user informed about how the scan is progressing. Calling ScanProgress periodically allows the manager to update the progress bar.
  • The user may decide to stop the scan by clicking the Cancel button. When this happens, the handler is not notified. Instead, the disk cleanup manager returns E_ABORT the next time ScanProgress is called. To detect a cancellation, the handler must query the manager by calling ScanProgress.

Purge

The disk cleanup manager calls the handler's Purge method to notify it to start cleaning up its files. The handler should then start doing whatever is necessary to free disk space. The disk cleanup manager uses the picb parameter to pass in a pointer to its IEmptyVolumeCacheCallBack interface. As with GetSpaceUsed, the handler should use the interface periodically to report its progress and query the manager to see if the user has clicked Cancel. However, the Purge method must call IEmptyVolumeCacheCallBack::PurgeProgress instead of IEmptyVolumeCacheCallBack::ScanProgress.

ShowProperties

Before starting cleanup, the handler may display a UI to get feedback from the user. The UI is typically in the form of a dialog box that allows the user to select which files or classes of files are to be cleaned up, and what should be done with them. If the handler sets the EVCF_HASSETTINGS flag when Initialize or InitializeEx is called, the user can request the UI by clicking the disk cleanup manager's Settings button.

When the Settings button is clicked, the disk cleanup manager will call ShowProperties to prompt the handler to display the UI. It should create the UI as a child of the window whose handle is passed in the hwnd parameter.

Deactivate

The Deactivate method is called when the disk cleanup manager is preparing to shut down. The handler should perform any needed cleanup tasks and return. If you don't want the handler to be run again, set the EVCF_REMOVEFROMLIST flag. If this flag is set, the disk cleanup manager will remove the handler from its list and delete its registry entries. You must reestablish the registry entries to run the handler again. This flag is typically used for handlers that will run only once.

Registering a Disk Cleanup Handler

To add a handler to the disk cleanup manager's list, it must be properly registered.

As with all COM objects, the handler object's globally unique identifier (GUID) and dynamic-link library (DLL) must be registered under under CLSID in HKEY_CLASSES_ROOT. You can also register an icon that will be displayed next to the handler's name in the disk cleanup manager's list box. The following example shows a typical registry entry.

HKEY_CLASSES_ROOT
  CLSID
   {Handler's GUID}
     InprocServer32
       (Default) = "DLL pathname"
       ThreadingModel = "Apartment"
     DefaultIcon = "Icon Pathname","Icon Index"

Registering a Handler with the Disk Cleanup Manager: Windows 98

To register a handler with the disk cleanup manager, you must also create a subkey for the handler in the following registry path:

HKEY_LOCAL_MACHINE/Software/Microsoft/Windows/CurrentVersion/Explorer/VolumeCaches

In addition to the CLSID, there are a several values that can be created under the handler's subkey:

  • Required. The GUID for the handler's CLSID.
  • Optional. The Display value, which specifies the default display name that will appear in the disk cleanup manager's list of handlers.
  • Optional. The Description value, which specifies the default descriptive text that will appear below the disk cleanup manager's list of handlers when the handler is selected.
  • Optional. The AdvancedButtonText value, which specifies the text for the Settings button. If no text is specified, it will be labeled "Settings".

You can override the Display and Description registry entries by specifying alternate strings when the handler's IEmptyVolumeCache::Initialize method is called. If you omit Display and Description from the registry, you must provide values when IEmptyVolumeCache::Initialize is called. For Windows 98, the optional AdvancedButtonText string can only be specified in the registry.

The following example shows how to register a Windows 98 disk cleanup handler.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            VolumeCaches
              Handler_Name
                (Default) = {CLSID GUID}
                Display = "Title"
                Description = "Some descriptive text"
                AdvancedButtonText = "Settings button text"

Registering a Handler with the Disk Cleanup Manager: Windows 2000

Specifying display text in the registry can make it difficult to localize software. For this reason, Windows 2000 supports the IEmptyVolumeCache2 interface. The preferred initialization method is IEmptyVolumeCache2::InitializeEx, which will be called first. The system will only use IEmptyVolumeCache::Initialize to initialize a handler if IEmptyVolumeCache2 is not exposed.

Register the handler as you do for Windows 98, but omit the Display, Description, and AdvancedButtonText values. Instead, provide properly localized text to the disk cleanup manager when it calls IEmptyVolumeCache2::InitializeEx.


Customizing a Folder's Web View

A Web view is a powerful and flexible way to use the Windows Explorer to display information about the contents of a Shell folder.

  • Introduction
  • Using the Web View Template

Introduction

Microsoft® Windows® offers users two primary ways to view and navigate the Shell namespace. The most familiar of these, the Classic style, is similar to the familiar Windows File Manager. The right pane lists the contents of the currently selected folder in one of five formats: Large Icon, Small Icon, List, Details, and Thumbnail. The major difference from Windows File Manager is the left pane, which looks very similar to the Explorer bar of Microsoft® Internet Explorer. It can be resized or removed, and it can display several panes in addition to the familiar file system tree, such as a search pane.

The following illustration shows the Printers folder in Classic style.

Classic style of the Printers folder.

The Classic style works reasonably well for normal file system folders and files. However, with the introduction of Windows 95, the file system has evolved into the namespace. The namespace allows the creation of virtual folders, such as Printers or Network Neighborhood, that can represent very different types of information than a normal file system folder.

The Web style, also known as a Web view, offers a more flexible and powerful way of presenting information than Classic style. In a Web view, the user basically views and navigates the namespace using Internet Explorer. The basic layout of a Web view is similar to Classic style. The Explorer bar is unchanged. However, the region that was occupied by the file list becomes a general-purpose display area that is effectively a Web page. A Web view is still used to display information about the contents of a folder, but there are few constraints on what information is displayed, or how. Each folder can have its own Web view, customized to suit its particular features.

The following illustration shows a Web view of the Printers folder (shown previously in Classic style).

Default Web view of the Printers folder.

Much like conventional Web pages, Web views are controlled by an HTML-based template. Authoring a Web view template is nearly identical to authoring a Web page and provides the same degree of flexibility in content and layout of information. Web view templates can use DHTML and scripting to respond to events, such as a user clicking an item. They can also host objects that allow them to obtain and display information from the folder or its contents.

The user can choose a Web view by starting Windows Explorer, clicking Folder Options on the View menu, and selecting this option: Enable Web content in folders. However, the user can also start Internet Explorer and point the browser at the file system by clicking the View menu, pointing to Explorer Bar, and clicking Folders. In a Web view, there is virtually no difference between Internet Explorer and Windows Explorer.

On the left side of the right pane, the Printers Web view displays a banner with the folder's name and icon, followed by a block of information about the folder. The usual file list occupies the right side of the page.

When a user clicks an item, detailed information about the item appears in the information block. The Printers Web view actually displays much the same information that is available in Classic style, but it does so in a more usable format. However, a Web view is not simply a different way to display Classic style information. For example, a link to a useful Web site can be displayed below the information block, a feature that is not available in Classic style. If the user clicks the link, the site will be displayed.

The Printers Web view shown in the preceding illustration is similar to the Classic style, because the underlying Web view template (an .htt file) was written that way. The list of files, for instance, is not generated by the Web view template directly. It is created and displayed by a WebViewFolderContents object hosted by the Web view template. The object's methods and properties allow the Web view to control its layout and obtain information about particular items. The content and layout of the banner and information block is specified in the Web view template.

Because a Web view supports DHTML, the template can also be used to handle user interaction. For instance, when a user clicks one of the printer icons, the WebViewFolderContents object fires a SelectionChanged event. The template uses a DHTML event handler written in script to retrieve the requested information and display it in the information block.

This simple example for the Printers folder is by no means the only way to use a Web view. By writing your own template and, if necessary, objects, you can use a Web view to display information and interact with the user in whatever way you find most effective. Note that, at present, Web view templates only display system-defined virtual folders. Although third-party developers can create a virtual folder by implementing a namespace extension, they must use the techniques described in Creating a Shell Namespace Extension to display it.

Using the Web View Template

The way data is displayed in a Web view can be customized in a limited way by modifying a folder's Desktop.ini file. See Customizing Folders with Desktop.ini for details. A much more flexible and powerful way to customize a Web view is to create a custom Web view template.

The Web view template controls what is displayed in a Web view and how. It uses standard HTML, DHTML, and scripting techniques to obtain and display information and interact with the user. This section discusses how to create a Web view by examining a simple template, Generic.htt.

A simple way to create your own Web view template is to take Generic.htt and modify it. Because it is rather limited, you should also look at other, more complex examples for additional ideas. You can find them by searching your system for the .htt extension used by all Web view templates. If you want to create a custom template for a folder, you should start with the default Folder.htt template, which is usually stored in either C:\Winnt\Web or C:\Windows\Web. Note that these files are defined as hidden, so you may need to modify your Explorer settings to view them. Once an .htt file is created, it should be marked as read-only and hidden.

Web view templates use the .htt extension because they differ slightly from conventional .htm documents. The main difference is several special variables in .htt files that the system replaces with the current namespace values. The %THISDIR% and %THISDIRPATH% variables represent the name and path of the currently selected folder. The %TEMPLATEDIR% variable represents the folder where the Web view style sheets are stored.

Like most HTML templates, .htt files have two basic parts: a body and a head. The template body controls the basic layout of the Web view and loads the objects used to communicate with the namespace and display information. The head contains scripts and functions that do tasks such as handling resizing and obtaining information from the folder. Most templates, including Generic.htt, also include a style sheet. In general, it is better to include the style sheet information in your template. Separate style sheets may not work properly when a Web view is used with remote namespaces.

The Template Body

The body of the template specifies what will be presented by a Web view. It is also where the objects used to display information and communicate with namespace folders are loaded. The layout defined by Generic.htt is similar to that shown in the illustration in the previous section. There are three display regions: the banner and information block on the left side of the view, and the file list on the right.

The regions are all assigned identifiers to be used by the style sheet and DHTML. As discussed in the next section, there are two possible banners, with identifiers of "Banner" and "MiniBanner". The identifier of the information block's region is "Info". The file list object's identifier is "FileList". The details of the region's layout are handled by the style sheet and a JScript® function, FixSize, which is discussed later in the chapter.

The Banner Region

The banner is located at the top of the display, in the upper-left corner of the Web view. The normal banner displays the name and icon of the folder whose contents are displayed in the file list on the right. However, if the window becomes too short, there may be no room below the icon to display information. For this reason, Generic.htt also defines a minibanner that only displays the folder name. Both banners are initially defined as hidden. FixSize chooses which one to display and sets it to "visible".

The normal banner for Generic.htt is defined by:

<div id="Banner" style="visibility: hidden">
    <table><tr><td nowrap>
    <p class=Title style="margin-left: 104px; margin-top: 16px">
        %THISDIRNAME%
    </td></tr></table>
    <hr id="Rule" size=1px color=black style="position: absolute; top: 44px; left: 84px">
    <object id=Icon classid="clsid:e5df9d10-3b52-11d1-83e8-00a0c90dc849">
        <param name="scale" value=200>
    </object>
</div>

The first part of the banner section displays the title with a horizontal rule underneath it. Table tags are used to control its position. The nowrap attribute is set for the <TD> tag to prevent word wrapping. The system will replace %THISDIRNAME% with the name of the current folder. A WebViewFolderIcon object, with an identifier of "Icon" for simplicity, is then loaded to extract and display the folder's icon.

The minibanner section is similar to the normal banner. The format of the title is placed slightly higher and does not have a rule. Because there is no icon, the WebViewFolderIcon object is not loaded.

<div id="MiniBanner" style="visibility: hidden">
    <table><tr><td nowrap>
        <p class=Title style="margin-left: 16px; margin-top: 4px">
        %THISDIRNAME%
    </td></tr></table>
</div>

The Info Region

The portion of the Web view below the banner is used to present detailed information about the selected item. If no item is selected, a default message is shown. Because Generic.htt only displays a single block of text, this section is quite simple.

<div id="Info">
    <p style="margin-top: 16px");
        <span id="TextBlock">
        </span>
</div>

Most of the work of collecting the information is handled by a folder information script that is discussed later in the chapter. It displays the information by assigning the text to TextBlock.innerHTML.

You can easily customize the information display by modifying these elements or including additional ones. Anything that you can put on a Web page can be used. For example, to display a link to your Web site, you can add an anchor element after the text block in Generic.htt.

<div id="Info">
    <p style="margin-top: 16px");
        <span id="TextBlock">
        </span>
        <span>
        <p> Click on <ahref="http://your.address"></a>
        </span>
</div>

The FileList Region

Finally, Generic.htt loads a WebViewFolderContents object for the FileList region. Because its identifier is set to "FileList", it will be referred to as the FileList object from now on.

        <object id="FileList" border=0 tabindex=1 classid="clsid:1820FED0-473E-11D0-A96C-00C04FD705A2"
        </object>

The FileList object is found in most Web views and serves several purposes. FileList displays the list of items contained by the selected folder with the same options and appearance as the file list in Classic style. When an item is selected, FileList notifies the Web view by firing a SelectionChanged event. FileList also exposes methods and properties that can be used to retrieve information about individual items and control the position and size of its display area.

Although the FileList object is very useful, it only returns standard file system information, such as file size or attributes. To retrieve other kinds of information from a Shell folder, you will have to load and handle additional objects. Any object that can be hosted by a Web page can be used with a Web view.

The Template Head

The head of the Web view template contains the scripts and functions that do most of the actual work. There are two essential tasks that need to be handled. One is the layout of the Web view display, which needs to be adjusted to accommodate different display regions. The other is retrieving and displaying information from the folder when an item is selected. As with style sheets, it is better to include all scripts and functions in the template instead of referencing them as separate files.

Controlling the Web View Layout

The area available for a Web view depends on the size of the Web view window and how much of it is taken up by the Explorer bar. This area will change anytime the window or Explorer bar is resized. So the layout needs to be matched to the available area when a Web view is loaded and change appropriately when it is resized. Much of the layout is specified in the style sheet. The Info region, for example, is defined to occupy the leftmost 30 percent of the Web view.

#Info		{position: absolute; top: 88px; width: 30%; background: window;
    overflow: auto}

As a Web view is resized, the width of the Info region will change to maintain that percentage. FixSize manages the layout issues that can't be handled by a style sheet.

Loading and Initializing the Web View

When a Web view is loaded, the layout needs to be adjusted to fit the available display area. Because no item has been selected yet, Web views normally display some default information that applies to the whole folder. To handle initialization, the <BODY> tag for Generic.htt detects the onload event and calls the Init function.

<body scroll=no onload="Init">

Init is a simple JScript function.

function Init() {
    window.onresize = FixSize;
    FixSize();
    TextBlock.innerHTML = L_Intro_Text;
}

Init binds FixSize to the window.onresize event so that it will be called whenever the Web view display area changes. It then runs FixSize to set the initial layout and assigns L_Intro_Text to the Info region. L_Intro_Text is a block of introductory text that is defined in the style sheet section.

var L_Intro_Text	= "This folder contains a variety of interesting stuff.<br>
<br>To get information about any of them, click the items icon.<br><br>";

Adjusting the Layout by using the FixSize function

The FixSize function is used to specify several aspects of the layout that can't be handled by the style sheet.

There are two possible banners that can be used, depending on the height of the Web view.

if (200 > document.body.clientHeight) {
    //A short window. Use the minibanner.
    document.all.Banner.style.visibility = "hidden";
    document.all.MiniBanner.style.visibility = "visible";
    document.all.FileList.style.top = 32;
    document.all.Info.style.top = 32;
}
else {
    //A normal window. Use the normal banner.
    document.all.Banner.style.visibility = "visible";
    document.all.MiniBanner.style.visibility = "hidden";
    document.all.FileList.style.top = (document.all.Banner.offsetHeight - 32) + "px";
    document.all.Info.style.top = (document.all.Banner.offsetHeight) + "px";
    document.all.Rule.style.width = (document.body.clientWidth > 84 ? document.body.clientWidth - 84 : 0) + "px";
}

Generic.htt uses a height of 200 pixels as the dividing line between normal and minibanners. It sets the style of the selected banner to visible and the other to hidden. It also sets several layout properties for the Info and FileList regions so that they fit properly with the selected banner.

If a Web view becomes too narrow, FixSize uses the full width of the display area for the FileList display.

if (400 > document.body.clientWidth) {
    //A narrow window. Hide the Info region, and expand the file list region.
    document.all.Info.style.visibility = "hidden";
    document.all.FileList.style.pixelLeft = 0;
    document.all.FileList.style.pixelTop = document.all.Info.style.pixelTop;
}

else {
    //Normal width.
    document.all.Info.style.visibility = "visible";
    document.all.FileList.style.pixelLeft = document.all.Info.style.pixelWidth;
}

Generic.htt uses 400 pixels as the dividing line between narrow and wide displays. If the Web view is too narrow, FixSize hides the Info region and modifies the FileList pixelLeft property so that it fills the entire region below the banner.

The final few lines of FixSize adjust several layout properties based on the results of the preceding code. The width of the FileList region is adjusted so that it exactly fills the portion of the Web view not occupied by the Info region. The height of the Info region is sized to fit between the banner and the bottom of the Web view.

document.all.FileList.style.pixelWidth = document.body.clientWidth
    document.all.FileList.style.pixelLeft;
document.all.FileList.style.pixelHeight = document.body.clientHeight
    document.all.FileList.style.pixelTop;
document.all.Info.style.pixelHeight = document.body.clientHeight
    document.all.Info.style.pixelTop;

Retrieving and Displaying Folder Information

When a user selects an item, the FileList object fires a SelectionChanged event. This event is handled by a JScript script. For simplicity, the script found in Generic.htt assumes that only one item can be selected at a time.
<script language="JavaScript" for="FileList" event="SelectionChanged">
    // Updates the TextBlock region when an item is selected.
    var data;
    var text;

    // Name
    text = "<b>" + FileList.FocusedItem.Name + "</b>";

    // Comment
    data = FileList.Folder.GetDetailsOf(FileList.FocusedItem, 3);
    if (data)
        text += "<br>" + data;

    // Documents
    data = FileList.Folder.GetDetailsOf(FileList.FocusedItem, 1);
    if (data)
        text += "<br><br>" + FileList.Folder.GetDetailsOf(null, 1) + ": " + data;

    // Status
    data = FileList.Folder.GetDetailsOf(FileList.FocusedItem, 2);
    if (data)
        text += "<br><br><b><font color=red>" + data + "</font></b>";

    // Tip
    data = FileList.Folder.GetDetailsOf(FileList.FocusedItem, -1);
    if (data != "" && data != FileList.FocusedItem.Name)
        text += "<br><br>" + data;

    TextBlock.innerHTML = text;
</script>

The script uses two FileList properties, FileList.FocusedItem and FileList.Folder to obtain information about the item. FileList.FocusedItem identifies the selected item, with the item's name given by FileList.FocusedItem.Name. FileList.Folder is actually a pointer to a Folder object. The Folder object's GetDetailsOf method is used to retrieve the remaining information about the item.

All the information is concatenated into a single text string, separated by <BR> tags for readability. The text is then displayed by assigning it to TextBlock.innerHTML.

Summary

This chapter outlines some of the techniques you can use to customize the way the Windows Explorer displays information about Shell folders. Creating a Desktop.ini file allows you to do some simple customization, such as displaying a custom icon in place of the standard folder icon. When a folder appears in a Web view, its layout and display are controlled by an HTML-based template that determines what information is displayed and how. You can exercise a high degree of control over a folder's Web view by using standard HTML, DHTML, and scripting techniques to create a custom template.


Advanced Shell Techniques

The Shell Basics and Intermediate Shell Techniques sections discuss a variety of ways to use the Shell API and extend the Shell's capabilities. This section covers a variety of additional ways to extend the Shell.

The first item in this section discusses how you can integrate your data with the Shell by creating a custom virtual folder and adding it to the Shell namespace. The remaining sections discuss specialized Shell topics.

  • Creating a Shell Namespace Extension
  • Creating Custom Explorer Bars, Tool Bands, and Desk Bands
  • Using the Active Desktop Object
  • Creating Control Panel Applications
  • Handling Screen Savers
  • Creating Briefcase Reconcilers
  • Handling Online Help

Note To improve the readability of the sample code in the Advanced Shell Techniques documentation, most of the normal error-correction code has been removed. You should add error code, as appropriate, to your own applications. To make registry samples more readable, key names are in a bold font and values and data are in a normal font.


Creating a Shell Namespace Extension

Microsoft® Windows® Explorer provides the user with a graphical representation of the Shell namespace. It displays the structure and contents of the namespace and gives users the ability to easily perform a wide variety of tasks.

Developers have numerous ways to customize how Windows Explorer displays the folders and files that make up the namespace. For the file system portion of the Shell namespace, developers can modify the appearance and behavior of objects by adding registry keys or special files or by implementing a Shell extension handler. For further discussion, see Shell Basics and Creating Shell Extension Handlers. A more flexible and powerful way to extend Windows Explorer is to display your information in a custom virtual folder or namespace extension.

  • Namespace Extensions
  • Specifying a Namespace Extension's Location
  • Displaying a Self-Contained View of a Namespace Extension
  • Implementing the Basic Folder Object Interfaces
  • Implementing a Folder View


Namespace Extensions

Microsoft® Windows® Explorer provides a graphical representation of the Shell namespace combined with tools that allow users to interact with Shell objects. With a namespace extension, you can take any body of data and have Windows Explorer present it to the user as a virtual folder. When a user browses into this folder, your data is presented as a tree-structured hierarchy of folders and files, much like the rest of the Shell namespace. Users and applications are able to interact with the contents of this virtual folder in much the same way as with any other namespace object. This document discusses how to create a namespace extension.

  • How a Namespace Extension Works
  • How Windows Explorer Interacts with a Namespace Extension

How a Namespace Extension Works

Behind the scenes, every folder that Windows Explorer displays is represented by a COM object called a folder object. Each time the user interacts with a folder or its contents, the Shell communicates with the associated folder object through one of a number of standard interfaces. The folder object then does whatever is necessary to respond to the user's action, and the Shell updates the Windows Explorer display.

The majority of the files and folders that users interact with are part of the file system or a system virtual folder such as the Recycle Bin. Other documentation has discussed how you can customize the behavior of these standard folders to meet the requirements of your application by modifying the registry or by implementing Shell extension handlers. However, extending the Shell in these ways is most useful when your information can be readily packaged in the form of normal file system files or folders.

There are a number of situations where storing data as a collection of file-system folders and files might be undesirable or even impossible. Some examples of this type of data include:

  • A collection of items that is most effectively packaged in a single file, such as a database.
  • A collection of items stored on a remote computer that does not have a standard Windows file system. An example of such data is the information stored on a personal digital assistant (PDA) or digital camera.
  • A collection of items that does not represent stored data. An example of such data is the printer links contained by the standard Printers folder.

One way to present this kind of data to a user is to write an application to allow users to view and interact with the various items. However, if your data can be presented as a folder/file hierarchy, much of the functionality you will need to implement might be user interface services that are already provided by Windows Explorer. A much more efficient approach could be to write a namespace extension and let Windows Explorer become your graphical user interface (GUI).

To implement a namespace extension, your information must be organized as a tree-structured namespace. Your namespace root is presented as a virtual folder in the Shell namespace. The root folder, and all its subfolders and data items, becomes part of the Shell namespace, and Windows Explorer becomes your user interface. You can thus present your information to the user in a familiar and readily accessible way with much less UI programming than would be required for a custom application.

A namespace extension consists of two basic components:

  • A data manager
  • An interface between the data manager and Windows Explorer

The first component on the list is entirely up to you. You can store and manage your data in whatever way is most effective. The second component is the code needed to package your data as folder objects and handle the interaction with Windows Explorer. Windows Explorer can then call these objects to allow users to view and interact with your data as if it were a collection of folders and files. Your namespace extension's folder objects must interact with Windows Explorer as if they were normal folders. Before attempting to implement a namespace extension, you must first understand how Windows Explorer handles a folder object.

How Windows Explorer Interacts with a Namespace Extension

Windows Explorer provides users with a GUI that allows them to do a variety of tasks, including:

  • Navigating the namespace hierarchy and viewing the contents of folders.
  • Managing the contents of the namespace by moving, deleting, and copying objects.
  • Retrieving a variety of information about objects.
  • Launching applications.

The Windows Explorer GUI has five basic components. The following illustration names the components and shows where they are typically displayed within Windows Explorer.

When a user displays a folder belonging to a namespace extension in Windows Explorer, the folder object has at least partial control over the contents of all five regions.

Tree View

The tree view provides a high-level view of the namespace. This region hosts a tree view control that can display every namespace folder and the folder's position in the namespace hierarchy. A user can perform several operations with the tree view region, including:

  • Displaying or hiding the next level in the namespace.
  • Copying, moving, or deleting folders.
  • Right-clicking a folder to display a shortcut menu.
  • Selecting a folder and viewing its contents in the folder view.

The tree view communicates with folder objects primarily through their IShellFolder interface. For example, when a user clicks the plus sign (+) next to the folder's icon, Windows Explorer expands the display to show the folder's subfolders. To obtain the information needed to update the tree view, the Shell makes several calls to the folder object's IShellFolder interface to:

  • Request the folder's attributes.
  • Enumerate the contents of the folder.
  • Request display names for each subfolder.
  • Request an icon to display next to each folder.

Windows Explorer then updates the tree view to show the selected folder's subfolders. If the subfolders have subfolders, a + is displayed next to their folder icon. There are a number of more sophisticated tasks that a user can also perform with the tree view, including:

  • Using the Clipboard to cut or copy a folder and paste it into another folder.
  • Using drag-and-drop to cut or copy a folder and drop it on another folder.
  • Using a search engine to search for items in a folder or its subfolders.
  • Modifying the folder's properties.

For a more detailed discussion of how a namespace extension handles these user actions, see Implementing the Basic Folder Object Interfaces.

Folder View

When a user selects a folder, the contents of the folder are displayed in the folder view. To some extent, the normal functionality of the folder view overlaps with the tree view. Users can move or copy folders, change folder properties, view the contents of a subfolder, display a shortcut menu for a folder, and so on. However, there are some distinct differences between tree view and folder view:

  • Folder view displays only the contents of a single folder, not part or all of the namespace hierarchy.
  • Folder view displays file objects as well as folder objects.
  • Folder view can display much more information about objects than tree view.
  • Folder view allows namespace extensions to have almost complete control over what information is displayed and how. Only minor aspects of the tree view, such as folder icons, can be modified.

Unlike the tree view, Windows Explorer does not directly control the contents of the folder view. The folder view is an area that Windows Explorer provides to folder objects. Displaying and managing the contents of a folder in the folder view are the responsibility of the folder object. Although most folder views follow a fairly standard format, there are actually few limitations on what can be displayed or how. An extreme case is the Internet folder, which is a full-featured Web browser.

When a user selects a folder that belongs to your namespace extension, you create a window and pass its handle to Windows Explorer. This window becomes a child of the folder view window. Windows Explorer provides the dimensions of the folder view window but places no restrictions on the content of your child window. You can then use the child window to display the folder's folder view.

Namespace extensions use one of two approaches for creating a folder view:

  • Use your child window to host a list view common control. This control allows you to display the contents of a folder in much the same way as the Windows Explorer classic view.
  • Use your child window to host a WebBrowser control and use a DHTML document to display the contents of the folder.

Both approaches display a folder view that looks very much like that displayed for system folders. However, if you want to use a different display scheme, you are free to do so.

Menu Bar and Toolbars

Like most Windows applications, Windows Explorer provides the user with a collection of tools. A complete selection of tools is available through the menu bar. The more commonly used tools are also represented by buttons or edit boxes on a toolbar. Unlike many Windows applications, the Windows Explorer menu bar is actually a toolbar control that has been customized to behave like a conventional menu. Both the menu bar and the toolbar are incorporated into a rebar control to allow users to organize the individual controls to suit their needs.

By default, Windows Explorer supports a standard set of buttons and menu items, such as Copy and Properties. Your namespace extension can customize the menu bar and toolbars by deleting standard tools and adding custom tools. When your folder view object is initialized, Windows Explorer passes a pointer to its IShellBrowser interface. This interface supports several methods that you can call to customize the menu bar and toolbar. When the user selects one of your custom menu items or toolbar buttons, Windows Explorer forwards WM_COMMAND messages for custom menu and toolbar items to your child window's window procedure.

Status Bar

The Windows Explorer status bar displays information about the currently selected object. Your namespace extension can use the status bar to display status information, such as a text string. You can customize the status bar by calling the IShellBrowser interface.


Specifying a Namespace Extension's Location

The root of a namespace extension is normally displayed by Microsoft® Windows® Explorer as a folder in both tree and folder views. For Windows Explorer to display your extension's files and subfolders, you must specify where the root folder is located in the Shell namespace hierarchy. This location is referred to as a junction point.

  • Using Virtual Folders as Junction Points
  • Using File System Folders as Junction Points
  • Opening a View of a Namespace Extension

Using Virtual Folders as Junction Points

The simplest way to define an extension's junction point is to make the root folder a subfolder of a system virtual folder. This type of junction point is referred to as a virtual junction point. The Desktop and My Computer folders are the typical locations for virtual junction points, but you can also define a virtual junction point on a remote computer or under the My Network Places, Internet Explorer, and Control Panel folders.

To define a virtual junction point, create a subkey of the key that represents the appropriate virtual folder and name it with the string form of your extension's CLSID. The registered CLSID would appear as follows.

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          Explorer
            Virtual Folder Name
              Namespace
                {Extension CLSID}

Virtual Folder Name is one of the registry key names in the following table.

Location | Virtual Folder Name
My Computer | MyComputer
Desktop | Desktop
Control Panel | ControlPanel
My Network Places | NetworkNeighborhood
Entire Network | NetworkNeighborhood\EntireNetwork
Remote Computer | RemoteComputer

Remote extensions must be initialized with IRemoteComputer.

Note You can also define junction points on a per-user basis by registering them in the equivalent location under the HKEY_CURRENT_USER key.

Using File System Folders as Junction Points

There are two ways to define file system folders as junction points. The simplest approach is to create a folder in the appropriate location and append a period to the folder's name, followed by the string form of the CLSID of your extension. Only the folder name will be visible in Windows Explorer. The following example creates a junction point with a display name of MyFolder.

MyFolder.{Extension CLSID}

Alternatively, you can define a conventionally named folder as a junction point by:

  • Making the folder read-only.
  • Making the folder a system folder by calling PathMakeSystemFolder.
  • Placing a hidden Desktop.ini file in the folder that includes the extension's CLSID.

Desktop.ini is a standard text file that can be added to any folder to customize certain aspects of the folder's behavior. For a general discussion of how to use this file, see Customizing Folders with Desktop.ini. To define a folder as a junction point, the [.ShellClassInfo] section of Desktop.ini must contain the extension's CLSID as follows:

[.ShellClassInfo]
CLSID={Extension CLSID}

Opening a View of a Namespace Extension

When a user browses into a junction point, Windows Explorer automatically creates a view of the root folder. You can also create a view by explicitly launching Explorer.exe with the extension's CLSID as an argument. You can, for instance, use this approach to launch a view of an extension from a shortcut menu or shortcut. For example, to launch a view of MyExtension that includes a tree view, you can use the following command string.

%SystemRoot%\Explorer.exe /e,::{MyExtension CLSID}

An alternative command string can be used to launch a view of an object within the extension. This feature would be useful, for instance, for an extension that uses a folder view to allow users to view the contents of one of a number of compressed files.

%SystemRoot%\Explorer.exe /e,::{MyExtension CLSID},objectname

The objectname parameter is the name of the object that is to be viewed. Windows Explorer converts the name to its corresponding PIDL and passes the PIDL to the new folder object's IPersistFolder::Initialize method.

Note The CLSID string must be preceded by a pair of colons (::) or the command will fail. The slash-e (/e) flag used in the two sample command lines shown previously instructs Windows Explorer to display a tree view. The flag must be separated from the two colons by a comma. If you do not want a tree view, omit the /e flag and the comma.


Displaying a Self-Contained View of a Namespace Extension

Most namespace extensions are a subset of the Shell namespace. When you create a junction point, as described in Specifying a Namespace Extension's Location, Microsoft® Windows® Explorer allows users to navigate into and out of your namespace extension just like any other folder. However, it is also possible to use Windows Explorer to display only the contents of your namespace extension. This display option is sometimes referred to as a rooted view. Although not commonly used, rooted views might be preferable to normal views for some types of extensions.

With a rooted view, a new instance of Windows Explorer is created that displays the contents of the extension as a separate namespace. The tree view of a rooted view shows only those folders that are part of the extension. Users cannot navigate from a rooted view to other parts of the Shell namespace.

Extensions are implemented in the same way for rooted views as they are for normal views. The only difference is in the way the contents of the extension are displayed by Windows Explorer. It is even possible to have normal and rooted views of the same extension.

To open a view of an extension, you must launch an instance of Explorer.exe with a /root flag. There are several different ways to launch a rooted view, depending on the nature of your extension.

  • Using a Junction Point to Open a Rooted View
  • Using a Shortcut File to Open a Rooted View
  • Displaying a Rooted View of a File

Using a Junction Point to Open a Rooted View

Typically, clicking or double-clicking the folder that represents a junction point opens a normal view of the contents of the associated extension. However, you can use the registry to specify that browsing into a junction point will open a rooted view. To do so, add Open and Explore command keys to your extension's CLSID registry key.

HKEY_CLASSES_ROOT
  CLSID
    ...
    {Extension CLSID}
      ...
      Shell
        Open
          Command==%SYSTEMROOT% \explorer.exe/e,/root,"%1"
        Explore
          Command==%SYSTEMROOT% \explorer.exe/e,/root,"%1"

When the user clicks or double-clicks the junction point, an instance of Explorer.exe is launched to display the contents of the extension as a rooted view.

Using a Shortcut File to Open a Rooted View

Another approach to launching a rooted view is to create a shortcut file and set the command to Explorer.exe with a /root flag. The exact form the command takes depends on the location of the junction point:

  • If the junction point is a subfolder of the Desktop, use:
    Explorer.exe /e,/root,::{Extension CLSID}
  • If the junction point is a file system folder, use:
    Explorer.exe /e,/root,[Fully qualified path to the folder]
  • If the junction point is a subfolder of a system virtual folder, use:
    Explorer.exe /e,/root,::{Folder CLSID}\::{Extension CLSID}

The system virtual folders that can contain junction points have the following CLSIDs.

My Computer | {20D04FE0-3AEA-1069-A2D8-08002B30309D}
My Network Places | {208D2C60-3AEA-1069-A2D7-08002B30309D}
Control Panel | {21EC2020-3AEA-1069-A2DD-08002B30309D}
Internet Explorer | {871C5380-42A0-1069-A2EA-08002B30309D}

Note Systems earlier than Microsoft® Windows® 2000 use a display name of Network Neighborhood instead of My Network Places. However, the CLSID is the same for both.

Displaying a Rooted View of a File

Extensions are usually presented to the user as a folder. However, you can also use an extension to allow users to browse the contents of a file. Extensions of this sort are typically used to display the contents of the members of a file class. For instance, the members of a file class might contain multiple compressed files or images, organized in a hierarchy. Rather than write an application to allow the user to view the contents of such a file, you can instead write a namespace extension and let Windows Explorer handle the display.

You must use a rooted view to have an extension display the contents of a file. The most common way to provide a rooted view of the members of the file class is to define a shortcut menu verb that launches an instance of Explorer.exe. By making this verb the default verb, a double-click will also open a rooted view of the file. You can either define a verb for all members of the file class by modifying the registry, or dynamically define verbs on a file-by-file basis by implementing a shortcut menu handler.

The following example illustrates how to use the registry to provide a rooted view of the members of a file class by modifying the registry. The sample registry entry is a modification of one of the examples in Extending Shortcut Menus. The registry entries define files with an .myp file name extension as a file class, and use the browse verb to launch a rooted view of members of that class.

HKEY_CLASSES_ROOT
  .myp=MyProgram.1
  ...
  MyProgram.1=MyProgram Application
    Shell=browse
      browse
        command=%SYSTEMROOT%\explorer.exe /e,/root,{Extension CLSID}, "%1"

You can use the same verb to programmatically launch a rooted view of a member of the file class by calling ShellExecute.


Implementing the Basic Folder Object Interfaces

The procedure for implementing a namespace extension is similar to that for any other in-process COM object. All extensions must support three primary interfaces that provide Microsoft® Windows® Explorer with the basic information needed to display the extension's folders in the tree view. However, to make full use of the capabilities of Windows Explorer, your extension must also expose one or more optional interfaces that support more sophisticated features, such as shortcut menus or drag-and-drop, and provide a folder view.

This document discusses how to implement the primary and optional interfaces that Windows Explorer calls for information about the contents of your extension. For a discussion of how to implement a folder view and how to customize Windows Explorer, see Implementing a Folder View. For a working example of a namespace extension, see the SampView sample in the Platform SDK.

  • Basic Implementation and Registration
  • Handling PIDLs
  • Implementing the Primary Interfaces
  • Implementing the Optional Interfaces

Basic Implementation and Registration

As an in-process COM server, your DLL must expose several standard functions and interfaces:

  • DllCanUnloadNow
  • DllGetClassObject
  • IClassFactory
  • IUnknown

These functions and interfaces are implemented in the same way as they are for most other COM objects. For details, see the COM documentation.

Registering an Extension

As with all COM objects, you must create a CLSID GUID for your extension. Register the object by creating a subkey of HKEY_CLASSES_ROOT\CLSID named for the CLSID of your extension. The DLL should be registered as an in-process server and should specify the apartment threading model. You can customize the behavior of an extension's root folder by adding a variety of subkeys and values to the extension's CLSID key.

Several of these values apply only to extensions with virtual junction points. These values do not apply to extensions whose junction points are file system folders. For further discussion, see Specifying a Namespace Extension's Location. To modify the behavior of an extension with a virtual junction point, add one or more of the following values to the extension's CLSID key:

  • WantsFORPARSING. The parsing name for an extension with a virtual junction point will normally have the form ::{GUID}. Extensions of this type normally contain virtual items. However, some extensions, such as My Documents, actually correspond to file system folders, even though they have virtual junction points. If your extension represents file system objects in this way, you can set the WantsFORPARSING value. Windows Explorer will then request your root folder's parsing name by calling the folder object's IShellFolder::GetDisplayNameOf method with uFlags set to SHGDN_FORPARSING and pidl set to a single empty PIDL. An empty PIDL contains only a terminator. Your method should then return the root folder's ::{GUID} parsing name.
  • HideFolderVerbs. The verbs registered under HKEY_CLASSES_ROOT\Folder normally are associated with all extensions. They appear on the extension's shortcut menu and can be invoked by ShellExecute. To prevent any of these verbs from being associated with your extension, set the HideFolderVerbs value.
  • HideAsDelete. If a user attempts to delete your extension, Windows Explorer will instead hide the extension.
  • HideAsDeletePerUser. This value has the same effect as HideAsDelete but on a per-user basis. The extension is hidden only for those users who have attempted to delete it. The extension is visible to all other users.
  • QueryForOverlay. Set this value to indicate that the root folder's icon can have an icon overlay. The folder object must support the IShellIconOverlay interface. Before Windows Explorer displays the root folder's icon, it will request an overlay icon by calling one of the two IShellIconOverlay methods with pidlItem set to an empty PIDL.

The remaining values and subkeys apply to all extensions:

  • To specify the display name of the extension's junction point folder, set the default value of the extension's CLSID subkey to an appropriate string.
  • When the cursor hovers over a folder, an infotip is typically displayed that describes the contents of the folder. To provide an infotip for your extension's root folder, create an InfoTip REG_SZ value for the extension's CLSID key, and set it to an appropriate string.
  • To specify a custom icon for your extension's root folder, create a subkey of the extension's CLSID subkey named DefaultIcon. Set the default value of DefaultIcon to a REG_SZ value containing the name of the file that contains the icon, followed by a comma, followed by the zero-based index of the icon in that file.
  • By default, the shortcut menu of your extension's root folder will contain the items defined under HKEY_CLASSES_ROOT\Folder. The Delete, Rename, and Properties items are added if you have set the appropriate SFGAO_XXX flags. You can add other items to the root folder's shortcut menu, or override existing items, much as you would for a file class. Create a Shell subkey under the extension's CLSID key, and define commands as discussed in Extending Shortcut Menus.
  • If you need a more flexible way to handle the root folder's shortcut menu, you can implement a shortcut menu handler. To register the shortcut menu handler, create a ShellEx key under the extension's CLSID key. Register the handler's CLSID as you would for a conventional Shell extension handler.
  • To add a page to the root folder's Properties property sheet, give the folder the SFGAO_HASPROPSHEET attribute and implement a property sheet handler. To register the property sheet handler, create a ShellEx key under the extension's CLSID key. Register the handler's CLSID as you would for a conventional Shell extension handler.
  • To specify the attributes of the root folder, add a ShellFolder subkey to the extension's CLSID subkey. Create an Attributes value, and set it to the appropriate combination of SFGAO_XXX flags.

The following table lists some commonly used attributes for root folders.

Flag | Value | Description
SFGAO_FOLDER | 0x20000000 | The extension's root folder contains one or more items.
SFGAO_HASSUBFOLDER | 0x80000000 | The extension's root folder contains one or more subfolders. Windows Explorer will place a plus sign (+) next to the folder icon.
SFGAO_CANDELETE | 0x00000020 | The extension's root folder can be deleted by the user. The folder's shortcut menu will have a Delete item. This flag should be set for junction points that are placed under one of the virtual folders.
SFGAO_CANRENAME | 0x00000010 | The extension's root folder can be renamed by the user. The folder's shortcut menu will have a Rename item.
SFGAO_HASPROPSHEET | 0x00000040 | The extension's root folder has a Properties property sheet. The folder's shortcut menu will have a Properties item. To provide the property sheet, you must implement a property sheet handler. Register the handler under the extension's CLSID key, as discussed previously.

The following example shows the CLSID registry entry for an extension with a display name of MyExtension. The extension has a custom icon that is contained in the extension's DLL with an index of 1. The SFGAO_FOLDER, SFGAOHASSUBFOLDER, and SFGAO_CANDELETE attributes are set.

HKEY_CLASSES_ROOT
  CLSID
    {Extension CLSID}=MyExtension
        InfoTip=Some appropriate text
      InProcServer32=c:\MyDir\MyExtension.dll
        ThreadingModel=Apartment
      ShellFolder
        Attributes=0xA00000020
      DefaultIcon=c:\MyDir\MyExtension.dll,1

For Microsoft® Windows NT® 4.0 and later systems, all extensions must be on the Shell's list of approved extensions. However, you should add your extension to the approved list for all systems. Doing so will ensure compatibility with later systems and have no effect on systems that do not support such a list. To add your extension to the approved list, create a value of the Approved subkey, named for the extension's CLSID. Although not required, you should assign a string to this value to identify your extension, as in the following:

HKEY_LOCAL_MACHINE
  Software
    Microsoft
      Windows
        CurrentVersion
          ShellExtensions
            Approved
              ...
              {Your Extension's CLSID}=MyExtension

Handling PIDLs

Every item in the Shell namespace must have a unique PIDL. Windows Explorer assigns a PIDL to your root folder and passes the value to your extension during initialization. Your extension is then responsible for assigning a properly constructed PIDL to each of its objects and providing those PIDLs to Windows Explorer on request. When the Shell uses a PIDL to identify one of your extension's objects, your extension must be able to interpret the PIDL and identify the particular object. Your extension must also assign a display name and a parsing name to each object. Because PIDLs are used by virtually every folder interface, extensions commonly implement a single PIDL manager to handle all these tasks.

The term PIDL is short for an ITEMIDLIST structure or a pointer to such a structure, depending on context. As declared, an ITEMIDLIST structure has a single member, an SHITEMID structure. However, as discussed in The Shell Namespace, an object's ITEMIDLIST structure is actually a packed array of two or more SHITEMID structures. The order of these structures defines a path through the namespace, in much the same way that c:\MyDirectory\MyFile defines a path through the file system. Typically, an object's PIDL will consist of a series of SHITEMID structures that correspond to the folders that define the namespace path, followed by the object's SHITEMID structure, followed by a terminator.

The terminator is an SHITEMID structure, with the cb member set to NULL. The terminator is necessary because the number of SHITEMID structures in an object's PIDL depends on the location of the object in the Shell namespace, and the starting point of the path. In addition, the size of the various SHITEMID structures can vary. When you receive a PIDL, you have no simple way of determining its size or even the total number of SHITEMID structures. Instead, you must "walk" the packed array, structure by structure, until you reach the terminator.

To create a PIDL, your application needs to:

  1. Create an SHITEMID structure for each of its objects.
  2. Assemble the relevant SHITEMID structures into a PIDL.

Creating an SHITEMID Structure

An object's SHITEMID structure uniquely identifies the object within its folder. In fact, a type of PIDL used by many of the IShellFolder methods consists of just the object's SHITEMID structure, followed by a terminator. The definition of an SHITEMID structure is:

typedef struct _SHITEMID {
    USHORT cb;
    BYTE   abID[1];
} SHITEMID, * LPSHITEMID;

The abID member is the object's identifier. Because the length of abID is not defined and can vary, the cb member is set to the size of the SHITEMID structure, in bytes.

Because neither the length nor the content of abID is standardized, you can use any scheme you want to assign abID values to your objects. The only requirement is that you cannot have two objects in the same folder with identical values. However, for performance reasons, your SHITEMID structure should be DWORD-aligned. In other words, you should construct your abID values such that cb is an integral multiple of 32.

Typically, abID points to an extension-defined structure. In addition to the object's ID, this structure is often used to hold a variety of related information, such as the object's type or attributes. Your extension's folder objects can then quickly extract the information from the PIDL instead of having to query for it.

Note One of the most important aspects of designing a data structure for a PIDL is to make the structure persistable and transportable. In the context of PIDLs, the meaning of these terms is:

  • Persistable. The system frequently places PIDLs in various types of long-term storage, such as shortcut files. It can then recover these PIDLs from storage later, possibly after the system has been rebooted. A PIDL that has been recovered from storage must still be valid and meaningful to your extension. This requirement means, for instance, that you should not use pointers or handles in your PIDL structure. PIDLs containing this type of data will normally be meaningless when the system later recovers them from storage.
  • Transportable. A PIDL must remain meaningful when transported from one computer to another. For example, a PIDL can be written to a shortcut file, copied to a floppy disk, and transported to another computer. That PIDL should still be meaningful to your extension running on the second computer. For instance, to ensure that your PIDLs are transportable, use either ANSI or Unicode characters explicitly. Avoid data types such as TCHAR or LPTSTR. If you use those data types, a PIDL created on a computer running a Unicode version of your extension will not be readable by an ANSI version of that extension running on a different computer.

The following declaration shows a simple example of a data structure.

typedef struct tagMYPIDLDATA {
  USHORT cb;
  DWORD dwType;
  WCHAR wszDisplayName[40];
} MYPIDLDATA, *LPMYPIDLDATA;

The cb member is set to the size of the MYPIDLDATA structure. This member makes MYPIDLDATA a valid SHITEMID structure, in and of itself. The rest of the members are equivalent to the abID member of an SHITEMID structure and hold private data. The dwType member is an extension-defined value that indicates the type of object. For this example, dwType is set to TRUE for folders and FALSE otherwise. This member allows you, for instance, to quickly determine whether the object is a folder or not. The wszDisplayName member contains the object's display name. Since you would not assign the same display name to two different objects in the same folder, the display name also serves as the object ID. In this example, wszDisplayName is set to 40 characters to guarantee that the SHITEMID structure will be DWORD-aligned. To limit the size of your PIDLs, you can instead use a variable-length character array and adjust the value of cb accordingly. Pad the display string with enough '\0' characters to maintain the structure's DWORD alignment. Other members that might be useful to put in the structure include the object's size, attributes, or parsing name.

Constructing a PIDL

Once you have defined SHITEMID structures for your objects, you can then use them to construct a PIDL. PIDLs can be constructed for a variety of purposes, but most tasks use one of two types of PIDL. The simplest, a single-level PIDL, identifies the object relative to its parent folder. This type of PIDL is used by many of the IShellFolder methods. A single-level PIDL contains the object's SHITEMID structure, followed by a terminator. A fully qualified PIDL defines a path through the namespace hierarchy from the desktop to the object. This type of PIDL starts at the desktop and contains one SHITEMID structure for each folder in the path, followed by the object and the terminator. A fully qualified PIDL uniquely identifies the object within the entire Shell namespace.

The simplest way to construct a PIDL is to work directly with the ITEMIDLIST structure itself. Create an ITEMIDLIST structure, but allocate enough memory to hold all the SHITEMID structures. The address of this structure will point to the initial SHITEMID structure. Define values for the members of this initial structure, and then append as many additional SHITEMID structures as you need, in the appropriate order. The following procedure outlines how to create a single-level PIDL. It contains two SHITEMID structures—a MYPIDLDATA structure followed by a terminator:

  1. Get a pointer to the Shell's memory allocator by calling SHGetMalloc. The function returns a pointer to an IMalloc interface that is used to allocate memory for the PIDL. Extensions typically call SHGetMalloc once and store the IMalloc pointer in a global variable for future use.
  2. Use the IMalloc::Alloc method to allocate memory for the PIDL. Allocate enough memory for your private data plus a USHORT (two bytes) for the terminator. Cast the result to LPMYPIDLDATA.
  3. Set the cb member of the first MYPIDLDATA structure to the size of that structure. For this example, you would set cb to sizeof(MYPIDLDATA). If you want to use a variable-length structure, you will have to calculate the value of cb.
  4. Assign appropriate values to the private data members.
  5. Calculate the address of the next SHITEMID structure. Cast the address of the current MYPIDLDATA structure to LPBYTE, and add that value to the value of cb determined in step 3.
  6. In this case, the next SHITEMID structure is the terminator. Set the structure's cb member to zero.

For longer PIDLS, allocate sufficient memory and repeat steps 3-5 for each additional SHITEMID structure.

The following sample function takes an object's type and display name and returns the object's single-level PIDL. The function assumes that the display name does not exceed the number of characters declared for the MYPIDLDATA structure. The g_pMalloc variable is an IMalloc pointer created elsewhere and stored in a global variable.

LPITEMIDLIST CreatePIDL(DWORD dwType, LPCWSTR pwszDisplayName)
{
LPMYPIDLDATA   pidlOut;
USHORT         uSize;

pidlOut = NULL;

//Calculate the size of the MYPIDLDATA structure.

uSize = sizeof(MYPIDLDATA);

/*
Allocate enough memory for the PIDL to hold a
MYPIDLDATA structure plus the terminator
*/

pidlOut = (LPMYPIDLDATA)m_pMalloc->Alloc(uSize + sizeof(USHORT));

if(pidlOut)
   {
   //Assign values to the members of the MYPIDLDATA structure
   //that is the PIDL's first SHITEMID structure

   pidlOut->cb = uSize;
   pidlOut->dwType = dwType;
   lstrcpy(pidlOut->wszDisplayName,pwszDisplayName);

   //Advance the pointer to the start of the next SHITEMID structure.

   pidlOut = (LPMYPIDLDATA)((LPBYTE)pidlOut + pidlOut->cb);

   //Create the NULL terminator by setting cb to 0.
   pidlOut->cb = 0;
   }

return pidlOut;
}

A fully qualified PIDL must have SHITEMID structures for every object from the desktop to your object. Your extension receives a fully qualified PIDL for your root folder when the Shell calls IPersistFolder::Initialize. To construct a fully qualified PIDL for an object, take the PIDL that the Shell has assigned to your root folder, and append the SHITEMID structures that are needed to take you from the root folder to the object.

Interpreting PIDLs

When the Shell or an application calls one of your extension's interfaces to request information about an object, it will usually identify the object by a PIDL. Some methods, such as IShellFolder::GetUIObjectOf, use PIDLs that are relative to the parent folder and are straightforward to interpret. However, your extension will probably also receive fully qualified PIDLs. Your PIDL manager must then determine which of your objects that PIDL is referring to.

What complicates the task of associating an object with a fully qualified PIDL is that one or more of the initial SHITEMID structures in the PIDL might belong to objects that lie outside your extension in the Shell namespace. You have no way of interpreting the meaning of the abID member of those structures. What your extension must do is to "walk" the list of SHITEMID structures, until you reach the structure that corresponds to your root folder. From then on, you will know how to interpret the information in the SHITEMID structures.

To walk the PIDL, take the first cb value and add it to the address of the PIDL to advance the pointer to the start of the next SHITEMID structure. It then will be pointing to that structure's cb member, which you can use to advance the pointer to the start of the next SHITEMID structure, and so on. Each time you advance the pointer, examine the SHITEMID structure to determine whether you have reached the root of your extension's namespace.

Implementing the Primary Interfaces

As with all COM objects, implementing an extension is largely a matter of implementing a collection of interfaces. This section discusses the three primary interfaces that must be implemented by all extensions. They are used for initialization and to provide Windows Explorer with basic information about the contents of the extension. These interfaces, plus a folder view, are all that is required for a functional extension. However, to fully exploit the features of Windows Explorer, most extensions also implement one or more of the optional interfaces.

IPersistFolder Interface

The IPersistFolder interface is called to initialize a new folder object. The IPersistFolder::Initialize method assigns a fully qualified PIDL to the new object. Store this PIDL for future use. For instance, a folder object must use this PIDL to construct fully qualified PIDLs for the object's children. The folder object's creator can also call IPersistFolder::GetClassID to request the object's CLSID.

Typically, a folder object is created and initialized by its parent folder's IShellFolder::BindToObject method. However, when a user browses into your extension, Windows Explorer creates and initializes the extension's root folder object. The PIDL that the root folder object receives through IPersistFolder::Initialize contains the path from the desktop to the root folder that you will need to construct fully qualified PIDLs for your extension.

IShellFolder Interface

The Shell treats an extension as a hierarchically ordered collection of folder objects. The IShellFolder interface is the core of any extension implementation. It represents a folder object and provides Windows Explorer with much of the information needed to display the contents of the folder.

IShellFolder is typically the only folder interface other than IPersistFolder that is directly exposed by a folder object. While Windows Explorer uses a variety of required and optional interfaces to obtain information about the contents of the folder, it obtains pointers to those interfaces through IShellFolder.

Windows Explorer obtains the CLSID of your extension's root folder in a variety of ways. For details, see Specifying a Namespace Extension's Location or Displaying a Self-Contained View of a Namespace Extension. Windows Explorer then uses that CLSID to create and initialize an instance of the root folder and query for an IShellFolder interface. Your extension creates a folder object to represent the root folder and returns the object's IShellFolder interface. Much of the remainder of the interaction between your extension and Windows Explorer then takes place through IShellFolder. Windows Explorer calls IShellFolder to:

  • Request an object that can enumerate the contents of the root folder.
  • Obtain various types of information about the contents of the root folder.
  • Request an object that exposes one of the optional interfaces. Those interfaces can then be queried for additional information, such as icons or shortcut menus.
  • Request a folder object that represents a subfolder of the root folder.

When a user opens a subfolder of the root folder, Windows Explorer calls IShellFolder::BindToObject. Your extension creates and initializes a new folder object to represent the subfolder and returns its IShellFolder interface. Windows Explorer then calls this interface for various types of information, and so on until the user decides to navigate elsewhere in the Shell namespace or close Windows Explorer.

The remainder of this section briefly discusses the more important IShellFolder methods and how to implement them.

EnumObjects

Before displaying the contents of a folder in the tree view, Windows Explorer must first determine what the folder contains by calling the IShellFolder::EnumObjects method. This method creates a standard OLE enumeration object that exposes an IEnumIDList interface and returns that interface pointer. The IEnumIDList interface allows Windows Explorer to obtain the PIDLs of all the objects contained by the folder. These PIDLs are then used to obtain information about the objects contained by the folder. For further details, see IEnumIDList Interface.

Note The IEnumIDList::Next method should only return PIDLs that are relative to the parent folder. The PIDL should contain only the object's SHITEMID structure, followed by a terminator.

CreateViewObject

Before the contents of a folder are displayed, Windows Explorer calls this method to request a pointer to an IShellView interface. This interface is used by Windows Explorer to manage the folder view. Create a folder view object and return its IShellView interface.

The IShellFolder::CreateViewObject method is also called to request one of the optional interfaces, such as IContextMenu, for the folder itself. Your implementation of this method should create an object that exposes the requested interface and returns the interface pointer. If Windows Explorer needs an optional interface for one of the objects contained by the folder, it will call IShellFolder::GetUIObjectOf.

GetUIObjectOf

While basic information about the contents of a folder is available through the IShellFolder methods, your extension can also provide Windows Explorer with various kinds of additional information. For instance, you can specify icons for the contents of a folder or an object's shortcut menu. Windows Explorer calls the IShellFolder::GetUIObjectOf method to attempt to retrieve additional information about an object that is contained by a folder. Windows Explorer specifies which object it wants the information for, and the IID of the relevant interface. The folder object then creates an object that exposes the requested interface and returns the interface pointer. For a detailed list of optional folder interfaces, see Standard Shell Interfaces.

If your extension allows users to transfer objects with drag-and-drop or the clipboard, Windows Explorer will call IShellFolder::GetUIObjectOf to request an IDataObject or IDropTarget interface. For details, see Transferring Shell Objects with Drag-and-Drop and the Clipboard.

Windows Explorer calls IShellFolder::CreateViewObject when it wants the same sort of information about the folder itself.

BindToObject

Windows Explorer calls the IShellFolder::BindToObject method when a user attempts to open one of your extension's subfolders. If riid is set to IID_IShellFolder, you should create and initialize a folder object that represents the subfolder and return the object's IShellFolder interface.

Note At present, Windows Explorer calls this method only to request an IShellFolder interface. However, because additional interfaces could be added in the future, you should always check the value of riid before proceeding.

GetDisplayNameOf

Windows Explorer calls the IShellFolder::GetDisplayNameOf method to convert the PIDL of one of the folder's objects into a name. That PIDL must be relative to the object's parent folder. In other words, it must contain a single non-NULL SHITEMID structure. Because there is more than one possible way to name objects, Windows Explorer specifies the type of name by setting one or more SHGNO flags in the uFlags parameter. One of two values, SHGDN_NORMAL or SHGDN_INFOLDER, will be set to specify whether the name should be relative to the folder or relative to the desktop. One of the other three values, SHGDN_FOREDITING, SHGDN_FORADDRESSBAR, or SHGDN_FORPARSING, can be set to specify what the name will be used for.

You must return the name in the form of an STRRET structure. If SHGDN_FOREDITING, SHGDN_FORADDRESSBAR, and SHGDN_FORPARSING are not set, return the object's display name. If the SHGDN_FORPARSING flag is set, Windows Explorer is requesting a parsing name. Parsing names are passed to IShellFolder::ParseDisplayName to obtain an object's PIDL, even though it might be located one or more levels below the current folder in the namespace hierarchy. For example, the parsing name of a file system object is its path. You can pass the fully qualified path of any object in the file system to the desktop's IShellFolder::ParseDisplayName method, and it will return the object's fully qualified PIDL.

While parsing names are text strings, they don't necessarily have to include the display name. You should assign parsing names based on what will work most efficiently when IShellFolder::ParseDisplayName is called. For instance, many of the Shell's virtual folders are not part of the file system and do not have a fully qualified path. Instead, each folder is assigned a GUID and the parsing name takes the form ::{GUID}. Regardless of what scheme you use, it should be able to reliably "round trip." For instance, if a caller passes a parsing name to IShellFolder::ParseDisplayName to retrieve an object's PIDL, and then passes that PIDL to IShellFolder::GetDisplayNameOf with the SHGDN_FORPARSING flag set, the caller should recover the original parsing name.

GetAttributesOf

Windows Explorer calls the IShellFolder::GetAttributesOf method to determine the attributes of one or more items contained by a folder object. The value of cidl gives the number of items in the query, and apidl points to a list of their PIDLs.

Because testing for some attributes can be time consuming, Windows Explorer typically restricts the query to a subset of the available flags by setting their values in rfgInOut. Your method should test for only those attributes whose flags are set in rfgInOut. Leave the valid flags set and clear the remainder. If more than one item is included in the query, set only those flags that apply to all items.

Note The attributes must be properly set for an item to be correctly displayed. For instance, if an item is a folder that contains subfolders, you must set the SFGAO_HASSUBFOLDERS flag. Otherwise, Windows Explorer will not display a + next to the item's icon in the tree view.

ParseDisplayName

The IShellFolder::ParseDisplayName method is in some sense a mirror image of IShellFolder::GetDisplayNameOf. The most common use of this method is to convert an object's parsing name into the associated PIDL. The parsing name can refer to any object that lies below the folder in the namespace hierarchy. The returned PIDL is relative to the folder object that exposes the method and is usually not fully qualified. In other words, although the PIDL can contain several SHITEMID structures, the first will either be that of the object itself or the first subfolder in the path from the folder to the object. The caller will have to append this PIDL to the folder's fully qualified PIDL to obtain a fully qualified PIDL for the object.

IShellFolder::ParseDisplayName can also be called to request an object's attributes. Because determining all the applicable attributes can be time consuming, the caller will set only those SFGAO_XXX flags that represent information that the caller is interested in. You should determine which of those attributes are true for the object, and clear the remaining flags.

IEnumIDList Interface

When Windows Explorer needs to enumerate the objects that are contained by a folder, it calls IShellFolder::EnumObjects. The folder object must create an enumeration object that exposes the IEnumIDList interface and return that interface pointer. Windows Explorer will then typically use IEnumIDList to enumerate the PIDLs of all the objects contained by the folder.

IEnumIDList is a standard OLE enumeration interface and is implemented in the usual way. Remember, however, that the PIDLs that you return must be relative to the folder and contain only the object's SHITEMID structure and a terminator.

Implementing the Optional Interfaces

There are a number of optional Shell interfaces that your extension's folder objects can support. Many of them, such as IExtractIcon, allow you to customize various aspects of the way the user views your extension. Others, such as IDataObject, allow your extension to support features such as drag-and-drop.

None of the optional interfaces are exposed directly by a folder object. Instead, Windows Explorer calls one of two IShellFolder methods to request an interface:

  • Windows Explorer calls a folder object's IShellFolder::GetUIObjectOf to request an interface for one of the objects contained by the folder.
  • Windows Explorer calls a folder object's IShellFolder::CreateViewObject to request an interface for the folder itself.

To provide the information, the folder object creates an object that exposes the requested interface and returns the interface pointer. Windows Explorer then calls that interface to retrieve the needed information. This section discusses the most commonly used optional interfaces.

IExtractIcon

Windows Explorer requests an IExtractIcon interface before it displays the contents of a folder. The interface allows your extension to specify custom icons for the objects that are contained by the folder. Otherwise, the standard file and folder icons will be used. To provide a custom icon, create an icon extraction object that exposes IExtractIcon and return a pointer to that interface. For further discussion, see the IExtractIcon reference documentation or Creating Icon Handlers.

IContextMenu

When a user right-clicks an object, Windows Explorer requests an IContextMenu interface. To provide shortcut menus for your objects, create a menu handler object and return its IContextMenu interface.

The procedures for creating a menu handler object are very similar to those used to create a menu handler Shell extension. For details, see Creating Shortcut Menu Handlers or the IContextMenu, IContextMenu2, or IContextMenu3 reference.

IQueryInfo

Windows Explorer calls the IQueryInfo interface to retrieve an infotip text string.

IDataObject and IDropTarget

When your objects are displayed by Windows Explorer, a folder object has no direct way to know when a user is attempting to cut, copy, or drag an object. Instead, Windows Explorer requests an IDataObject interface. To allow the object to be transferred, create a data object and return a pointer to its IDataObject interface.

Similarly, a user might attempt to drop a data object on a Windows Explorer representation of one of your objects, such as an icon or address bar path. Windows Explorer then requests an IDropTarget interface. To allow the data object to be dropped, create an object that exposes an IDropTarget interface and return the interface pointer.

Handling data transfer is one of the trickier aspects of writing namespace extensions. For a detailed discussion, see Transferring Shell Objects with Drag-and-Drop and the Clipboard. For a working example of how to implement drag-and-drop in a namespace extension, see the SampView sample code in the Platform SDK.


Implementing a Folder View

Unlike the tree view, Microsoft® Windows® Explorer does not manage the contents of a folder view. Instead, the folder view window hosts a child window that is provided by the folder object. The folder object is responsible for creating a folder view object to display the folder's contents in the child window.

The key to implementing a folder view object is the IShellView interface. This interface is used by Windows Explorer to communicate with the folder view object. Before displaying a folder view, Windows Explorer calls the folder object's IShellFolder::CreateViewObject method with riid set to IID_IShellView. Create a folder view object and return its IShellView interface. The folder view object must then create a child window of the folder view window and use the child window to display information about the folder's contents.

In addition to controlling how data is displayed, extensions can also customize a number of the features of Windows Explorer. For instance, an extension can add items to the toolbar or menu bar, or display information on the status bar.

  • The Folder View Object
  • Initializing the Folder View Object
  • Displaying the Folder View
  • Implementing IShellView
  • Using IShellBrowser to Communicate with Windows Explorer

The Folder View Object

A folder view object is a COM object that exposes an IShellView interface. This object is responsible for:

  • Creating a child window of the folder view window and using it to display the contents of the folder.
  • Handling communication with Windows Explorer.
  • Adding folder-specific commands to the Windows Explorer menu bar and toolbar and handling those commands when they are selected.
  • Managing user interaction with the folder view window, such as displaying shortcut menus or handling drag-and-drop operations.

This document discusses the first three topics. Because user interaction with the folder view takes place within your child window, your folder view object is responsible for handling it as it would for any other window.

Windows Explorer requests a folder view object by calling your folder object's IShellFolder::CreateViewObject with riid set to IID_IShellView. The procedure for creating a folder view is:

  1. Your folder object creates a new instance of your folder view object and returns a pointer to its IShellView interface.
  2. Windows Explorer initializes the folder view object by calling the IShellView::CreateViewWindow method. Create a child window of the folder view window and return its handle to Windows Explorer.
  3. The folder view object uses the Windows Explorer IShellBrowser interface to customize the Windows Explorer toolbar, menu bar, and status bar.
  4. The folder view object displays the contents of the folder in the child window.
  5. The folder view object handles user interaction with the folder view and any folder-specific toolbar or menu bar items.

Initializing the Folder View Object

Windows Explorer initializes the folder view object by calling the IShellView::CreateViewWindow method. The method's parameters provide the folder view object with the information it needs to create the child window that will be used to display the folder's contents:

  • A pointer to the previous folder view object's IShellView interface. This parameter can be set to NULL.
  • A FOLDERSETTINGS structure that contains the previous folder view's settings.
  • A pointer to the Windows Explorer IShellBrowser interface.
  • A RECT structure with the dimensions of the folder view window.

The IShellView::CreateViewWindow method is called before the previous folder view object is destroyed. The IShellView interface pointer thus allows you to communicate with the previous folder view object. This interface is primarily useful if the previous folder belonged to your extension and used the same display scheme. If so, you can communicate with the previous folder view object for such purposes as exchanging private settings.

A simple way to determine whether the IShellView pointer belongs to your extension is to have all your folder view objects expose a private interface. Call IShellView::QueryInterface to request the private interface, and examine the return value to determine whether the folder view object is one of yours. You can then use a private method on that interface to exchange information.

The FOLDERSETTINGS structure contains the previous folder view's display settings. The primary setting is the viewing mode: large icon, small icon, list, or details. There is also a flag that contains the settings of a variety of display options, such as whether the view should be left-aligned. Your folder display should follow these settings to the extent possible, to give users a consistent experience as they go from one folder to another. You should store this structure and update it as the settings change. Windows Explorer calls IShellView::GetCurrentInfo to obtain the most recent value of this structure before it opens the next folder view.

The IShellBrowser interface is exposed by Windows Explorer. This interface is a companion to IShellView and allows a folder view object to communicate with Windows Explorer. There is no other way to retrieve this interface pointer, so your folder view object should store it for future use. In particular, you will need to call IShellBrowser::GetWindow to retrieve the parent folder view window that you will use to create your child window. Note that the IShellBrowser::GetWindow method is not included in the IShellBrowser documentation because it is inherited from IOleWindow. After storing the interface pointer, remember to call IShellBrowser::AddRef to increment the interface's reference count. When you no longer need the interface, call IShellBrowser::Release.

To create your child window:

  1. Examine the FOLDERSETTINGS and RECT structures.
  2. If needed, obtain private settings from the previous folder view object.
  3. Call IShellBrowser::GetWindow to retrieve the parent folder view window.
  4. Create a child of the folder view window obtained in the previous step and return it to Windows Explorer.

Displaying the Folder View

Once you have created the child window and returned it to Windows Explorer, you can display the folder's contents. Typically, extensions display their information by having the child window host either a list view control or a WebBrowser control. The list view control allows you to replicate the Windows Explorer classic view. The WebBrowser control allows you to use a DHTML document to display your information, much like the Windows Explorer Web view. For further information, refer to the documentation of those controls.

The folder view window always exists, even if it does not have focus. You should therefore maintain three states for your child window:

  • Activated with focus. The folder view has been created and has focus. Set the menu bar or toolbar items that are appropriate for a focused state.
  • Activated without focus. The folder view has been created and is active, but it does not have focus. Set the menu bar or toolbar items that are appropriate for a nonfocused state. Omit any items that apply to the selection of items within the folder view.
  • Deactivated. The folder view is about to be destroyed. Remove all folder-specific menu items.

Windows Explorer notifies your folder view object when the window state changes by calling IShellView::UIActivate. In turn, the folder view object should notify Windows Explorer when a user activates the folder view window by calling IShellBrowser::OnViewWindowActive. For further discussion of this interface, see Using IShellBrowser to Communicate with Windows Explorer.

While the folder view is active, you need to process any Microsoft® Windows® messages, such as WM_SIZE, that belong to your child window. Your window procedure will also receive WM_COMMAND messages for any items you have added to the Windows Explorer menu bar or toolbar.

After creating the folder view, Windows Explorer calls the folder view object's IShellView interface to pass it a variety of information. Your object must modify its display accordingly. When the folder view is about to be destroyed, Windows Explorer notifies the folder view object by calling its IShellView::DestroyViewWindow method.

Implementing IShellView

After the folder object has been created, Windows Explorer calls various IShellView methods to either request information or notify the object of a change in the state of Windows Explorer. This section outlines how to implement those IShellView methods. The remaining methods are used for more specialized purposes, such as the File Open common dialog box. For details, see the IShellView documentation.

AddPropertySheetPages

When a user selects Folder Options from the Windows Explorer Tools menu, a property sheet is displayed that allows the user to modify the folder options. Windows Explorer calls your folder view object's IShellView::AddPropertySheetPages method to allow you to add a page to this property sheet.

Windows Explorer passes a pointer to an AddPropSheetPageProc callback function in the lpfn parameter of IShellView::AddPropertySheetPages. Call CreatePropertySheetPage to create the page, and then call the AddPropSheetPageProc to add it to the property sheet. For further discussion of how to handle property sheets, see Property Sheets.

GetCurrentInfo

When the user switches from one folder to another, Windows Explorer attempts to maintain a similar folder view. For instance, if the previous folder view showed large icons, the next should as well. When Windows Explorer calls IShellView::CreateViewWindow to initialize your folder view object, the method receives a FOLDERSETTINGS structure. This structure contains information that allows you to make your folder view display consistent with the previous folder view.

To help ensure that the next view is consistent with the current view, store the FOLDERSETTINGS structure. If the view changes, for instance from large to small icons, update the structure accordingly. Prior to switching views, Windows Explorer will call IShellView::GetCurrentInfo to request the current FOLDERSETTINGS values to pass them to the next folder view object.

Refresh

The user can ensure that the folder view reflects the current state of the folder by selecting Refresh from the View menu or pressing the F5 key. When the user does so, Windows Explorer calls the IShellView::Refresh method. Your folder view object should immediately update the folder view display.

SaveViewState

Windows Explorer calls the IShellView::SaveViewState method to prompt your folder view object to save its view state. You can then recover the state the next time the folder is viewed. The preferred way to save a view state is by calling the IShellBrowser::GetViewStateStream method. This method returns an IStream interface that your folder view object can use to save its state. When you create another folder view, you can call the same IShellBrowser::GetViewStateStream method to obtain an IStream pointer that allows you to read the settings saved by previous folder views.

TranslateAcelerator

When the user presses a shortcut key, Windows Explorer passes the message to the folder view object by calling IShellView::TranslateAccelerator. Return S_FALSE to have Windows Explorer process the message. If your folder view object has processed the message, return S_OK.

When the folder view window has focus, Windows Explorer calls IShellView::TranslateAccelerator before it processes the message. Because most of the messages are typically associated with Windows Explorer menu bar or toolbar commands, your folder view object should normally return S_FALSE. Windows Explorer can then process the message normally. Return S_OK only if the message is folder-specific and you do not want Windows Explorer to do any further processing. If the folder view does not have focus, Windows Explorer processes the message first. It calls IShellBrowser::TranslateAcceleratorSB only if it does not handle the message.

Using IShellBrowser to Communicate with Windows Explorer

The IShellBrowser interface is used by the folder view object to communicate with Windows Explorer for a variety of purposes, including:

  • Modifying the Windows Explorer menu bar.
  • Modifying the Windows Explorer toolbar.
  • Modifying the Windows Explorer status bar.
  • Storing view-specific information, such as the current settings or state.

Modifying the Windows Explorer Menu Bar

The Windows Explorer menu bar allows the user to launch a variety of commands. By default, the menu bar only supports commands that are specific to Windows Explorer. The related WM_COMMAND messages are processed by Windows Explorer and are not passed to your folder view object. However, you can modify the menu bar to include one or more folder-specific menu items with IShellBrowser. Windows Explorer passes the associated WM_COMMAND messages of those items to your folder object's window procedure for processing. You can also remove or disable any standard commands that do not apply to your application.

Folder view objects typically modify the menu bar before the folder view is first displayed. They must return the menu bar to its original state when the folder view is destroyed. You might also need to modify the menu bar each time your folder view gains or loses focus.

Because Windows Explorer calls IShellView::UIActivate each time the folder view window's state changes, menu bar modification is normally included in that method's implementation. The basic procedure for modifying the Windows Explorer menu bar is:

  1. Call CreateMenu to create a menu handle.
  2. Pass that menu handle to Windows Explorer by calling IShellBrowser::InsertMenusSB. Windows Explorer will fill in its menu information.
  3. Modify the menu as needed.
  4. Call IShellBrowser::SetMenuSB to have Windows Explorer display the modified menu bar.

Windows Explorer has six pop-up menus on its menu bar. As with all OLE containers, the Windows Explorer menu is divided into six groups: File, Edit, Container, Object, Window, and Help. The following table lists the Windows Explorer pop-up menus and their associated group, along with the menu IDs.

Pop-up menu | ID | Group
File | FCIDM_MENU_FILE | File
Edit | FCIDM_MENU_EDIT | File
View | FCIDM_MENU_VIEW | Container
Favorites | FCIDM_MENU_FAVORITES | Container
Tools | FCIDM_MENU_TOOLS | Container
Help | FCIDM_MENU_HELP | Window

When you pass the menu handle to Windows Explorer by calling IShellBrowser::InsertMenusSB, you must also pass a pointer to an OLEMENUGROUPWIDTHS structure whose members have been initialized to zero.

When IShellBrowser::InsertMenusSB returns, Windows Explorer will have added its menu items. You can then use the returned menu handle with standard Windows menu functions such as InsertMenuItem to:

  • Add items to the Windows Explorer pop-up menus.
  • Modify or delete existing items in the Windows Explorer pop-up menus.
  • Add new pop-up menus.

Use the IDs listed in the table to identify the various Windows Explorer pop-up menus.

Note To avoid conflicts with Windows Explorer command IDs, the IDs of any menu items that you add must fall between FCIDM_SHVIEWFIRST and FCIDM_SHVIEWLAST. These two values are defined in Shlobj.h.

Once you have finished modifying the menu, call IShellBrowser::SetMenuSB to have Windows Explorer display the new menu bar.

After the folder view is initially displayed, Windows Explorer calls IShellView::UIActivate each time the folder view gains or loses focus. If you have any menu items that are sensitive to the state of the folder view, you should modify the menu accordingly, each time the state changes. For instance, you might have a menu item that acts on an item in the folder view that has been selected by the user. You should disable or remove this menu item when the folder view loses focus.

When Windows Explorer calls IShellView::UIActivate to indicate that the folder view is being deactivated, restore the menu bar to its original state by calling IShellBrowser::RemoveMenusSB.

Modifying the Windows Explorer Toolbar

In addition to modifying the Windows Explorer menu bar, you can also add buttons to the toolbar. As with the menu bar, toolbar modification is usually part of the IShellView::UIActivate implementation. The procedure for adding buttons to the Windows Explorer toolbar is:

  1. Add the button's bitmap to the toolbar's image list.
  2. Define the button's text string.
  3. Add the button to the toolbar.

To add a bitmap to a toolbar's image list, send the toolbar a TB_ADDBITMAP message by calling IShellBrowser::SendControlMsg. To specify the toolbar control, set the method's id parameter to FCW_TOOLBAR. Set wParam to the number of button images in the bitmap, and lParam to the address of a TBADDBITMAP structure. The image index is returned in the pret parameter.

There are two ways to define a string for the button:

  • Assign the string to the iString member of the button's TBBUTTON structure.
  • Call IShellBrowser::SendControlMsg to send the toolbar control a TB_ADDSTRING message. The wParam parameter should be set to zero and the lParam parameter to the string. The string index is returned in the pret parameter.

To add the button to the toolbar, fill in a TBBUTTON structure and pass it to IShellBrowser::SetToolbarItems. As with the menu, your command ID must fall between FCIDM_SHVIEWFIRST and FCIDM_SHVIEWLAST. The toolbar will then append the button to the right of the existing buttons.

For instance, the following code fragment adds one standard button to the Windows Explorer toolbar with a command ID of IDB_MYBUTTON.

TBADDBITMAP tbadbm;
int iButtonIndex;
TBBUTTON tbb;

tbadbm.hInst = g_hInstance; //The module's instance handle
tbadbm.nID = IDB_BUTTONIMAGE; //The bitmap's resource ID

psb->SendControlMsg(FCW_TOOLBAR, TB_ADDBITMAP, 1,
             reinterpret_cast<LPARAM>(&tbadbm), &iButtonIndex);

psb->SendControlMsg(FCW_TOOLBAR, TB_ADDSTRING, NULL,
             reinterpret_cast<LPARAM>(szLabel), &iStringIndex);

ZeroMemory(&tbb, sizeof(TBBUTTON));
tbb.iBitmap = iButtonIndex;
tbb.iCommand = IDB_MYBUTTON;
tbb.iString = iStringIndex;
tbb.fsState = TBSTATE_ENABLED;
tbb.fsStyle = TBSTYLE_BUTTON;

psb->SetToolbarItems(&tbb, 1, FCT_MERGE);

For further discussion of how to handle toolbar controls, see Toolbar Controls.

Modifying the Windows Explorer Status Bar

You can use the Windows Explorer status bar to display a variety of useful information. There are two ways to use the status bar:

  • Use IShellBrowser::SetStatusTextSB to display a text string on the status bar.
  • Send messages directly to the status bar control with IShellBrowser::SendControlMsg.

The first method is straightforward but sufficient for many purposes. For greater flexibility, you can send messages directly to the status bar control by calling IShellBrowser::SendControlMsg with the id parameter set to FCW_STATUS. For further discussion of status bar controls, see Status Bars.

Storing View-specific Information

When a view is about to be destroyed, it is often useful to store information such as the view's state or settings. Windows Explorer prompts you to do this task by calling IShellView::SaveViewState. The preferred way to save view-specific information is to call IShellBrowser::GetViewStateStream. This method provides you with an IStream interface that you can use to store the information. You are free to use any suitable data format.


Creating Custom Explorer Bars, Tool Bands, and Desk Bands

The Explorer Bar was introduced with Microsoft® Internet Explorer 4.0 to provide a display area adjacent to the browser pane. It is basically a child window within the Internet Explorer window, and it can be used to display information and interact with the user in much the same way. Explorer Bars are most commonly displayed as a vertical pane on the left side of the browser pane. However, an Explorer Bar can also be displayed horizontally, below the browser pane.

There is a wide range of possible uses for the Explorer Bar. Users can select which option they wish to see in several different ways, including selecting it from the Explorer Bar submenu of the View menu, or clicking a toolbar button. Internet Explorer provides several standard Explorer Bars, including Favorites and Search.

One of the ways you can customize Internet Explorer is by adding a custom Explorer Bar. When implemented and registered, it will be added to the Explorer Bar submenu of the View menu. When selected by the user, the Explorer Bar's display area can then be used to display information and take user input in much the same way as a normal window.

To create a custom Explorer Bar, you must implement and register a band object. Band objects were introduced with version 4.71 of the Shell and provide capabilities similar to those of normal windows. However, because they are COM objects and contained by either Internet Explorer or the Shell, they are implemented somewhat differently. Simple band objects were used to create the sample Explorer Bars displayed in the first graphic. The implementation of the vertical Explorer Bar sample will be discussed in detail in a later section.

Tool Bands

A tool band is a band object that was introduced with Internet Explorer 5 to support the Microsoft® Windows® radio toolbar feature. The Internet Explorer toolbar is actually a rebar control that contains several toolbar controls. By creating a tool band, you can add a band to that rebar control. However, like Explorer bands, a tool band is a general purpose window.

Sample Toolband

Users display the radio toolbar by selecting it from the Toolbars submenu of the View menu or from the shortcut menu that is displayed by right-clicking the toolbar area.

Desk Bands

Band objects can also be used to create desk bands. While their basic implementation is similar to Explorer Bars, desk bands are unrelated to Internet Explorer. A desk band is basically a way to create a dockable window on the desktop. The user selects it by right-clicking the taskbar and selecting it from the Toolbars submenu.

Initially, desk bands are docked on the taskbar:

The user can then drag it to the desktop, and it will appear as a normal window:

Implementing Band Objects

Although they can be used much like normal windows, band objects are COM objects that exist within a container. Explorer Bars are contained by Internet Explorer, and desk bands are contained by the Shell. While they serve different functions, their basic implementation is very similar. The primary difference is in how the band object is registered, which in turn controls the type of object, and its container. This section discusses those aspects of implementation that are common to all band objects. See the discussion of the vertical Explorer Bar example for additional implementation details.

In addition to IUnknown and IClassFactory, all band objects must implement the following interfaces:

  • IDeskBand
  • IObjectWithSite
  • IPersistStream

In addition to registering their CLSID, the Explorer Bar and desk band objects must also be registered for the appropriate component category. Registering the component category determines the object type, and its container. Tool bands use a different registration procedure and do not have a CATID. The CATIDs for the three band objects that require them are:

Band Type | Component Category
Vertical Explorer Bar | CATID_InfoBand
Horizontal Explorer Bar | CATID_CommBand
Desk Band | CATID_DeskBand

See Registration for further discussion of how to register band objects.

If the band object is to accept user input, it must also implement IInputObject. To add items to the shortcut menu for Explorer Bar or desk bands, the object must export IContextMenu. Tool bands do not support shortcut menus.

Because band objects implement a child window, they must also implement a window procedure to handle Windows messaging.

Band objects can send commands to their container through its IOleCommandTarget interface. To obtain the interface pointer, call the container's IInputObjectSite::QueryInterface method and ask for IID_IOleCommandTarget. You then send commands to the container with IOleCommandTarget::Exec. The command group is CGID_DeskBand. When a band object's IDeskBand::GetBandInfo method is called, the container uses the dwBandID parameter to assign the band object an identifier that is used for three of the commands. Four IOleCommandTarget::Exec command IDs are supported:

DBID_BANDINFOCHANGED
The band's information has changed. Set the pvaIn parameter to the band identifier that was received in the most recent call to IDeskBand::GetBandInfo. The container will call the band object's IDeskBand::GetBandInfo method to request the updated information.
DBID_MAXIMIZEBAND
Maximize the band. Set the pvaIn parameter to the band identifier that was received in the most recent call to IDeskBand::GetBandInfo.
DBID_SHOWONLY
Turn other bands in the container on or off. Set the pvaIn parameter to the VT_UNKNOWN type with one of the following values:
Value | Description
pUnk | A pointer to the band object's IUnknown interface. All other desk bands will be hidden.
0 | Hide all desk bands.
1 | Show all desk bands.
DBID_PUSHCHEVRON
Not implemented.

Registration

A band object must be registered as an OLE in-process server that supports apartment threading. The default value for the server is a menu text string. For Explorer Bars, it will appear in the Explorer Bar submenu of the Internet Explorer View menu. For tool bands, it will appear in the Toolbars submenu of the Internet Explorer View menu. For desk bands, it will appear in the Toolbars submenu of the taskbar's shortcut menu. As with menu resources, placing an ampersand (&) in front of a letter will cause it to be underlined and enable keyboard shortcuts. For example, the menu string for the vertical Explorer Bar shown in the first graphic is "Sample &Vertical Explorer Bar".

In general, the basic registry entry for a band object will look like:

HKEY_CLASSES_ROOT
...
    CLSID
    ...
        {Your Band Object's CLSID GUID} = "Menu Text String"
            InProcServer32 = "DLL Pathname"
                ThreadingModel = "Apartment"

Tool bands must also have their object's CLSID registered with Internet Explorer. To do this, create a REG_SZ value under HKEY_LOCAL_MACHINE\Software\Microsoft\Internet Explorer\Toolbar named with the string form of the tool band object's CLSID GUID. For example:

HKEY_LOCAL_MACHINE
    Software
        Microsoft
            Internet Explorer
                Toolbar
                    {Your Band Object's CLSID GUID}

There are several optional values, not used by the example, that can also be added to the registry. The first two are necessary if you wish to use the Explorer Bar to display HTML. The last one defines the default width or height of the Explorer Bar, depending on whether it is vertical or horizontal, respectively.

  • HKEY_CLASSES_ROOT\CLSID\{Your Band Object's CLSID GUID}\Instance\CLSID, which should be set to "{4D5C8C2A-D075-11D0-B416-00C04FB90376}".
  • HKEY_CLASSES_ROOT\CLSID\{Your Band Object's CLSID GUID}\Instance\InitPropertyBag\Url which should be set to the location of the file that contains the HTML content for the Explorer Bar.
  • \HKEY_CURRENT_USER\Software\Microsoft\Internet Explorer\Explorer Bars\{Your Band Object's CLSID GUID}\BarSize which should be set to the width or height of the bar. This value requires 8 bytes, so it is placed in the registry as a string, with the bytes separated by commas. The first four bytes specify the size in pixels, in hexadecimal format, starting from the leftmost byte. The last four bytes are reserved, and should be set to zero. For example, a vertical Explorer Bar with a default width of 291 pixels (0X123) should have BarSize set to "23,01,00,00,00,00,00,00".

The registry entry for an HTML-capable Explorer Bar with a default width of 291 pixels will look like:

HKEY_CLASSES_ROOT
...
    CLSID
    ...
        {Your Band Object's CLSID GUID} = "Menu Text String"
            InProcServer32 = "DLL Pathname"
                ThreadingModel = "Apartment"
            Instance
                CLSID = "{4D5C8C2A-D075-11D0-B416-00C04FB90376}"
                InitPropertyBag
                    Url = "Your_HTML_File"
...
HKEY_CURRENT_USER
...
    Software
    ...
        Microsoft
        ...
            Internet Explorer
            ...
                Explorer Bars
                    {Your Band Object's CLSID GUID}
                        BarSize = "23,01,00,00,00,00,00,00"

You can handle registration of a band object's CATID programmatically. Create a component categories manager object (CLSID_StdComponentCategoriesMgr) and request a pointer to its ICatRegister interface. Pass the band object's CLSID and CATID to ICatRegister::RegisterClassImplCategories.

A Simple Example of a Custom Explorer Bar

This example goes through the implementation of the sample vertical Explorer Bar shown in the introduction. It is based on the band objects sample code, which can be found in the Platform SDK. The complete source code, which also implements a horizontal Explorer Bar and a desk band, is included here for reference. See the sample code, CommBand.cpp and DeskBand.cpp, for details on the implementation of the horizontal Explorer Bar and desk band objects.

The basic procedure for creating a custom Explorer Bar is:

  1. Implement the functions needed by the DLL.
  2. Implement the required COM interfaces.
  3. Implement any desired optional COM interfaces.
  4. Register the object's CLSID.
  5. Register the object for the appropriate component category.
  6. Create a child window of Internet Explorer, sized to fit the Explorer Bar's display region.
  7. Use the child window to display information and interact with the user.

The very simple implementation used in the Explorer Bar sample could actually be used for either type of Explorer Bar, or a desk band, by simply registering it for the appropriate component category. More sophisticated implementations will need to be customized for each object type's display region and container. However, much of this customization can be accomplished by taking the sample code and extending it by applying familiar Windows programming techniques to the child window. For example, you can add controls for user interaction, or graphics for a richer display.

DLL Functions

All three objects are packaged in a single DLL, which exposes:

  • DllMain
  • DllCanUnloadNow
  • DllGetClassObject
  • DllRegisterServer

These functions, can be found in BandObjs.cpp and serve all three band objects. The first three functions are standard implementations and will not be discussed here. The Class Factory implementation is also standard, and can be found in ClsFact.cpp.

Registration

As with all COM objects, the Explorer Bar's CLSID must be registered. For it to function properly with Internet Explorer, it must also be registered for the appropriate component category (CATID_InfoBand). Registration is handled by DllRegisterServer. The relevant section for the vertical Explorer Bar is:

...

//Register the Explorer Bar object.
if(!RegisterServer(CLSID_SampleExplorerBar, TEXT("Sample &Vertical Explorer Bar")))
   return SELFREG_E_CLASS;

//Register the component categories for the Explorer Bar object.
if(!RegisterComCat(CLSID_SampleExplorerBar, CATID_InfoBand))
   return SELFREG_E_CLASS;

...

Registration of band objects uses normal COM procedures and is handled by a private function, RegisterServer.

In addition to the CLSID, the band object server must also be registered for one or more component categories. This is actually the main difference in implementation between the vertical and horizontal Explorer Bar samples. This process is handled by creating a component categories manager object (CLSID_StdComponentCategoriesMgr) and using the ICatRegister::RegisterClassImplCategories method to register the band object server. In this example, component category registration is handled by passing the Explorer Bar sample's CLSID and CATID to a private function, RegisterComCat:

BOOL RegisterComCat(CLSID clsid, CATID CatID)
{
ICatRegister   *pcr;
HRESULT        hr = S_OK ;

CoInitialize(NULL);

hr = CoCreateInstance(  CLSID_StdComponentCategoriesMgr,
                        NULL,
                        CLSCTX_INPROC_SERVER,
                        IID_ICatRegister,
                        (LPVOID*)&pcr);
if(SUCCEEDED(hr))
   {
   hr = pcr->RegisterClassImplCategories(clsid, 1, &CatID);
   pcr->Release();
   }

CoUninitialize();

return SUCCEEDED(hr);
}

Required Interface Implementations

The vertical Explorer Bar sample implements the four required interfaces: IUnknown, IObjectWithSite, IPersistStream, and IDeskBand as part of the CExplorerBar class. The constructor, destructor, and IUnknown implementations are straightforward, and will not be discussed here. See the sample code for details.

The IObjectWithSite Interface

When the user selects an Explorer Bar, the container calls the corresponding band object's IObjectWithSite::SetSite method. The punkSite parameter will be set to the site's IUnknown pointer.

In general, a SetSite implementation should perform the following steps:

  1. Release any site pointer that is currently being held.
  2. If the pointer passed to SetSite is set to NULL, the band is being removed. SetSite can return S_OK.
  3. If the pointer passed to SetSite is non-NULL, a new site is being set. SetSite should do the following:
    1. Call QueryInterface on the site for its IOleWindow interface.
    2. Call IOleWindow::GetWindow to obtain the parent window's handle, and save it for future use. Release IOleWindow if it is no longer needed.
    3. Create the band object's window as a child of the window obtained in the previous step. Do not create it as a visible window.
    4. If the band object implements IInputObject, call QueryInterface on the site for its IInputObjectSite interface. Store the pointer to this interface for use later.
    5. If all steps are successful, return S_OK. If not, return the OLE-defined error code indicating what failed.

The Explorer Bar sample implements SetSite in the following way. For future reference, m_pSite is a private member variable that holds the IInputObjectSite pointer and m_hwndParent holds the parent window's handle.

STDMETHODIMP CExplorerBar::SetSite(IUnknown* punkSite)
{
//If a site is being held, release it.
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

//If punkSite is not NULL, a new site is being set.
if(punkSite)
   {
   //Get the parent window.
   IOleWindow  *pOleWindow;

   m_hwndParent = NULL;

   if(SUCCEEDED(punkSite->QueryInterface(IID_IOleWindow, (LPVOID*)&pOleWindow)))
      {
      pOleWindow->GetWindow(&m_hwndParent);
      pOleWindow->Release();
      }

   if(!m_hwndParent)
      return E_FAIL;

   if(!RegisterAndCreateWindow())
      return E_FAIL;

   //Get and keep the IInputObjectSite pointer.
   if(SUCCEEDED(punkSite->QueryInterface(IID_IInputObjectSite, (LPVOID*)&m_pSite)))
      {
      return S_OK;
      }
   return E_FAIL;
   }
return S_OK;
}

The sample's GetSite implementation simply wraps a call to the site's QueryInterface method, using the site pointer saved by SetSite.

STDMETHODIMP CExplorerBar::GetSite(REFIID riid, LPVOID *ppvReturn)
{
*ppvReturn = NULL;

if(m_pSite)
   return m_pSite->QueryInterface(riid, ppvReturn);

return E_FAIL;
}

Window creation is handled by the private RegisterAndCreateWindow method. If the window does not exist, this method creates the the Explorer Bar's window as an appropriately sized child of the parent window obtained by SetSite. The child window's handle is stored in m_hwnd.

BOOL CExplorerBar::RegisterAndCreateWindow(void)
{
//If the window doesn't exist yet, create it now.
if(!m_hWnd)
   {
   //Can't create a child window without a parent.
   if(!m_hwndParent)
      {
      return FALSE;
      }

   //If the window class has not been registered, then do so.
   WNDCLASS wc;
   if(!GetClassInfo(g_hInst, EB_CLASS_NAME, &wc))
      {
      ZeroMemory(&wc, sizeof(wc));
      wc.style          = CS_HREDRAW | CS_VREDRAW | CS_GLOBALCLASS;
      wc.lpfnWndProc    = (WNDPROC)WndProc;
      wc.cbClsExtra     = 0;
      wc.cbWndExtra     = 0;
      wc.hInstance      = g_hInst;
      wc.hIcon          = NULL;
      wc.hCursor        = LoadCursor(NULL, IDC_ARROW);
      wc.hbrBackground  = (HBRUSH)CreateSolidBrush(RGB(0, 0, 192));
      wc.lpszMenuName   = NULL;
      wc.lpszClassName  = EB_CLASS_NAME;

      if(!RegisterClass(&wc))
         {
         //If RegisterClass fails, CreateWindow below will fail.
         }
      }

   RECT  rc;

   GetClientRect(m_hwndParent, &rc);

   //Create the window. The WndProc will set m_hWnd.
   CreateWindowEx(   0,
                     EB_CLASS_NAME,
                     NULL,
                     WS_CHILD | WS_CLIPSIBLINGS | WS_BORDER,
                     rc.left,
                     rc.top,
                     rc.right - rc.left,
                     rc.bottom - rc.top,
                     m_hwndParent,
                     NULL,
                     g_hInst,
                     (LPVOID)this);

   }
return (NULL != m_hWnd);
}
The IPersistStream Interface

Internet Explorer will call the Explorer Bar's IPersistStream interface to allow the Explorer Bar to load or save persistent data. If there is no persistent data, the methods must still return a success code. The IPersistStream interface inherits from IPersist, so five methods must be implemented: GetClassID, IsDirty, Load, Save, GetSizeMax.

The Explorer Bar sample does not use any persistent data and has only a minimal implementation of IPersistStream. GetClassID returns the object's CLSID (CLSID_SampleExplorerBar), and the remainder return either S_OK, S_FALSE, or E_NOTIMPL. See IPersistStream implementation for details.

The IDeskBand Interface

The IDeskBand interface is specific to band objects. In addition to its one method, it inherits from IDockingWindow, which in turn inherits from IOleWindow.

There are two IOleWindow methods: GetWindow and ContextSensitiveHelp. The Explorer Bar sample's implementation of GetWindow returns the Explorer Bar's child window handle, m_hwnd. Context-sensitive Help is not implemented, so ContextSensitiveHelp returns E_NOTIMPL.

The IDockingWindow interface has three methods: ShowDW, CloseDW, and ResizeBorder. The ResizeBorder method is not used with any type of band object and should always return E_NOTIMPL. The ShowDW method either shows or hides the Explorer Bar's window, depending on the value of its parameter:

STDMETHODIMP CExplorerBar::ShowDW(BOOL fShow)
{
if(m_hWnd)
   {
   if(fShow)
      {
      //show our window
      ShowWindow(m_hWnd, SW_SHOW);
      }
   else
      {
      //hide our window
      ShowWindow(m_hWnd, SW_HIDE);
      }
   }

return S_OK;
}

The CloseDW method destroys the Explorer Bar's window:

STDMETHODIMP CExplorerBar::CloseDW(DWORD dwReserved)
{
ShowDW(FALSE);

if(IsWindow(m_hWnd))
   DestroyWindow(m_hWnd);

m_hWnd = NULL;

return S_OK;
}

The remaining method, GetBandInfo, is specific to IDeskBand. Internet Explorer uses it to specify the Explorer Bar's identifier and viewing mode. Internet Explorer also may request one or more pieces of information from the Explorer Bar by filling the dwMask member of the DESKBANDINFO structure that is passed as the third parameter. GetBandInfo should store the identifier and viewing mode, and fill the DESKBANDINFO structure with the requested data. The Explorer Bar sample implements GetBandInfo as follows:

STDMETHODIMP CExplorerBar::GetBandInfo(DWORD dwBandID, DWORD dwViewMode, DESKBANDINFO* pdbi)
{
if(pdbi)
   {
   m_dwBandID = dwBandID;
   m_dwViewMode = dwViewMode;

   if(pdbi->dwMask & DBIM_MINSIZE)
      {
      pdbi->ptMinSize.x = MIN_SIZE_X;
      pdbi->ptMinSize.y = MIN_SIZE_Y;
      }
   if(pdbi->dwMask & DBIM_MAXSIZE)
      {
      pdbi->ptMaxSize.x = -1;
      pdbi->ptMaxSize.y = -1;
      }
   if(pdbi->dwMask & DBIM_INTEGRAL)
      {
      pdbi->ptIntegral.x = 1;
      pdbi->ptIntegral.y = 1;
      }
   if(pdbi->dwMask & DBIM_ACTUAL)
      {
      pdbi->ptActual.x = 0;
      pdbi->ptActual.y = 0;
      }
   if(pdbi->dwMask & DBIM_TITLE)
      {
      lstrcpyW(pdbi->wszTitle, L"Sample Explorer Bar");
      }
   if(pdbi->dwMask & DBIM_MODEFLAGS)
      {
      pdbi->dwModeFlags = DBIMF_VARIABLEHEIGHT;
      }
   if(pdbi->dwMask & DBIM_BKCOLOR)
      {
      //Use the default background color by removing this flag.
      pdbi->dwMask &= ~DBIM_BKCOLOR;
      }
   return S_OK;
   }
return E_INVALIDARG;
}

Optional Interface Implementations

There are two interfaces that are not required, but that may be useful to implement: IInputObject and IContextMenu. The Explorer Bar sample implements IInputObject. Refer to the documentation for information on how to implement IContextMenu.

The IInputObject Interface

The IInputObject interface must be implemented if a band object accepts user input. Internet Explorer implements IInputObjectSite and uses IInputObject to maintain proper user input focus when it has more than one contained window. There are three methods that need to be implemented by an Explorer Bar: UIActivateIO, HasFocusIO, and TranslateAcceleratorIO.

Internet Explorer calls UIActivateIO to inform the Explorer Bar that it is being activated or deactivated. When activated, the Explorer Bar sample calls SetFocus to set the focus to its window.

Internet Explorer calls HasFocusIO when it is attempting to determine which window has focus. If the Explorer Bar's window or one of its descendants has focus, HasFocusIO should return S_OK. If not, it should return S_FALSE.

TranslateAcceleratorIO allows the object to process keyboard accelerators. The Explorer Bar sample does not implement this method, so it returns S_FALSE.

The sample bar's implementation of IInputObjectSite is as follows:

STDMETHODIMP CExplorerBar::UIActivateIO(BOOL fActivate, LPMSG pMsg)
{
if(fActivate)
   SetFocus(m_hWnd);

return S_OK;
}

STDMETHODIMP CExplorerBar::HasFocusIO(void)
{
if(m_bFocus)
   return S_OK;

return S_FALSE;
}

STDMETHODIMP CExplorerBar::TranslateAcceleratorIO(LPMSG pMsg)
{
return S_FALSE;
}

The Window Procedure

Because a band object uses a child window for its display, it must implement a window procedure to handle Windows messaging. The Explorer band sample has minimal functionality, so its window procedure only handles five messages: WM_NCCREATE, WM_PAINT, WM_COMMAND, WM_SETFOCUS, and WM_KILLFOCUS. It can easily be expanded to accommodate additional messages to support more features.

LRESULT CALLBACK CExplorerBar::WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam)
{
CExplorerBar  *pThis = (CExplorerBar*)GetWindowLong(hWnd, GWL_USERDATA);

switch (uMessage)
   {
   case WM_NCCREATE:
      {
      LPCREATESTRUCT lpcs = (LPCREATESTRUCT)lParam;
      pThis = (CExplorerBar*)(lpcs->lpCreateParams);
      SetWindowLong(hWnd, GWL_USERDATA, (LONG)pThis);

      //set the window handle
      pThis->m_hWnd = hWnd;
      }
      break;
   case WM_PAINT:
      return pThis->OnPaint();
   case WM_COMMAND:
      return pThis->OnCommand(wParam, lParam);
   case WM_SETFOCUS:
      return pThis->OnSetFocus();
   case WM_KILLFOCUS:
      return pThis->OnKillFocus();
   }
return DefWindowProc(hWnd, uMessage, wParam, lParam);
}

The WM_COMMAND handler simply returns zero. The WM_PAINT handler creates the simple text display shown in the Explorer band example in the introduction:

LRESULT CExplorerBar::OnPaint(void)
{
PAINTSTRUCT ps;
RECT        rc;

BeginPaint(m_hWnd, &ps);
GetClientRect(m_hWnd, &rc);
SetTextColor(ps.hdc, RGB(255, 255, 255));
SetBkMode(ps.hdc, TRANSPARENT);
DrawText(ps.hdc, TEXT("Sample Explorer Bar"), -1, &rc, DT_SINGLELINE | DT_CENTER | DT_VCENTER);
EndPaint(m_hWnd, &ps);
return 0;
}
The WM_SETFOCUS and WM_KILLFOCUS handlers inform the site of a focus change by calling the site's IInputObjectSite::OnFocusChangeIS method.

LRESULT CExplorerBar::OnSetFocus(void)
{
FocusChange(TRUE);

return 0;
}

LRESULT CExplorerBar::OnKillFocus(void)
{
FocusChange(FALSE);
return 0;
}

void CExplorerBar::FocusChange(BOOL bFocus)
{
m_bFocus = bFocus;

//Inform the input object site that the focus has changed.
if(m_pSite)
   {
   m_pSite->OnFocusChangeIS((IDockingWindow*)this, bFocus);
   }
}

Summary

Band objects provide a flexible and powerful way to extend the capabilities of Internet Explorer by creating custom Explorer Bars. Implementing a desk band enables you to extend the capabilities of normal windows. Although some COM programming is required, it ultimately serves to provide a child window for your user interface. From there, the bulk of the implementation can use familiar Windows programming techniques. While the example discussed here has only limited functionality, it illustrates all the necessary features of a band object and it can be readily extended to create a unique and powerful user interface.


Using the Active Desktop Object

This article contains information on the ActiveDesktop object that is part of the Microsoft® Windows® Shell API. This object, through its IActiveDesktop interface, enables you to add, remove, and change items on the desktop.

Overview of the Active Desktop Interface

The Active Desktop is a feature of Microsoft Internet Explorer 4.0 that enables you to include HTML documents and items (such as ActiveX® Controls and Java applets) directly to your desktop. The IActiveDesktop interface, which is part of the Windows Shell API, is used to programmatically add, remove, and modify the items on the desktop. Active Desktop items can also be added using a Channel Definition Format (CDF) file.

Accessing the Active Desktop

To access the Active Desktop, a client application would need to create an instance of the ActiveDesktop object (CLSID_ActiveDesktop) with the CoCreateInstance function and retrieve a pointer to the object's IActiveDesktop interface.

The following sample shows how to retrieve a pointer to the IActiveDesktop interface.

HRESULT hr;
IActiveDesktop *pActiveDesktop;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
            IID_IActiveDesktop, (void**)&pActiveDesktop);

//Insert code to call the IActiveDesktop methods

// Call the Release method
pActiveDesktop->Release();

Adding a Desktop Item

There are three methods you can use to add a desktop item: IActiveDesktop::AddDesktopItem, IActiveDesktop::AddDesktopItemWithUI, and IActiveDesktop::AddUrl. Each desktop item added to the Active Desktop must have a different source URL.

The IActiveDesktop::AddDesktopItemWithUI and IActiveDesktop::AddUrl both provide the option to display the various user interfaces that can be displayed before adding a desktop item to the Active Desktop. The interfaces verify whether users want to add the desktop item to their Active Desktop. The interfaces also notify users of any security risks that are warranted by the URL security zone settings, and they ask users if they would like to create a subscription for this desktop item. Both methods also provide a way of suppressing the user interfaces. The IActiveDesktop::AddDesktopItem method requires a call to IActiveDesktop::ApplyChanges in order to update the registry. For the IActiveDesktop::AddDesktopItemWithUI, the client application must immediately release the IActiveDesktop interface and then use the CoCreateInstance function to retrieve an interface to an instance of the ActiveDesktop object that includes the newly added desktop item.

The IActiveDesktop::AddDesktopItem method adds the specified desktop item to the Active Desktop without any user interface, unless the URL security zone settings prevent it. If the URL security zone settings do not allow the desktop item to be added without prompting the user, the method fails. IActiveDesktop::AddDesktopItem also requires a call to IActiveDesktop::ApplyChanges in order to update the registry.

The following sample demonstrates how to add a desktop item with the IActiveDesktop::AddDesktopItem method.

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
            IID_IActiveDesktop, (void**)&pActiveDesktop);

// Initialize the COMPONENT structure
compDesktopItem.dwSize = sizeof(COMPONENT);

// Insert code that adds the information about the desktop item to the COMPONENT structure

// Add the desktop item
pActiveDesktop->AddDesktopItem(&compDesktopItem,0);

// Save the changes to the registry
pActiveDesktop->ApplyChanges(AD_APPLY_ALL);

Enumerating the Desktop Items

To enumerate the desktop items currently installed on the Active Desktop, the client application needs to retrieve the total number of desktop items installed using the IActiveDesktop::GetDesktopItemCount method and then creating a loop that retrieves the COMPONENT structure for each desktop item by calling the IActiveDesktop::GetDesktopItem method using the desktop item index.

The following sample demonstrates one way to enumerate the desktop items.

HRESULT hr;
IActiveDesktop *pActiveDesktop;
COMPONENT compDesktopItem;
int intCount;
int intIndex = 0;

//Create an instance of the Active Desktop
hr = CoCreateInstance(CLSID_ActiveDesktop, NULL, CLSCTX_INPROC_SERVER,
            IID_IActiveDesktop, (void**)&pActiveDesktop);

pActiveDesktop->GetDesktopItemCount(&intCount,0);

compDesktopItem.dwSize = sizeof(COMPONENT);

while(intIndex<=(intCount-1))
{
    //get the COMPONENT structure for the current desktop item
    pActiveDesktop->GetDesktopItem(intIndex, &compDesktopItem,0);

    //Insert code that processes the structure

    //Increment the index
    intIndex++;

    //Insert code to clean-up structure for next component
}

// Call the Release method
pActiveDesktop->Release();


Control Panel Applications

Control Panel applications are special-purpose dynamic-link libraries (DLLs) that let users configure the environment of Microsoft® Windows®.

This section describes Control Panel applications and explains the functions and messages they use and process to complete their work.

  • About Control Panel Applications
  • Creating Control Panel Applications
  • Executing Control Panel Applications
  • Extending System Control Panels

About Control Panel Applications

Although Windows provides a number of standard Control Panel applications, you can create additional applications that let users examine and modify the settings and operational modes of specific hardware and software.

Application Responsibilities and Operation

The primary responsibility of any Control Panel application is to display a window (typically a dialog box or property sheet) and to carry out any tasks specified by the user. Despite this responsibility, Control Panel applications do not provide menus or other direct means for users to access their dialog boxes. Instead, these applications operate under the control of another application and launch their subprograms only when requested by the controlling application.

Control Panel applications, such as the Mouse application, are usually controlled by a Windows system utility specifically designed to give users access to these applications. However, any application can load and manage Control Panel applications as long as the controlling application sends messages and processes return values in a way recognized by Control Panel applications.

Most Control Panel applications display and manage a single subprogram, giving the user control of the settings and operational modes of a single system component. However, any given Control Panel application can provide any number of subprograms to control any number of system components. To distinguish between subprograms, a Control Panel application typically supplies the controlling application with a unique icon for each subprogram. The controlling application displays these icons, and the user can choose a subprogram by choosing the corresponding icon.

Application Entry-Point Function

Every Control Panel application must export the standard entry-point function, CPlApplet. This function receives requests in the form of Control Panel (CPL) messages and then carries out the requested work—initializing the application, displaying and managing the dialog box(es), and closing the application.

When the controlling application first loads the Control Panel application, it retrieves the address of the CPlApplet function and subsequently uses the address to call the function and pass it messages. The controlling application might send the following messages.

Message | Description
CPL_DBLCLK | Sent to notify CPlApplet that the user has chosen the icon associated with a given subprogram. CPlApplet should display the corresponding dialog box and carry out any user-specified tasks.
CPL_EXIT | Sent after the last CPL_STOP message and immediately before the controlling application uses the FreeLibrary function to free the DLL containing the Control Panel application. CPlApplet should free any remaining memory and prepare to close.
CPL_GETCOUNT | Sent after the CPL_INIT message to prompt CPlApplet to return a number that indicates how many subprograms it supports.
CPL_INIT | Sent immediately after the DLL containing the Control Panel application is loaded. The message prompts CPlApplet to perform initialization procedures, including memory allocation.
CPL_INQUIRE | Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified subprogram. The lParam1 value is an integer representing the zero-based index of the subprogram about which information is being requested. The lParam2 parameter of CPlApplet points to a CPLINFO structure.
CPL_NEWINQUIRE | Sent after the CPL_GETCOUNT message to prompt CPlApplet to provide information about a specified subprogram. The lParam1 value is an integer representing the zero-based index of the subprogram about which information is being requested. The lParam2 parameter is a pointer to a NEWCPLINFO structure. For better performance on Microsoft® Windows® 95 and Windows NT® version 4.0, your application should process CPL_INQUIRE and not CPL_NEWINQUIRE.
CPL_SELECT | Obsolete. Current versions of Windows do not send this message.
CPL_STARTWPARAMS | Sent to notify CPlApplet that the user has chosen the icon associated with a given dialog box. CPlApplet should display the corresponding dialog box and carry out any user-specified tasks. This message is similar to CPL_DBLCLK, but there might be some additional information. The lParam1 parameter is the subprogram number and lParam2 is an LPCTSTR to any extra directions that might be necessary. CPlApplet should return TRUE if this message is handled, or FALSE if not. This message is valid for version 5.00 and later of Shell32.dll.
CPL_STOP | Sent once for each subprogram before the controlling application unloads the Control Panel extension. CPlApplet should free any memory associated with the subprogram number provided in lParam1.

Message Processing

The CPlApplet callback function processes all messages sent to a Control Panel application by a controlling application. Messages sent to the function should be in a specific order. By the same token, the application requires the messages to be processed in a specific way.

First, the CPlApplet function receives the CPL_INIT message when the controlling application first loads the Control Panel application. The function should carry out any initialization, such as allocating memory, and return nonzero. If CPlApplet cannot complete the initialization, it must return zero, directing the controlling application to terminate communication and release the DLL.

Next, if the CPL_INIT message succeeded, the controlling application sends the CPL_GETCOUNT message. The function must then return the number of subprograms supported by the Control Panel application.

The CPlApplet function then receives one CPL_INQUIRE message and one CPL_NEWINQUIRE message for each subprogram supported by the Control Panel application. The function fills in a CPLINFO or NEWCPLINFO structure with information about your application, such as its name, icon, and a descriptive string. Most applications should process the CPL_INQUIRE message and ignore the CPL_NEWINQUIRE message. The CPL_INQUIRE message provides information in a form that the controlling application can cache, resulting in much better performance. The CPL_NEWINQUIRE message is useful only if you need to change your application's icon or display strings based on the state of the computer.

The CPlApplet function next receives a CPL_DBLCLK message as a notification that the user has chosen the icon representing the subprogram. The function might receive this message any number of times. The message includes the subprogram identifier and the value contained in the lData parameter. The function should display the corresponding dialog box and process subsequent user input.

Before the controlling application terminates, CPlApplet receives the CPL_STOP message once for each subprogram supported by the Control Panel application. The message includes the identifier for the subprogram and the lData value. The function should free any memory that it allocated for the specified dialog box.

After the last CPL_STOP message, CPlApplet receives a CPL_EXIT message. The function should free all remaining allocated memory and unregister any private window classes that it might have registered. Immediately after the function returns from this message, the controlling application releases the Control Panel application by calling the FreeLibrary function.

Application Setup

Every Control Panel application is a dynamic-link library. However, the DLL file must have a .cpl file name extension. For Windows 2000 and later systems, new Control Panel applications should be installed in the associated application's folder under the Program Files folder. The DLL's path must be registered in one of two ways:

  • If the Control Panel application is to be available to all users, register the path on a per-computer basis by adding a REG_EXPAND_SZ value to the HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Control Panel\Cpls key, set to the DLL path.
  • If the Control Panel application is to be available on a per-user basis, use HKEY_CURRENT_USER as the root key instead of HKEY_LOCAL_MACHINE.

The following two examples register the MyCplApp Control Panel application. The DLL is named MyCpl.cpl and is located in the MyCorp\MyApp application directory. The first registry entry illustrates per-computer registration, and the second illustrates per-user registration.

HKEY_LOCAL_MACHINE
    Software
        Microsoft
            Windows
                CurrentVersion
                    Control Panel
                        Cpls
                            MyCpl="%ProgramFiles%\MyCorp\MyApp\MyCpl.cpl"

-or-

HKEY_CURRENT_USER
    Software
        Microsoft
            Windows
                CurrentVersion
                    Control Panel
                        Cpls
                            MyCpl="%ProgramFiles%\MyCorp\MyApp\MyCpl.cpl"

For systems prior to Windows 2000, new Control Panel applications must be set up in one of the following ways:

  • Copy the DLL to the directory that contains the Windows system utility.
  • Copy the DLL to the Windows SYSTEM directory.
  • Write the path of the DLL using the WritePrivateProfileString function, specifying the string "MMCPL" as the section name and the string "control.ini" as the file name (no path). Do not actually write directly to the control.ini file. Instead, use the WritePrivateProfileString function, which automatically handles differences among platforms. The following example demonstrates how you would set up the path for MyCpl.cpl.
    • WritePrivateProfileString("MMCPL",
                          "MyCpl.cpl",
                          "C:\\mydir\\MyCpl.cpl",
                          "control.ini");

    Note control.ini can also restrict which Control Panel applications are loaded. It is not recommended that applications alter Control.ini for this purpose.

Creating Control Panel Applications

Although a Control Panel application can support more than one subprogram, it processes all requests through the single CPlApplet function. In the following example, the Control Panel application supports three subprograms that let the user set preferences for a component stereo system attached to the computer. The example uses an application-defined StereoSubProgs array that contains three structures, each corresponding to one of the subprograms. Each structure contains all the information required by the CPL_INQUIRE message as well as the dialog box template and dialog box procedure required by the CPL_DBLCLK message. The code demonstrates how to fill the structures in the StereoSubProgs array.

#define NUM_SUBPROGS 3

typedef struct tagSubProg
{
    int icon;         // icon resource identifier
    int namestring;   // name-string resource identifier
    int descstring;   // description-string resource identifier
    int dlgtemplate;  // dialog box template resource identifier
    DLGPROC dlgfn;    // dialog box procedure
} SUBPROG;

SUBPROG StereoSubProgs[NUM_SUBPROGS] =
{
    {AMP_ICON, AMP_NAME, AMP_DESC, AMP_DLG, AmpDlgProc,},
    {TUNER_ICON, TUNER_NAME, TUNER_DESC, TUNER_DLG, TunerDlgProc,},
    {TAPE_ICON, TAPE_NAME, TAPE_DESC, TAPE_DLG, TapeDlgProc,},
};

HANDLE  hinst = NULL;

LONG CALLBACK CPlApplet(hwndCPL, uMsg, lParam1, lParam2)
HWND hwndCPL;      // handle to Control Panel window
UINT uMsg;         // message
LPARAM lParam1;    // first message parameter
LPARAM lParam2;    // second message parameter
{
    int i;
    LPCPLINFO lpCPlInfo;

    i = (int) lParam1;

    switch (uMsg) {
        case CPL_INIT:      // first message, sent once
            hinst = GetModuleHandle("ecp.cpl");
            return TRUE;

        case CPL_GETCOUNT:  // second message, sent once
            return NUM_SUBPROGS;
            break;

        case CPL_INQUIRE: // third message, sent once per application
            lpCPlInfo = (LPCPLINFO) lParam2;
            lpCPlInfo->lData = 0;
            lpCPlInfo->idIcon = StereoSubProgs[i].icon;
            lpCPlInfo->idName = StereoSubProgs[i].namestring;
            lpCPlInfo->idInfo = StereoSubProgs[i].descstring;
            break;

        case CPL_DBLCLK:    // application icon double-clicked
            DialogBox(hinst,
                MAKEINTRESOURCE(StereoSubProgs[i].dlgtemplate),
                hwndCPL, StereoSubProgs[i].dlgfn);
            break;

        case CPL_STOP:      // sent once per application before CPL_EXIT
            break;

        case CPL_EXIT:    // sent once before FreeLibrary is called
            break;

        default:
            break;
    }
    return 0;
}

Executing Control Panel Applications

There are two ways to start a Control Panel application:

  • The user can open Control Panel and start an application by double-clicking the application icon.
  • The user or an application can start a Control Panel application by executing it directly from the command line prompt.

An application can open the Control Panel programmatically using the WinExec function.

WinExec("control.exe", SW_NORMAL);

The following example shows how an application can start the Control Panel application named MyCpl.cpl by using the WinExec function.

WinExec("control.exe MyCpl.cpl", SW_NORMAL);

When Control Panel starts, it immediately executes the Control Panel application MyCpl.cpl. After the user finishes using the application and closes it, Control Panel ends.

When you use the WinExec function, the system can recognize special Control Panel commands.

control.exe desktop | Launches the Desktop Control Panel subprogram.
control.exe color | Launches the Desktop Control Panel subprogram, with the Appearance tab preselected.
control.exe date/time | Launches the Date/Time Control Panel subprogram.
control.exe international | Launches the Regional Settings Control Panel subprogram.
control.exe mouse | Launches the Mouse Control Panel subprogram.
control.exe keyboard | Launches the Keyboard Control Panel subprogram.
control.exe printers | Displays the Printers folder.
control.exe fonts | Displays the Fonts folder.

For Windows 2000 and later systems:

control.exe folders | Launches the Folder Settings Control Panel subprogram.
control.exe netware | Launches the Novell NetWare Control Panel subprogram (if installed).
control.exe telephony | Launches the Phone and Modem Options Control Panel subprogram.
control.exe admintools | Displays the Administrative Tools folder.
control.exe schedtasks | Displays the Scheduled Tasks folder.
control.exe netconnections | Displays the Network and Dial-Up Connections folder.
control.exe infrared | Launches the Infrared Control Panel subprogram (if installed).
control.exe userpasswords | Launches the Users and Passwords Control Panel subprogram.

Extending System Control Panels

Some of the system control panels are extensible. To install a control panel extension, register your Shell extension as follows, where name is the predefined name of the system control panel application (see table below).

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            CurrentVersion
               Controls Folder
                  name
                     shellex
                        PropertySheetHandlers

This is similar to the way you would register an extension for a predefined Shell object. Since the only Shell extensions supported by control panels are property sheets, the registration must be under the shellex\PropertySheetHandlers key.

Control Panel | name | Remarks
Display | Desk |
Display Settings Advanced | Device | Non-hardware-specific advanced properties
Display Settings Advanced | Display | Hardware-specific advanced properties
Mouse | Mouse |
Keyboard | Keyboard |
Internet | Internet |


Handling Screen Savers

The Microsoft® Win32® application programming interface (API) supports special applications called screen savers. Screen savers start when the mouse and keyboard have been idle for a specified period of time. They are used for these two reasons:

  • To protect a screen from phosphor burn caused by static images.
  • To conceal sensitive information left on a screen.

This topic is divided into the following sections.
  • About Screen Savers
  • Using the Screen Saver Functions

About Screen Savers

The Desktop application in the Microsoft® Windows® Control Panel lets users select from a list of screen savers, specify how much time should elapse before the screen saver starts, configure screen savers, and preview screen savers. Screen savers are loaded automatically when Windows starts or when a user activates the screen saver through the Control Panel.

Once a screen saver is chosen, Windows monitors keystrokes and mouse movements and then starts the screen saver after a period of inactivity. However, Windows does not start the screen saver if any of the following conditions exist:

  • The active application is not a Windows-based application.
  • A computer-based training (CBT) window is present.
  • The active application receives the WM_SYSCOMMAND message with the wParam parameter set to the SC_SCREENSAVE value, but it does not pass the message to the DefWindowProc function.

Screen savers contain specific exported functions, resource definitions, and variable declarations. The screen saver library contains the main function and other startup code required for a screen saver. When a screen saver starts, the startup code in the screen saver library creates a full-screen window. The window class for this window is declared as follows:

WNDCLASS cls;

cls.hCursor        = NULL;
cls.hIcon          = LoadIcon(hInst, MAKEINTATOM(ID_APP));
cls.lpszMenuName   = NULL;
cls.lpszClassName  = "WindowsScreenSaverClass";
cls.hbrBackground  = GetStockObject(BLACK_BRUSH);
cls.hInstance      = hInst;
cls.style          = CS_VREDRAW | CS_HREDRAW |
                     CS_SAVEBITS | CS_DBLCLKS;
cls.lpfnWndProc    = (WNDPROC) ScreenSaverProc;
cls.cbWndExtra     = 0;
cls.cbClsExtra     = 0;

To create a screen saver, most developers create a source code module containing three required functions and link them with the screen saver library. A screen saver module is responsible only for configuring itself and for providing visual effects.

One of the three required functions in a screen saver module is ScreenSaverProc. This function processes specific messages and passes any unprocessed messages back to the screen saver library. Following are some of the typical messages processed by ScreenSaverProc.
Message | Meaning
WM_CREATE | Retrieve any initialization data from the Regedit.ini file. Set a window timer for the screen saver window. Perform any other required initialization.
WM_ERASEBKGND | Erase the screen saver window and prepare for subsequent drawing operations.
WM_TIMER | Perform drawing operations.
WM_DESTROY | Destroy the timers created when the application processed the WM_CREATE message. Perform any additional required cleanup.

ScreenSaverProc passes unprocessed messages to the screen saver library by calling the DefScreenSaverProc function. The following table describes how this function processes various messages.
Message | Action
WM_SETCURSOR | Set the cursor to the null cursor, removing it from the screen.
WM_PAINT | Paint the screen background.
WM_LBUTTONDOWN | Terminate the screen saver.
WM_MBUTTONDOWN | Terminate the screen saver.
WM_RBUTTONDOWN | Terminate the screen saver.
WM_KEYDOWN | Terminate the screen saver.
WM_MOUSEMOVE | Terminate the screen saver.
WM_ACTIVATE | Terminate the screen saver if the wParam parameter is set to FALSE.

The second required function in a screen saver module is ScreenSaverConfigureDialog. This function displays a dialog box that enables the user to configure the screen saver (an application must provide a corresponding dialog box template). Windows displays the configuration dialog box when the user selects the Setup button in the Control Panel's Screen Saver dialog box.

The third required function in a screen saver module is RegisterDialogClasses. This function must be called by all screen saver applications. However, applications that do not require special windows or custom controls in the configuration dialog box can simply return TRUE. Applications requiring special windows or custom controls should use this function to register the corresponding window classes.

In addition to creating a module that supports the three functions just described, a screen saver should supply an icon. This icon is visible only when the screen saver is run as a standalone application. (To be run by the Control Panel, a screen saver must have the .scr file name extension; to be run as a standalone application, it must have the .exe file name extension.) The icon must be identified in the screen saver's resource file by the constant ID_APP, which is defined in the Scrnsave.h header file.

One final requirement is a screen saver description string. The resource file for a screen saver must contain a string that the Control Panel displays as the screen saver name. The description string must be the first string in the resource file's string table (identified with the ordinal value 1).

Using the Screen Saver Functions

This section uses example code taken from a screen saver application to illustrate the following tasks:

  • Creating a Screen Saver
  • Installing New Screen Savers
  • Adding Help to the Screen Saver Configuration Dialog Box

Creating a Screen Saver

At intervals ranging from 1 through 10 seconds, the application in this example repaints the screen with one of four colors: white, light gray, dark gray, and black. The application paints the screen each time it receives a WM_TIMER message. The user can adjust the interval at which this message is sent by selecting the application's configuration dialog box and adjusting a single horizontal scroll bar.

Screen saver library

The static screen saver functions are contained in the screen saver library. There are two versions of the library available, Scrnsave.lib and Scrnsavw.lib. You must link your project with one of these. Scrnsave.lib is used for screen savers that use ANSI characters, and Scrnsavw.lib is used for screen savers that use UNICODE characters. A screen saver that is linked with Scrnsavw.lib will only run on Windows platforms that support UNICODE, while a screen saver linked with Scrnsave.lib will run on any Windows platform.

Supporting the configuration dialog box

Most screen savers provide a configuration dialog box to let the user specify customization data such as unique colors, drawing speeds, line thickness, fonts, and so on. To support the configuration dialog box, the application must provide a dialog box template and must also support the ScreenSaverConfigureDialog function. Following is the dialog box template for the sample application.

DLG_SCRNSAVECONFIGURE DIALOG 6, 18, 160, 63
LANGUAGE LANG_NEUTRAL, SUBLANG_NEUTRAL
STYLE DS_MODALFRAME | WS_POPUP | WS_VISIBLE | WS_CAPTION |
    WS_SYSMENU
CAPTION "Sample Screen-Saver Setup"
FONT 8, "MS Shell Dlg"
BEGIN
    GROUPBOX      "Redraw Speed", 101, 0, 6, 98, 40
    SCROLLBAR     ID_SPEED, 5, 31, 89, 10
    LTEXT         "Fast", 103, 6, 21, 20, 8
    LTEXT         "Slow", 104, 75, 21, 20, 8
    PUSHBUTTON    "OK", ID_OK, 117, 10, 40, 14
    PUSHBUTTON    "Cancel", ID_CANCEL, 117, 32, 40, 14
END

You must define the constant used to identify the dialog box template by using the decimal value 2003, as in the following example:

#define  DLG_SCRNSAVECONFIGURE 2003

The following example shows the ScreenSaverConfigureDialog function found in the sample application.

#define MINVEL  1               /* minimum redraw speed value    */
#define MAXVEL  10              /* maximum redraw speed value    */
#define DEFVEL  5               /* default redraw speed value    */

LONG    lSpeed = DEFVEL;        /* redraw speed variable         */

extern HINSTANCE hMainInstance; /* screen saver instance handle  */

CHAR   szAppName[80];           /* .ini section name             */
CHAR   szTemp[20];              /* temporary array of characters */
CHAR   szRedrawSpeed[ ] = "Redraw Speed";   /* .ini speed entry   */

BOOL WINAPI ScreenSaverConfigureDialog(hDlg, message, wParam, lParam)
HWND  hDlg;
UINT  message;
DWORD wParam;
LONG  lParam;
{
    static HWND hSpeed; /* handle to speed scroll bar */
    static HWND hOK;    /* handle to OK push button */

    switch(message)
    {
        case WM_INITDIALOG:

            /* Retrieve the application name from the .rc file. */

            LoadString(hMainInstance, idsAppName, szAppName, 40);

            /* Retrieve the .ini (or registry) file name. */

            LoadString(hMainInstance, idsIniFile, szIniFile,
                MAXFILELEN);

            /* Retrieve any redraw speed data from the registry. */

            lSpeed = GetPrivateProfileInt(szAppName, szRedrawSpeed,
                DEFVEL, szIniFile);

            /*
             * If the initialization file does not contain an entry
             * for this screen saver, use the default value.
             */

            if(lSpeed > MAXVEL || lSpeed < MINVEL)
                lSpeed = DEFVEL;

            /* Initialize the redraw speed scroll bar control. */

            hSpeed = GetDlgItem(hDlg, ID_SPEED);
            SetScrollRange(hSpeed, SB_CTL, MINVEL, MAXVEL, FALSE);
            SetScrollPos(hSpeed, SB_CTL, lSpeed, TRUE);

            /* Retrieve a handle to the OK push button control. */

            hOK = GetDlgItem(hDlg, ID_OK);

            return TRUE;

        case WM_HSCROLL:

            /*
             * Process scroll bar input, adjusting the lSpeed
             * value as appropriate.
             */

            switch (LOWORD(wParam))
                {
                    case SB_PAGEUP:
                        --lSpeed;
                    break;

                    case SB_LINEUP:
                        --lSpeed;
                    break;

                    case SB_PAGEDOWN:
                        ++lSpeed;
                    break;

                    case SB_LINEDOWN:
                        ++lSpeed;
                    break;

                    case SB_THUMBPOSITION:
                        lSpeed = HIWORD(wParam);
                    break;

                    case SB_BOTTOM:
                        lSpeed = MINVEL;
                    break;

                    case SB_TOP:
                        lSpeed = MAXVEL;
                    break;

                    case SB_THUMBTRACK:
                    case SB_ENDSCROLL:
                        return TRUE;
                    break;
                }
                if ((int) lSpeed <= MINVEL)
                    lSpeed = MINVEL;
                if ((int) lSpeed >= MAXVEL)
                    lSpeed = MAXVEL;

                SetScrollPos((HWND) lParam, SB_CTL, lSpeed, TRUE);
            break;

        case WM_COMMAND:
            switch(LOWORD(wParam))
            {
                case ID_OK:

                   /*
                    * Write the current redraw speed variable to
                    * the .ini file.
                    */

                    wsprintf(szTemp, "%ld", lSpeed);
                    WritePrivateProfileString(szAppName, szRedrawSpeed,
                        szTemp, szIniFile);

                case ID_CANCEL:
                    EndDialog(hDlg, LOWORD(wParam) == ID_OK);
                return TRUE;
            }
    }
    return FALSE;
}

In addition to providing the dialog box template and supporting the ScreenSaverConfigureDialog function, an application must also support the RegisterDialogClasses function. This function registers any nonstandard window classes required by the screen saver. Because the sample application used only standard window classes in its dialog box procedure, this function simply returns TRUE, as in the following example:

BOOL WINAPI RegisterDialogClasses(hInst)
HANDLE  hInst;
{
    return TRUE;
}

Supporting the screen saver window procedure

Each screen saver must support a window procedure named ScreenSaverProc. Like most window procedures, ScreenSaverProc processes a set of specific messages and passes any unprocessed messages to a default procedure. However, instead of passing them to the DefWindowProc function, ScreenSaverProc passes unprocessed messages to the DefScreenSaverProc function. Another difference between ScreenSaverProc and a normal window procedure is that the handle passed to ScreenSaverProc identifies the entire desktop rather than a client window. The following example shows the ScreenSaverProc window procedure for the sample screen saver.

LONG WINAPI ScreenSaverProc(hwnd, message, wParam, lParam)
HWND  hwnd;
UINT  message;
DWORD wParam;
LONG  lParam;
{
static HDC          hdc;    /* device-context handle */
static RECT         rc;     /* RECT structure */
static UINT         uTimer; /* timer identifier */

    switch(message)
    {
        case WM_CREATE:

            /* Retrieve the application name from the .rc file. */

            LoadString(hMainInstance, idsAppName, szAppName, 40);

            /* Retrieve the .ini (or registry) file name. */

            LoadString(hMainInstance, idsIniFile, szIniFile,
                MAXFILELEN);

            /* Retrieve any redraw speed data from the registry. */

            lSpeed = GetPrivateProfileInt(szAppName, szRedrawSpeed,
                DEFVEL, szIniFile);

           /*
            * Set a timer for the screen saver window using the
            * redraw rate stored in Regedit.ini.
            */

            uTimer = SetTimer(hwnd, 1, lSpeed * 1000, NULL);
            break;

        case WM_ERASEBKGND:

           /*
            * The WM_ERASEBKGND message is issued before the
            * WM_TIMER message, allowing the screen saver to
            * paint the background as appropriate.
            */

            hdc = GetDC(hwnd);
            GetClientRect (hwnd, &rc);
            FillRect (hdc, &rc, GetStockObject(BLACK_BRUSH));
            ReleaseDC(hwnd,hdc);
            break;

        case WM_TIMER:

           /*
            * The WM_TIMER message is issued at (lSpeed * 1000)
            * intervals, where lSpeed == .001 seconds. This
            * code repaints the entire desktop with a white,
            * light gray, dark gray, or black brush each
            * time a WM_TIMER message is issued.
            */

            hdc = GetDC(hwnd);
            GetClientRect(hwnd, &rc);
            if (i++ <= 4)
                FillRect(hdc, &rc, GetStockObject(i));
            else
                (i = 0);
            ReleaseDC(hwnd,hdc);
            break;

        case WM_DESTROY:

           /*
            * When the WM_DESTROY message is issued, the screen saver
            * must destroy any of the timers that were set at WM_CREATE
            * time.
            */

            if (uTimer)
                KillTimer(hwnd, uTimer);
            break;
    }

   /*
    * DefScreenSaverProc processes any messages
    * ignored by ScreenSaverProc.
    */

    return DefScreenSaverProc(hwnd, message, wParam, lParam);
}

Creating a module-definition file

The ScreenSaverProc and ScreenSaverConfigureDialog functions must be exported in the application's module-definition file; RegisterDialogClasses should not be exported, however. The following example shows the module-definition file for the sample application.

NAME    SSTEST.SCR

DESCRIPTION 'SCRNSAVE : Test'

STUB    'WINSTUB.EXE'
EXETYPE WINDOWS

CODE    MOVEABLE
DATA    MOVEABLE MULTIPLE

HEAPSIZE  1024
STACKSIZE 4096

EXPORTS
        ScreenSaverProc
        ScreenSaverConfigureDialog

Installing New Screen Savers

When compiling the list of available screen savers, the Control Panel searches the Windows Startup directory for files with the .scr extension. Because screen savers are standard Windows executable files with .exe extensions, you must rename them so they have .scr extensions and copy them to the correct directory.

Adding Help to the Screen Saver Configuration Dialog Box

The configuration dialog box for a screen saver typically includes a Help button. Screen saver applications can check for the Help button identifier and call the WinHelp function in the same way Help is provided in other Windows-based applications.


Creating Briefcase Reconcilers

A briefcase reconciler gives the Microsoft® Windows® Briefcase the means to reconcile different versions of a document.

  • About Briefcase Reconcilers
  • Briefcase Reconciler Reference

About Briefcase Reconcilers

A briefcase reconciler combines different input versions of a document to produce a single, new output version of the document. You might need to create a briefcase reconciler to support your type of document. This overview describes briefcase reconcilers and explains how to create them.

Reconciliation

A document is a collection of information that can be copied and changed. A document has different versions if the contents of at least two copies of the document are different. Reconciliation produces a single version of a document from two or more initial versions. Typically, the reconciled version is a combination of information from the initial versions with the most recent or most useful information preserved.

Reconciliation is initiated by the Briefcase when it determines that two or more copies of the same document are different. The Briefcase, which acts as the initiator in this context, locates and starts the briefcase reconciler associated with the given document type. The reconciler compares the documents and determines which portions of the documents to retain. Some reconcilers might require user interaction to complete reconciliation. Others might complete reconciliation without user interaction. The reconciler can be contained within an application or be an extension implemented as a dynamic-link library (DLL).

Some briefcase reconcilers might create residues. A residue is a document, usually having the same file type as the initial document, that contains information not saved in the merged version. Residues are typically used to give authors a quick way to determine what information from their original document is not in the final merged version. If a reconciler supports residues, it creates one residue for each of the original versions of the document. Residues are not created unless the initiator requests them. The Briefcase does not currently request residues, but future initiators might.

Some briefcase reconcilers work with the Briefcase to allow the user to terminate reconciliation. This is an important feature for a user who might decide that the reconciliation should not proceed. A reconciler typically provides a termination object when the reconciliation requires user interaction and might be lengthy. In some environments, a reconciler might allow partial reconciliation, enabling a user to temporarily suspend a reconciliation and resume it later. The Briefcase does not currently support partial reconciliation, however.

Creating a Briefcase Reconciler

You create a briefcase reconciler by implementing the reconciliation interfaces. At a minimum, a reconciler implements the IReconcilableObject interface and the IPersistStorage or IPersistFile interface. As the initiator, the Briefcase determines when reconciliation is needed and calls the IReconcilableObject::Reconcile method to initiate reconciliation.

Although IReconcilableObject::Reconcile provides a wide-ranging set of reconciliation capabilities, a briefcase reconciler carries out only minimal reconciliation in most cases. In particular, the Briefcase does not require the reconciler to support residue generation or to support the termination object. Also, the reconciler carries out a single top-to-bottom reconciliation and must not return the REC_E_NOTCOMPLETE value; that is, it should not attempt partial reconciliation.

The Briefcase provides the IReconcileInitiator interface. The briefcase reconciler can use the IReconcileInitiator::SetAbortCallback method to set the termination object. The Briefcase does not use version identifiers and cannot, therefore, provide previous versions of a document if a reconciler requests them using the corresponding methods in IReconcileInitiator.

The Briefcase passes to IReconcilableObject::Reconcile file monikers representing the versions of the document to be reconciled. The briefcase reconciler gains access to the versions by using either the IMoniker::BindToObject or IMoniker::BindToStorage method. The latter is generally faster and is recommended. The reconciler must release any objects or storage to which it binds.

When the briefcase reconciler uses IMoniker::BindToStorage, it binds to storage that is either flat storage (a stream) or OLE-defined structured storage. If the reconciler expects flat storage, it should use IMoniker::BindToStorage to request the IStream interface. If the reconciler expects structured storage, it should request the IStorage interface. In both cases, it should request read-only direct (nontransacted) access to the storage; read-write access might not be available.

A minimal briefcase reconciler typically looks directly at the storage of the other versions and deals with embedded objects in a very primitive manner, such as merging two versions of the object by including both versions in the output version.

The initiator locates the appropriate briefcase reconciler by using a subset of the logic implemented by the GetClassFile function to determine the class of a given file and then looks in the registry for the reconciler class associated with the given file class. The Briefcase, like other Shell components, determines the class of a file solely by the file name extension. A file's extension must have a registered class for the Briefcase to invoke a reconciler for the file. You must set a registry entry of the following form when installing your reconciler.

CLSID\file-clsid\Roles\Reconciler\reconciler-classid

The class must be quick loading, must be designated _MULTIPLEUSE, and, unless marshalers are provided for the reconciliation interface, must be an in-process server (contained in a DLL) rather than a local server (implemented in an .exe file).

User Interaction in Reconciliation

A briefcase reconciler should attempt to carry out reconciliation without user interaction. The more automated the reconciliation, the better the user's perception of the process.

In some cases, user intervention can be valuable. For example, a document system might require a user to review changes before accepting the merged version of a document or might require comments from the user explaining the changes that have been made. In these cases, the initiator, not the briefcase reconciler, is responsible for querying the user and carrying out the user's instructions.

In other cases, user intervention might be necessary—for example, when two versions have been edited in incompatible ways. In such cases, either the initiator or briefcase reconciler must query the user for instructions on how to resolve the conflict. In general, no initiator can rely on completing a reconciliation without expecting some user interaction. Reconcilers, on the other hand, have the option of interacting with the user to resolve conflicts or requiring the initiator to do so.

Reconciling Embedded Objects

When reconciling a document, the briefcase reconciler itself can become an initiator if it discovers an embedded object of a type that it cannot reconcile. In this case, the reconciler needs to recursively reconcile each of the embedded objects and assume all the responsibilities of an initiator.

To carry out the recursion, the briefcase reconciler loads the object and queries for the appropriate interface. The handler for the object must support the interface. If any method of the interface returns the OLE_E_NOTRUNNING value, the reconciler must run the object in order to carry out the operation. Because code for embedded objects is not always available, a reconciler must provide a solution for this condition. For example, the reconciler might include both old and new versions of the embedded object in the reconciled version. The reconciler must not attempt to reconcile across links.

The initiator stores the document versions being merged. In many cases, the initiator has access to the storage of each version and saves the result of reconciliation using similar storage. Sometimes, however, the initiator might have an in-memory object for which no persistent version is available. This situation can occur when a document containing open embedded objects must be reconciled before being saved. In such cases, the initiator saves the result of the reconciliation in the version found in memory.

The initiator uses the IPersistStorage interface to bind (load) the merged version. The initiator uses the IPersistStorage::Load method if an initial version has already been created and uses the IPersistStorage::InitNew method for the initial version. When the merged version is loaded, the initiator uses QueryInterface to retrieve the address of the IReconcilableObject interface. This interface gives the initiator access to the storage of the existing residues and gives it a way to create storage for any new residues. Then the initiator directs the interface to carry out the reconciliation. The initiator actually queries for the IPersistFile interface before IPersistStorage. If the reconciler supports IPersistFile, the initiator manipulates the replica through the IPersistFile rather than the IPersistStorage methods. This permits reconciliation of files that are not stored as compound documents.

When the reconciliation is complete, the initiator can save the merged version by using the IPersistStorage or IPersistFile interface. During reconciliation, the briefcase reconciler creates residues as needed and writes their persistent bits to storage. If the merged version is a stream, the IStorage interface passed to IPersistStorage::Load contains a stream named "Contents" with its storage state set to STATEBITS_FLAT. (You can set the state bits by using the IStorage::Stat method.) After the merge, the initiator saves the merged version by writing the data in an appropriate manner. It should ensure that STATEBITS_FLAT is set as appropriate for the storage.

Residues

The initiator indicates whether it wants residues by setting the pstgNewResidues parameter to a valid address when calling the IReconcilableObject::Reconcile method. If the reconciler does not support the creation of residues, it must return immediately the REC_E_NORESIDUES value, unless the dwFlags parameter specifies the RECONCILEF_NORESIDUESOK value.

The briefcase reconciler returns residues to the initiator by creating new storage elements and copying them to the array pointed to by pstgNewResidues. For structured storage residues, the reconciler copies an IStorage interface, and for flat storage residues, it copies either an IStream or an IStorage interface with the STATEBITS_FLAT flag set. The reconciler uses IStorage to create the necessary storage, using IStorage::CreateStream to create flat storage for a residue that is a stream and IStorage::CreateStorage to create structured storage.

The initiator prepares pstgNewResidues so that it contains no elements in the nonreserved part of the IStorage name space. The briefcase reconciler places each residue in an element whose name corresponds to the order of its initial version. For example, the first residue is contained in "1", the second in "2", and so on. If the reconciled object itself produces a residue, it is found in the element named "0".

The briefcase reconciler commits each of the newly created elements individually, ensuring that the initiator has access to the information. The reconciler does not, however, commit pstgNewResidues itself. The initiator is responsible for committing this or otherwise disposing of it.

Briefcase Reconciler Reference

This section contains information about the reconciliation interfaces. When handling errors, a method can return only those error values that are explicitly defined as possible return values. Furthermore, the method must set all variables whose addresses are passed as parameters to NULL before returning from the error.

Briefcase Reconciler Interfaces and Methods

  • IReconcilableObject
    • IReconcilableObject::GetProgressFeedbackMaxEstimate
    • IReconcilableObject::Reconcile
  • IReconcileInitiator
    • IReconcileInitiator::SetAbortCallback
    • IReconcileInitiator::SetProgressFeedback
  • INotifyReplica
    • INotifyReplica::YouAreAReplica


Working with Item ID Lists

The Item Identifier List and the pointer to an item identifier list (PIDL) uniquely identify objects in the namespace. For basic information about PIDLs and the Shell namespace in general, see The Shell Namespace. Many of the more advanced subjects dealing with PIDLs are covered in this section.

  • Walking a PIDL
  • Calculating the Size of an Identifier List
  • Making a Copy of a PIDL
  • Obtaining the Parent of a PIDL
  • Relative and Full PIDLs
  • Deleting a PIDL
  • Simple ID Lists

Walking a PIDL

A PIDL points to the first item ID in the item identifier list. To access the subsequent items in the list, you must be able to get the address of the next element in the list. This operation is called "walking" or "traversing" a PIDL.

The cb member of the SHITEMID structure that represents each item gives the size of that element in bytes. Since each element in the list is located immediately after the previous one, obtaining the address of the next item is simply a matter of adding cb to the current address.

The following example demonstrates how to walk a PIDL. Given the address of an element in an item identifier list, this function returns the address of the next element (or NULL if there are no more elements).

// GetNextItemID - points to the next element in an item
// identifier list.
// Returns a PIDL if successful, or NULL if at the end of the
// list.
// pidl - previous element

LPITEMIDLIST GetNextItemID(LPCITEMIDLIST pidl)
   {
   // Check for valid pidl.
   if(pidl == NULL)
      return NULL;

   // Get the size of the specified item identifier.
   int cb = pidl->mkid.cb;

   // If the size is zero, it is the end of the list.
   if (cb == 0)
      return NULL;

   // Add cb to pidl (casting to increment by bytes).
   pidl = (LPITEMIDLIST) (((LPBYTE) pidl) + cb);

   // Return NULL if it is null-terminating, or a pidl otherwise.
   return (pidl->mkid.cb == 0) ? NULL : (LPITEMIDLIST) pidl;
   }

Calculating the Size of an Identifier List

Knowing the amount of memory that a particular ID list uses is important for creating new instances of identifier lists. The following example calculates the size of an identifier list by walking the PIDL and keeping track of the size of each SHITEMID structure.

UINT GetSize(LPCITEMIDLIST pidl)
{
    UINT cbTotal = 0;
    if (pidl)
    {
        cbTotal += sizeof(pidl->mkid.cb);    // Null terminator
        while (pidl)
        {
            cbTotal += pidl->mkid.cb;
            pidl = GetNextItemID(pidl);
        }
    }
    return cbTotal;
}

Making a Copy of a PIDL

It can be useful to make a copy of an item ID list so that you can perform operations on the copy while leaving the original untouched. The following functions allocate space for the new PIDL and then copy the information into the new space. The first copies the entire list, and the second copies only the first item.

Note that this function and the ones that follow use the IMalloc::Alloc method to allocate the space. Before using IMalloc::Alloc, declare a pointer to IMalloc and get the Shell's IMalloc interface with the SHGetMalloc function, as follows:

SHGetMalloc(&g_pMalloc);

In larger applications, this pointer is commonly chosen to be a global variable.

LPITEMIDLIST MakeCopy(LPCITEMIDLIST pidl)
{
    UINT cb = 0;
    LPITEMIDLIST pidlTemp = (LPITEMIDLIST) pidl;

// Calculate size of list.
    cb = GetSize(pidl);

    LPITEMIDLIST pidlRet = (LPITEMIDLIST)g_pMalloc->Alloc(cb);
    if (pidlRet)
        CopyMemory(pidlRet, pidl, cb);
    return pidlRet;
}
LPITEMIDLIST MakeCopyOfFirstItem(LPCITEMIDLIST pidl)
{
    // Check for valid pidl.
    if(pidl == NULL)
        return NULL;

    // Calculate size and allocate space.
    UINT cb = pidl->mkid.cb + sizeof(pidl->mkid.cb);
    LPITEMIDLIST pidlRet = (LPITEMIDLIST)g_pMalloc->Alloc(cb);

    // Copy first item and append terminating zero.
    if (pidlRet)
    {
        CopyMemory(pidlRet, pidl, cb);
        GetNextItemID(pidlRet)->mkid.cb = 0;
    }
    return pidlRet;
}

Obtaining the Parent of a PIDL

Sometimes it can be useful to get the PIDL that refers to the parent element of another PIDL. For example, if a particular PIDL has an equivalent display name of:

C:\Program Files\myprog.exe

The parent would have a display name of:

C:\Program Files

The following function takes a PIDL and changes it to its parent by removing the last item in the list.

BOOL GetParentID(LPITEMIDLIST pidl)
{
    BOOL fRemoved = FALSE;

// Make sure it's a valid PIDL.
    if (pidl == NULL)
        return(FALSE);

    if (pidl->mkid.cb)
    {
        LPITEMIDLIST pidlNext = pidl;
        while (pidlNext)
        {
           pidl = pidlNext;
           pidlNext = GetNextItemID(pidl);
        }
// Remove the last one, insert null-terminator.
        pidl->mkid.cb = 0;
        fRemoved = TRUE;
    }

    return fRemoved;
}

Relative and Full PIDLs

A PIDL uniquely describes the location of an object relative to some root object. If the PIDL describes the object relative to the desktop folder (and hence uniquely describes the object within the entire Shell namespace), the PIDL is known as a fully qualified PIDL or a full PIDL. Otherwise it is known as a relative PIDL or a partial PIDL.

When a function or method requests a pointer to an IShellFolder interface in addition to a PIDL, the PIDL will be expected to be relative to the particular folder given by the IShellFolder interface that you pass. Often, this folder must be the immediate parent folder of the object described by the PIDL (and thus the PIDL will contain only one SHITEMID structure).

IShellFolder methods that take a PIDL as a parameter also expect the PIDL to be relative to the interface's folder.

If the function or method does not request a pointer to an IShellFolder interface, you must use a full PIDL. For example, the SHBindToParent function requires a full PIDL for its input.

To create a full PIDL from a relative PIDL, you must have the fully qualified PIDL of the object that is the root of the relative PIDL. Then you would append the relative PIDL to the end of the PIDL of the root object.

For example, if your relative PIDL has the display name:

myprog.exe
And the object that it is relative to has a display name of:
C:\Program Files
Then the fully qualified PIDL would have a display name of:
C:\Program Files\myprog.exe
LPITEMIDLIST Append(LPCITEMIDLIST pidlBase, LPCITEMIDLIST pidlAdd)
{
    if(pidlBase == NULL)
        return NULL;
    if(pidlAdd == NULL)
        return pidlBase;

    LPITEMIDLIST pidlNew;

    UINT cb1 = GetSize(pidlBase) - sizeof(pidlBase->mkid.cb);
    UINT cb2 = GetSize(pidlAdd);

    pidlNew = (LPITEMIDLIST)g_pMalloc->Alloc(cb1 + cb2);
    if (pidlNew)
    {
        CopyMemory(pidlNew, pidlBase, cb1);
        CopyMemory(((LPSTR)pidlNew) + cb1, pidlAdd, cb2);
    }
    return pidlNew;
}

Deleting a PIDL

It is important to free the memory that was allocated for a PIDL when it is no longer needed. Often, a function will allocate the memory and expect the calling application to free the memory when it has finished using the PIDL.

To free the memory allocated for a PIDL, get the address of the Shell's IMalloc interface using SHGetMalloc. Then use the IMalloc::Free method to release the allocated memory.

Simple ID Lists

There is a special kind of item ID list called a simple ID list (or simple PIDL). A simple PIDL is created when WIN32_FIND_DATA information is stored in a bind context that is passed to IShellFolder::ParseDisplayName.

The advantage of parsing the display name into a simple PIDL is that it gives you the flexibility to create a PIDL that refers to a file that doesn't exist yet.

You must take care when using simple PIDLs, however, because much of the path information is omitted in the creation of a simple PIDL. For example, if a simple PIDL refers to the computer's E: drive, it is impossible to discern whether the drive is a hard disk drive, a CD-ROM drive, or a mapped network drive.

Note It is recommended that you not employ the use of simple ID lists unless you are certain that their use will not disrupt the functionality of your programs.

To create a simple PIDL, you must:

  1. Create an instance of the object that exposes the IFileSystemBindData interface.
  2. Store the file's WIN32_FIND_DATA data in the object using IFileSystemBindData::SetFindData.
  3. Create a bind context and store the object in the bind context by using the IBindCtx::RegisterObjectParam method. Set the pszKey parameter to the string L"File System Bind Data" and the punk parameter to the address of the IFileSystemBindData interface.
  4. Parse the display name with IShellFolder::ParseDisplayName. Pass the bind context that contains the WIN32_FIND_DATA data through the pbc parameter.

The following example details the steps to create a simple PIDL. To begin with, here is a sample implementation of IFileSystemBindData. Note that implementations of the IUnknown methods have been omitted.

class MyFileSysBindData: public IFileSystemBindData
{
public:
    MyFileSysBindData();

    // *** IUnknown methods ***
    STDMETHODIMP QueryInterface(REFIID riid, void **ppvObj);
    STDMETHODIMP_(ULONG) AddRef(void);
    STDMETHODIMP_(ULONG) Release(void);

    // *** IFileSystemBindData Methods ***
    STDMETHODIMP SetFindData(const WIN32_FIND_DATAW *pfd);
    STDMETHODIMP GetFindData(WIN32_FIND_DATAW *pfd);

private:
    ~CFileSysBindData();

    LONG _cRef;
    WIN32_FIND_DATAW _fd;
};

MyFileSysBindData::MyFileSysBindData()
{
    // Zero-initialize in case client never calls SetFindData.
    ZeroMemory(&_fd, sizeof(_fd));
}

HRESULT MyFileSysBindData::SetFindData(const WIN32_FIND_DATAW *pfd)
{
    _fd = *pfd;
    return S_OK;
}

HRESULT MyFileSysBindData::GetFindData(WIN32_FIND_DATAW *pfd)
{
    *pfd = _fd;
    return S_OK;
}

IUnknown* CreateFSBD(VOID)
{
    IUnknown *pI = static_cast<IFileSystemBindData*>
        (new MyFileSysBindData);

    pI->AddRef();
    return pI;
}

The following is an example of how to generate a simple PIDL from a display name and WIN32_FIND_DATA information.

HRESULT GetSimpleIDFromPath(LPWSTR pwszPath, WIN32_FIND_DATAW *pfd,
    LPITEMIDLIST *ppidl)
{

    HRESULT hr;

    // Create the object.
    IUnknown *pI;
    IFileSystemBindData *pfsbd;
    pI = CreateFSBD();
    hr = pI->QueryInterface(IID_IFileSystemBindData,
        (void**)&pfsbd);

    // Store the data and register to the bind context.
    if (SUCCEEDED(hr))
    {
        if (pfd)
        {
            pfsbd->SetFindData(pfd);
        }

        IBindCtx *pbc;
        hr = CreateBindCtx(0, &pbc);
        if (SUCCEEDED(hr))
        {
              hr = (pbc)->
                  RegisterObjectParam(L"File System Bind Data",
                  pfsbd);
        }
        else {
            pfsbd->Release();
            return hr;
        }
        pfsbd->Release();

   // Get the desktop folder and parse the display name.
        IShellFolder *pFolder;
        hr = SHGetDesktopFolder(&pFolder);
        if (SUCCEEDED(hr))
        {
            hr = pFolder->ParseDisplayName(NULL, pbc,
                (LPOLESTR)pwszPath, NULL, ppidl, NULL);
        }

        pFolder->Release();
        pbc->Release();
    }

    return hr;
}


Handling Online Help

Online Help can come in a variety of forms, from detailed conceptual information to quick definitions. This topic contains the following sections.

  • About Help
  • Using Help

About Help

An important element of a user-friendly application is readily available in online Help. Microsoft® Windows® provides functions and messages that, when used in conjunction with the Windows Help application, make it easy to implement online Help in your application. This overview discusses the elements of the Microsoft® Win32® application programming interface (API) that support online Help. It describes how to use these elements to give users a means to request Help, and it explains how to use the Windows Help application to display Help.

Help Requests

Most Windows-based applications provide online Help information in a variety of forms, ranging from conceptual Help that explains the purpose of an application's features to pop-up Help that provides quick definitions of individual elements in the application's user interface. You use Win32 functions and messages to give users a variety of ways to request access to this information. The following sections describe these Help requests.

Help menu

Most applications provide user access to Help information by including a Help menu in the main window. When the user selects an item from a Help menu, the corresponding window procedure receives a WM_COMMAND message that identifies the selected item. The application responds by displaying the appropriate Help information, such as a list of Help topics, an index, or an introduction to the application.

Help from the keyboard

Windows provides user access to Help information from the keyboard by notifying the application whenever the user presses the F1 key. The system sends a WM_HELP message to the window that had the keyboard focus when the user pressed the F1 key. If the window is a child window (for example, a control in a dialog box), the DefWindowProc function passes the message to the parent window. If a menu is active when F1 is pressed, the system sends the message to the window associated with the menu. The application responds by displaying Help information associated with the window, control, or menu that has the focus or is active. For example, if the user selects a control in a dialog box and presses F1, the application displays Help information for that control.

The lParam parameter of WM_HELP is a pointer to a HELPINFO structure that contains detailed information about the item for which Help is requested. You use this information to determine the Help topic to display. The HELPINFO structure also includes the coordinates of the mouse cursor at the time the user pressed the F1 key. You can use this information to provide Help based on the location of the mouse cursor.

Help from the mouse

Windows provides the user access to Help information from the mouse by notifying the application whenever the user clicks the right mouse button or clicks a window, control, or menu after clicking the Question (?) button. The application responds by displaying Help information associated with the given window, control, or menu.

The system sends a WM_CONTEXTMENU message when the user clicks the right mouse button. The window that was clicked receives the message. If the window is a child window, such as a control, the DefWindowProc function passes the message to the parent window. The WM_CONTEXTMENU message specifies the coordinates of the mouse cursor. The x-coordinate is in the low-order word of the lParam parameter, and the y-coordinate is in the high-order word. If the user clicked a control, the wParam parameter is the handle to the control that received the click.

The system sends a WM_HELP message when the user clicks an item in a window after clicking the Question (?) button that appears in the title bar of the window. You can add a Question button to a title bar by specifying the WS_EX_CONTEXTHELP style in the CreateWindowEx function when creating the window. The lParam parameter of WM_HELP is a pointer to a HELPINFO structure that contains detailed information about the item for which Help is requested, including the coordinates of the mouse cursor at the time the user clicked the mouse button.

The Question button is recommended for use in dialog boxes only. In the past, applications have provided user access to Help information about a dialog box by providing a Help button in the dialog box. This method is no longer recommended. Use the Question button instead.

Help Display and Windows Help

Once an application receives a request for Help, it should display the appropriate Help information. Because the Windows Help application supplies a consistent user interface, it is recommended that applications use Windows Help rather than other methods. To direct Windows Help to display Help information, an application uses the WinHelp function, specifying details such as the information to display and the form of the window in which to display it. The following sections explain how to use WinHelp to display Help information.

Help files

To view Help information, you must specify a Help file when calling the WinHelp function. The Help file must have the Windows Help (.hlp) file format and one or more topics. Each topic is a distinct unit of information, such as a conceptual description, a set of instructions, a picture, a glossary definition, and so on. Topics must be uniquely identified so that Windows Help can locate them whenever they are requested. Internally, Windows Help uses topic identifiers to locate topics, but applications most often use context identifiers (unique integer values) to specify the topics to display. The Help file author must explicitly map context identifiers to topic identifiers in the [MAP] section of the project file used to build the Help file.

When you specify a Help file but you do not specify a path, WinHelp looks for the Help file in the Help directory or in a directory specified by the PATH environment variable. In addition, WinHelp can find a Help file whose name is listed in the following registry location:

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help

To take advantage of the registry, you must create a value name that has the same name as your Help file. The value assigned to that name must be the directory where the Help file resides.

If WinHelp cannot find the given Help file, it displays a dialog box that allows the user to specify the location of the Help file. Because WinHelp saves the location information in the registry, it does not ask again for the location of the same Help file.

For more information about how to author and build a Help file, see the documentation provided with your development tools.

Starting Windows Help

The following example uses the WinHelp function to start the Windows Help application and open the Microsoft® Windows NT® Help file to its Contents topic.

HWND hwnd;     // main window handle
BOOL bResult   // for checking Boolean function result

bResult = WinHelp(hWnd, "WINNT.HLP", HELP_CONTENTS, 0L);

This next example opens the Windows NT user Help file, searches the file for the topic associated with a keyword string, and then displays the topic.

HWND hwnd;     // main window handle
BOOL bResult   // for checking Boolean function result

bResult = WinHelp(hWnd, "WINNT.HLP", HELP_KEY,
                  (DWORD) "finding topics");

Help Topics dialog box

You can display the Help Topics dialog box by calling the WinHelp function with the HELP_FINDER command. The Help Topics dialog box lets the user select topics to display by viewing the titles of the topics, the keywords associated with the topics, or the words and phrases found in the topics. Applications typically display this dialog box when the user chooses a command, such as Help Topics, from the Help menu. An application may also display this dialog box if the user presses the F1 key when no specific window, control, or menu in the application has the focus or is active.

In the past, applications have used the HELP_CONTENTS and HELP_INDEX commands with the WinHelp function to display the Contents topic and the keyword index of the Help file. These commands are no longer recommended. Use the HELP_FINDER command instead.

Information topics

You can display a specific topic by calling the WinHelp function with the HELP_CONTEXT command and specifying the context identifier for the topic. Applications typically use the HELP_CONTEXT command in response to user requests for topics containing conceptual information or procedural Help rather than information about a specific control or menu. In such cases, the user may continue to browse the Help file looking for related information before returning to the application.

The HELP_CONTEXT command invokes a regular instance of Windows Help, enabling the user to find other topics in the Help file. It typically displays the main Help window, which includes a title bar, a system menu, minimize and maximize buttons, a main menu, an optional navigation bar, a sizing border, and a client area. The text of the selected topic appears in the client area, and the user can navigate through the Help file by using hot links or navigation buttons in the main window. The regular instance of Windows Help can also be used to display Help in one or more secondary windows instead of the main window.

Pop-up topics

You can display a pop-up topic that contains information for a specific control or menu by calling the WinHelp function with the HELP_WM_HELP or HELP_CONTEXTMENU command. These commands display a topic in a pop-up window near the corresponding control or menu. To let the user return immediately to work in the application, the pop-up window is destroyed as soon as the user presses a key or clicks the left mouse button.

You use the HELP_WM_HELP command when processing WM_HELP messages for control windows. Because most controls pass the WM_HELP message to the DefWindowProc function, the corresponding dialog box procedure (or parent window procedure) processes this message. Rather than give a specific context identifier, the dialog box procedure must pass an array of control and context identifier pairs to WinHelp along with the control handle specified in the hItemHandle member of the HELPINFO structure passed with the WM_HELP message. The function determines the identifier of the control for which the WM_HELP message was generated and uses the matching context identifier to display the appropriate topic.

You use the HELP_CONTEXTMENU command when processing WM_CONTEXTMENU messages. Because most controls pass the WM_CONTEXTMENU message to the DefWindowProc function, the corresponding dialog box procedure (or parent window procedure) processes this message. The procedure specifies an array of control and context identifier pairs; it also specifies the handle in the wParam parameter when calling WinHelp so that the function can pick the appropriate context identifier from the array and display the appropriate topic. Unlike the HELP_WM_HELP command, HELP_CONTEXTMENU first displays a What's This? command in a menu. If the user chooses the command, WinHelp displays the topic. Otherwise, the request is canceled.

You can also display pop-up topics by using the HELP_CONTEXTPOPUP command and specifying a context identifier of the topic. This command is similar to the HELP_CONTEXT command but invokes the pop-up instance of Windows Help used by HELP_WM_HELP and HELP_CONTEXTMENU. Applications can use this command in response to WM_HELP messages to display Help for menus and for windows that are not controls in a dialog box. To use this command most effectively, the application should assign context identifiers to these menus and windows.

You can assign a context identifier to any window or menu in the application. When a WM_HELP message is generated, the system includes the context identifier in the HELPINFO structure that is passed to the parent window in the WM_HELP message. The parent window can then pass the context identifier to WinHelp to display the requested Help topic.

You use the SetWindowContextHelpId function to assign a context identifier to a window or control and the SetMenuContextHelpId function to assign a context identifier to a menu. You can retrieve the context identifier for a window or menu by using the GetWindowContextHelpId or GetMenuContextHelpId function.

Keyword searches

You can enable the user to find and view topics by assigning keywords to topics in the Help file. A keyword is simply a string that is associated with one or more topics. Windows Help collects all keywords in a Help file, places them in a table, and displays them in the Index list of the Help Topics dialog box. When the user selects a keyword, Windows Help displays the associated Help topic or, if there is more than one topic associated with the keyword, displays a list of topics from which the user can choose.

In an application, you can use the HELP_KEY, HELP_PARTIALKEY, or HELP_MULTIKEY command with the WinHelp function to search for and display Help topics based on whole or partial keywords. You specify the command, the keyword string, the Help file, and the handle to the owner window. In all cases, if a single match is found, WinHelp displays the corresponding topic. If more than one match is found, the function displays the Topics Found dialog box, and the user can choose which topic to view. If no match is found, WinHelp either displays the Index list (for HELP_KEY and HELP_PARTIALKEY) or displays an error message (for HELP_MULTIKEY).

Your application can search for multiple keywords in a single call to WinHelp by separating the keywords with semicolons. (Searching for multiple keywords is not supported for Help files created for Windows version 3.x.) It can also search for keywords across multiple Help files if the Help file that is specified has a contents (.cnt) file that contains :Index or :Link commands. With the HELP_KEY command, WinHelp searches for keywords in all files specified by these commands. With the HELP_MULTIKEY and HELP_PARTIALKEY commands, the function searches all files except those specified by :Link commands.

By default, Windows Help recognizes only the keyword table identified by the K footnote character in the Help source file. You can direct Windows Help to create additional keyword tables by adding a footnote character other than K, with the keyword definition, in the Help source file. (The footnote character A, however, is reserved.) You must define any additional keyword tables by using MULTIKEY statements in the [OPTIONS] section of the project file when building the Help file.

An application can use the HELP_SETINDEX command with the WinHelp function to direct Windows Help to display a keyword table other than K in its Index list. To direct Windows Help to search for a keyword in an alternate keyword table, an application can use the HELP_MULTIKEY command. You specify the keyword and keyword table in a MULTIKEYHELP structure, which you pass to WinHelp.

When WinHelp displays a topic, it displays it in the window specified by the ">" footnote for the topic, in the window specified by the :Base command in the contents file, or in the main window. If the main window is already open to a different Help file when you call WinHelp, the function hides the main window while searching. In this case, canceling both the Topics Found and Help Topics dialog boxes closes the main window.

Secondary Help windows

The main window of the Windows Help application is called the primary window. Windows Help can also display Help topics in a secondary window. Unlike the primary Help window, a secondary window does not contain a menu bar. You can include a navigation bar in a secondary window, and you can add buttons to the bar. You can also choose to have Windows Help automatically adjust the height of the secondary window to accommodate the topic.

You must define secondary windows in the [WINDOWS] section of your Help project file, providing the name and, optionally, initial size and position of each window. You can direct the Windows Help application to display a topic in a secondary window by appending an angle bracket (>) and the name you have defined for the secondary window to the name of the Help file. The resulting string is then passed to the WinHelp function.

An application can change the size and position of a primary or secondary window by specifying the address of a HELPWININFO structure and the HELP_SETWINPOS command in a call to WinHelp. HELPWININFO specifies the name of the window and its new size and position.

Training card Help

Using training card Help, an application can display a sequence of instructions to guide the user through the steps of a task. A training card typically consists of text that explains a particular step and buttons that are associated with TCard macros, which allow the user to tell the application what to do next. Training cards can only be displayed in secondary windows and must not contain hot links to other topics in the Help file.

An application initiates the training card instance of Windows Help by calling the WinHelp function and specifying the HELP_TCARD command in combination with another command, such as HELP_CONTEXT. Subsequently, when the user clicks a button in the training card, clicks a hot spot assigned to the TCard macro, or closes the training card, Windows Help notifies the application by sending it a WM_TCARD message. The wParam parameter identifies the button or user action, and the lParam parameter contains additional data, the meaning of which depends on the value of wParam.

Canceling Help

Windows Help requires an application to explicitly cancel Help so that it can free any resources used to keep track of the application and its Help files. The application can do this at any time by calling the WinHelp function and specifying the HELP_QUIT command. Note that this is not true for the pop-up instance of Windows Help. An application should not try to close a pop-up instance.

If an application has made any calls to WinHelp, it must cancel Help before it closes its main window (for example, in response to the WM_DESTROY message in the main window procedure). An application needs to call WinHelp only once to cancel Help, no matter how many Help files it has opened. Windows Help remains running until all applications or dynamic-link libraries (DLLs) have canceled Help.

To close the training card instance of Windows Help, you must specify both the HELP_TCARD and HELP_QUIT commands when calling WinHelp. An application does not need to cancel the training card instance of Windows Help if the user cancels it first. Windows Help notifies an application when the user cancels the training card instance by sending the WM_TCARD message with the wParam parameter set to IDCLOSE.

Using Help

This section shows how to provide context-sensitive Help for a dialog box and how to set the appearance of a secondary Help window.

  • Providing Help in a Dialog Box
  • Setting the Appearance of a Secondary Help Window

Providing Help in a Dialog Box

To provide context-sensitive Help in a dialog box, you must create an array consisting of pairs of DWORD values. The first value in each pair is the identifier of a control in the dialog box, and the second is the context identifier of the Help topic for the control. The array should contain one pair of identifiers for each control in the dialog box.

The dialog box procedure must process the WM_HELP and WM_CONTEXTMENU messages. The dialog box procedure receives WM_HELP when the user presses the F1 key and WM_CONTEXTMENU when the user clicks the right mouse button.

The lParam parameter of WM_HELP contains the address of a HELPINFO structure. The hItemHandle member of this structure identifies the control for which the user has requested Help. You must pass this handle to the WinHelp function along with the HELP_WM_HELP command, the name of your Help file, and a pointer to the array of identifiers. The WinHelp function searches the array for the control identifier of the specified control and then retrieves the corresponding Help context identifier. Next, the function passes the Help context identifier to Windows Help, which finds the corresponding topic and displays it in a pop-up window. If the control has an identifier of -1, the system searches for the next control that is a tab stop and then uses its identifier to find the Help context identifier. For this reason, it is important that you place static text before controls in a resource file.

When calling the WinHelp function, processing WM_CONTEXTMENU is similar to processing WM_HELP with these two exceptions:

  • You pass the wParam parameter from WM_CONTEXTMENU, which is the handle to the control that sent the message.
  • You specify the HELP_CONTEXTMENU command instead of HELP_WM_HELP.

The HELP_CONTEXTMENU command causes Windows Help to display a menu before it displays the Help topic. The menu is system-defined. It allows the user to display Help for the control or to display the Help Topics dialog box.

The following example shows how to implement context-sensitive Help in a dialog box.

LRESULT CALLBACK EditDlgProc(HWND hwndDlg, UINT uMsg, WPARAM wParam,
    LPARAM lParam)
{

// Create an array of control identifiers and context identifiers.

static DWORD aIds[ ] = {
    ID_SAVE,   IDH_SAVE,
    ID_DELETE, IDH_DELETE,
    ID_COPY,   IDH_COPY,
    ID_PASTE,  IDH_PASTE,
    0,0
};

switch (uMsg) {
    case WM_HELP:
        WinHelp(((LPHELPINFO) lParam)->hItemHandle, "helpfile.hlp",
            HELP_WM_HELP, (DWORD) (LPSTR) aIds);
        break;

    case WM_CONTEXTMENU:
        WinHelp((HWND) wParam, "helpfile.hlp", HELP_CONTEXTMENU,
            (DWORD) (LPVOID) aIds);
        break;
    .
    . // Process other messages here.
    .
    }

return FALSE;

}

Setting the Appearance of a Secondary Help Window

An application can set the size, position, and show state of a secondary Help window by passing the HELP_SETWINPOS command and the address of a HELPWININFO structure to the WinHelp function. The members of HELPWININFO specify the name of the window to change and the window's new size, position, and show state.

The following example sets the appearance of a secondary window named "wnd_menu". The name must be defined in the [WINDOWS] section of the Help project file.

BOOL DoWindowSize(VOID)
{
    HANDLE hhwi;
    LPHELPWININFO lphwi;
    WORD wSize;
    char *szWndName = "wnd_menu";

    wSize = sizeof(HELPWININFO) + lstrlen(szWndName);
    hhwi = GlobalAlloc(GHND, wSize);
    lphwi = (LPHELPWININFO) GlobalLock(hhwi);

    lphwi->wStructSize = wSize;
    lphwi->x    = 256;      // horizontal position
    lphwi->y    = 256;      // vertical position
    lphwi->dx   = 767;      // width
    lphwi->dy   = 512;      // height
    lphwi->wMax = SW_SHOW;  // show the window
    lstrcpy(lphwi->rgchMember, szWndName);  // secondary window

    WinHelp(hwnd, "myhelp.hlp", HELP_SETWINPOS, (DWORD) lphwi);
    GlobalUnlock(hhwi);
    GlobalFree(hhwi);

return;
}


Creating and Installing Theme Files

This is preliminary documentation and is subject to change.

This document discusses the format of .theme files used in the Microsoft product code-named Whistler. Microsoft® Plus! for Microsoft® Windows® 95 introduced .theme files. A .theme file is a .ini text file that is divided into sections, which specify visual elements that appear on a Windows desktop. Section names are wrapped in brackets ([]) in the .ini file.

The following topics are discussed in this article.

  • Creating a Theme File
  • Example of a Theme File
  • Installing Theme Files

Creating a Theme File

A .theme file enables you to change the appearance of certain desktop elements. The following steps describe the easiest way to create a .theme file.

  1. In Control Panel, click the Display icon. Make changes to the settings you want, such as background, screen saver, and icons.
  2. Click Apply.
  3. Select the Themes tab and click Save As....
  4. To make your theme available to users of your application, you must supply your .theme file, as well as the background picture, screen saver, and icons files.

You can also modify your .theme file manually for a greater level of control over the details of your theme. The following topics describe the sections of .theme files and provide examples of how to specify changes for the different elements.

Desktop Features Icons

The desktop, which is the screen you see when you log on to Windows, is the home of icons for such features as My Computer, My Documents, and Recycle Bin. The first section of a .theme file specifies the icons to use for these desktop features. Following are two examples of how a .theme file sets the My Computer icon.

[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%ThemeDir%Inside your Computer My Computer.ico

; My Computer
[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%WinDir%explorer.exe,0
screen saver

Colors

If .theme files are installed on a computer, the user can open Control Panel, click the Appearance and Themes icon and select a theme. When the user selects a theme, the theme can change certain aspects of the desktop appearance. One aspect that can be changed is the color of elements such as scrollbars, text, and buttons. The .theme file specifies the RGB values for the elements to change. Following is an example of how colors are set.

[Control Panel\Colors]
ActiveTitle=10 36 106
Background=166 202 240
Hilight=10 36 106
HilightText=255 255 255
TitleText=255 255 255
Window=255 255 255
WindowText=0 0 0
Scrollbar=212 208 200
InactiveTitle=128 128 128
Menu=212 208 200
WindowFrame=0 0 0
MenuText=0 0 0
ActiveBorder=212 208 200
InactiveBorder=212 208 200
AppWorkspace=128 128 128
ButtonFace=212 208 200
ButtonShadow=128 128 128
GrayText=128 128 128
ButtonText=0 0 0
InactiveTitleText=212 208 200
ButtonHilight=255 255 255
ButtonDkShadow=64 64 64
ButtonLight=212 208 200
InfoText=0 0 0
InfoWindow=255 255 225
GradientActiveTitle=166 202 240
GradientInactiveTitle=192 192 192

Cursors

A theme can also change the appearance of cursors. To do so, you create .cur files to replace the default Windows cursors. The following example is from a .theme file that defines the cursors for a theme called Inside Your Computer.

[Control Panel\Cursors]
Arrow=%ThemeDir%Inside Your Computer arrow.cur
Help=%ThemeDir%Inside Your Computer help.cur
AppStarting=%ThemeDir%Inside Your Computer wait.ani
Wait=%ThemeDir%Inside Your Computer busy.ani
NWPen=%ThemeDir%Inside Your Computer pen.cur
No=%ThemeDir%Inside Your Computer no.cur
SizeNS=%ThemeDir%Inside Your Computer size NS.cur
SizeWE=%ThemeDir%Inside Your Computer size WE.cur
Crosshair=%ThemeDir%Inside Your Computer cross.cur
IBeam=%ThemeDir%Inside Your Computer beam.cur
SizeNWSE=%ThemeDir%Inside Your Computer size NWSE.cur
SizeNESW=%ThemeDir%Inside Your Computer size NESW.cur
SizeAll=%ThemeDir%Inside Your Computer move.cur
UpArrow=%ThemeDir%Inside Your Computer up.cur
DefaultValue=Windows default

Desktop Appearance

You can create custom wallpaper for the desktop and specify a path to the graphics file in a .theme file. Additionally, this section of the .theme file can specify whether the screen saver is active. The following example shows how to do modify the desktop appearance.

[Control Panel\Desktop]
Wallpaper=%WinDir%web\wallpaper\Professional.jpg
;The path to the wallpaper picture can point to a
;.bmp, .gif, .jpg, .png, or .htm file.

TileWallpaper=0
;A value of 0 means that the wallpaper picture should
;not be tiled and 1 means that it should.

WallpaperStyle=2
;A value of 2 means that the wallpaper picture should be
;stretched and 0 means that it should be centered.

Pattern=(None)
ScreenSaveActive=1
Note The elements, tilewallpaper and center, are not available with wallpaper that uses a .htm file.

System Metrics

You can specify system metrics in a .theme file. System metrics are the dimensions of various display elements, such as the window border width, icon height, or scrollbar width. Following is an example of how to change system metrics.

[Control Panel\Desktop\WindowMetrics]

[Metrics]
IconMetrics=76 0 0 0 139 0 0 0 139 0 0 0 1 0 0 0 245
255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0 0 0 0
0 0 0 0 84 97 104 111 109 97 0 119 0 0 7 0 0 0 0 0 216
31 7 0 28 52 1 1 216 31 7 0 176 36 1 1
NonclientMetrics=84 1 0 0 1 0 0 0 16 0 0 0 16 0 0 0 18
0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
188 2 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 12 0 0 0
15 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 188 2
0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 80 37 11
0 0 0 0 0 140 221 6 0 227 115 247 119 2 40 11 0 7 0 0
0 18 0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0
0 0 0 144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0
0 0 0 0 0 60 222 6 0 50 71 252 119 120 1 7 0 76 73 252
119 8 6 7 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 119 0
0 7 0 120 1 7 0 120 1 7 0 40 37 11 0 120 1 7 0 120 1 7
0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0
0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 92 1 0 0 136 4
0 0 40 37 1 1 0 0 7 0 184 221 6 0 46 75 232 119

Visual Styles

You can supply specific information concerning the size and color of desktop elements in .mstheme files. The color and size sections of .theme files can be replaced by .mstheme files which enable you to modify desktop elements in more detail. These files are specified in the visual styles section of a .theme file. Following is an example of a visual styles section.

[VisualStyles]
Path=%ResourceDir%\Themes\Professional\Professional.mstheme
ColorStyle=Default
Size=Normal

Adding a Path element to a .mstheme file is optional. If you supply a path, you should remove the metrics and color sections from the .theme file. When these sections are removed, the colors, fonts, and sizes for a theme come from the .mstheme file and match the .mstheme author's intent. Failing to remove the metric and color sections can cause Windows or applications to have drawing problems.

Application Events

The user can select the Sounds, Speech, and Audio Devices icon in Control Panel to associate sounds with events that occur in applications. For example, a .wav file can play when an application is opened. A .theme file can specify .wav files to replace the default ones. The following example shows how to do this.

[AppEvents\Schemes\Apps\.Default\SystemExclamation\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemExit\.Current]
DefaultValue=%WinDir%media\tada.wav

[AppEvents\Schemes\Apps\.Default\SystemHand\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemQuestion\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemStart\.Current]
DefaultValue=%WinDir%media\The Microsoft Sound.wav

[AppEvents\Schemes\Apps\Explorer\EmptyRecycleBin\.Current]
DefaultValue=%WinDir%media\ding.wav

Boot

In the .theme file, you can specify the screen saver for Windows to use. The following example shows this.

[boot]
SCRNSAVE.EXE=%WinDir%\System32\ssflwbox.scr

Master Theme Selector

The master theme selector section of the .theme file should always be included as a tag that indicates the file is valid. You do not have a choice of values for this parameter. The following shows this.

[MasterThemeSelector]
MTSM=DABJDKT
ThemeColorBPP=4

Example of a Theme File

The following example shows a complete .theme file.

[Theme]
DisplayName=@themeui.dll,-2016

; My Computer
[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%WinDir%explorer.exe,0

; My Documents
[CLSID\{450D8FBA-AD25-11D0-98A8-0800361B1103}\DefaultIcon]
DefaultValue=%WinDir%SYSTEM32\mydocs.dll,0

; My Network Places
[CLSID\{208D2C60-3AEA-1069-A2D7-08002B30309D}\DefaultIcon]
DefaultValue=%WinDir%SYSTEM32\shell32.dll,17

; Recycle Bin
[CLSID\{645FF040-5081-101B-9F08-00AA002F954E}\DefaultIcon]
full=%WinDir%SYSTEM32\shell32.dll,32
empty=%WinDir%SYSTEM32\shell32.dll,31

[Control Panel\Colors]
ActiveTitle=10 36 106
Background=58 110 165
Hilight=10 36 106
HilightText=255 255 255
TitleText=255 255 255
Window=255 255 255
WindowText=0 0 0
Scrollbar=212 208 200
InactiveTitle=128 128 128
Menu=212 208 200
WindowFrame=0 0 0
MenuText=0 0 0
ActiveBorder=212 208 200
InactiveBorder=212 208 200
AppWorkspace=128 128 128
ButtonFace=212 208 200
ButtonShadow=128 128 128
GrayText=128 128 128
ButtonText=0 0 0
InactiveTitleText=212 208 200
ButtonHilight=255 255 255
ButtonDkShadow=64 64 64
ButtonLight=212 208 200
InfoText=0 0 0
InfoWindow=255 255 225
GradientActiveTitle=166 202 240
GradientInactiveTitle=192 192 192

[Control Panel\Cursors]
Arrow=
Help=
AppStarting=
Wait=
NWPen=
No=
SizeNS=
SizeWE=
Crosshair=
IBeam=
SizeNWSE=
SizeNESW=
SizeAll=
UpArrow=
DefaultValue=Windows default

[Control Panel\Desktop]
Wallpaper=(None)
TileWallpaper=0
WallpaperStyle=2
Pattern=(None)
ScreenSaveActive=0

[AppEvents\Schemes\Apps\.Default\.Default\.Current]
DefaultValue=%WinDir%media\ding.wav

[AppEvents\Schemes\Apps\.Default\AppGPFault\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Maximize\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\MenuCommand\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\MenuPopup\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Minimize\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Open\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\RestoreDown\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\RestoreUp\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\RingIn\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Ringout\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\SystemAsterisk\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemDefault\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\SystemExclamation\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemExit\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\SystemHand\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemQuestion\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemStart\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\Explorer\EmptyRecycleBin\.Current]
DefaultValue=%WinDir%media\ding.wav

[AppEvents\Schemes\Apps\.Default\Close\.Current]
DefaultValue=

[Control Panel\Desktop\WindowMetrics]

[Metrics]
IconMetrics=76 0 0 0 139 0 0 0 139 0 0 0 1 0 0 0 245
255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0 0 0 0
0 0 0 0 84 97 104 111 109 97 0 119 0 0 7 0 0 0 0 0 216
31 7 0 28 52 1 1 216 31 7 0 176 36 1 1
NonclientMetrics=84 1 0 0 1 0 0 0 16 0 0 0 16 0 0 0 18
0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
188 2 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 12 0 0 0
15 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 188 2
0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 80 37 11
0 0 0 0 0 140 221 6 0 227 115 247 119 2 40 11 0 7 0 0
0 18 0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0
0 0 0 144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0
0 0 0 0 0 60 222 6 0 50 71 252 119 120 1 7 0 76 73 252
119 8 6 7 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 119 0
0 7 0 120 1 7 0 120 1 7 0 40 37 11 0 120 1 7 0 120 1 7
0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0
0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 92 1 0 0 136 4
0 0 40 37 1 1 0 0 7 0 184 221 6 0 46 75 232 119

[boot]
SCRNSAVE.EXE=%WinDir%\System32\logon.scr

[MasterThemeSelector]
MTSM=DABJDKT
ThemeColorBPP=4

Installing Theme Files

When Whistler is initialized, it enumerates the following directories and subdirectories.

  • The ProgramFiles directory
  • First level subdirectories of %windir%\Resources\<LangID>\ using SHGetFolderPath (NULL, CSIDL_RESOURCES_LOCALIZED, NULL, O, szPath);
  • %AppData%\Microsoft\Windows\Themes
  • Any directories specified under the registry key \Software\Microsoft\Windows\CurrentVersion!\Themes\InstalledThemes

The registry key values are ignored and the REG_SZ data contains the path. Whistler looks for .theme files in the InstalledThemes directory or its first level subdirectories.

A .theme file can specify a DisplayName value under the Themes section. If a DisplayName exists, it is used instead of the file name.

The %ThemeDir% token has been updated to make it easier for you to make a subdirectory for each theme; %ThemeDir% points to the legacy directory. If a theme file is not found in %ThemeDir%, the operating system attempts to load the file from the location of the .theme file.

Use the following steps to create an installer.

  1. Create a theme directory, such as %ProgramFiles%\Themes\.
  2. Register the path to the theme directory in the InstalledThemes registry key.
  3. Install each theme in its own subdirectory, for example: %ProgramFiles%\Themes\Holiday.theme, Holiday.jpg.

A .theme file has file associations; therefore theme installer applications can call ShellExecute on a .theme file to open the Display window in Control Panel to the specified theme. If the Display window in Control Panel is already open, the Themes tab will not be selected or its selection changed.


BandObjs Sample

Band Object Implementation Sample "BandObjs"

BandObjs is a simple example that demonstrates the implementation of the three types of band objects. These are Desk Bands, Explorer Bars and Communication Bands. See the Band Objects topic under Internet Tools and Technologies - Windows Shell in the Internet Client SDK documentation for more information on band objects.

Once the sample is built, it can register itself. If you use Visual C++ 5.0 to build this project, it will automatically register the server when the server is built. The included make file will also attempt to register the server. If you need to register the server manually, just execute the following from the command line, substituting the path where the DLL is located for "<path>":

regsvr32.exe /s /c <path>\BandObjs.dll


BandObjs.cpp

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          BandObjs.cpp

   Description:   Contains DLLMain and standard OLE COM object creation stuff.

**************************************************************************/

/**************************************************************************
   #include statements
**************************************************************************/

#include <ole2.h>
#include <comcat.h>
#include <olectl.h>
#include "ClsFact.h"

/**************************************************************************
   GUID stuff
**************************************************************************/

//this part is only done once
//if you need to use the GUID in another file, just include Guid.h
#pragma data_seg(".text")
#define INITGUID
#include <initguid.h>
#include <shlguid.h>
#include "Guid.h"
#pragma data_seg()

/**************************************************************************
   private function prototypes
**************************************************************************/

extern "C" BOOL WINAPI DllMain(HINSTANCE, DWORD, LPVOID);
BOOL RegisterServer(CLSID, LPTSTR);
BOOL RegisterComCat(CLSID, CATID);

/**************************************************************************
   global variables
**************************************************************************/

HINSTANCE   g_hInst;
UINT        g_DllRefCount;

/**************************************************************************

   DllMain

**************************************************************************/

extern "C" BOOL WINAPI DllMain(  HINSTANCE hInstance,
                                 DWORD dwReason,
                                 LPVOID lpReserved)
{
switch(dwReason)
   {
   case DLL_PROCESS_ATTACH:
      g_hInst = hInstance;
      break;

   case DLL_PROCESS_DETACH:
      break;
   }

return TRUE;
}

/**************************************************************************

   DllCanUnloadNow

**************************************************************************/

STDAPI DllCanUnloadNow(void)
{
return (g_DllRefCount ? S_FALSE : S_OK);
}

/**************************************************************************

   DllGetClassObject

**************************************************************************/

STDAPI DllGetClassObject(  REFCLSID rclsid,
                           REFIID riid,
                           LPVOID *ppReturn)
{
*ppReturn = NULL;

//if we don't support this classid, return the proper error code
if(   !IsEqualCLSID(rclsid, CLSID_SampleDeskBand) &&
      !IsEqualCLSID(rclsid, CLSID_SampleExplorerBar) &&
      !IsEqualCLSID(rclsid, CLSID_SampleCommBand))
   return CLASS_E_CLASSNOTAVAILABLE;

//create a CClassFactory object and check it for validity
CClassFactory *pClassFactory = new CClassFactory(rclsid);
if(NULL == pClassFactory)
   return E_OUTOFMEMORY;

//get the QueryInterface return for our return value
HRESULT hResult = pClassFactory->QueryInterface(riid, ppReturn);

//call Release to decement the ref count - creating the object set it to one
//and QueryInterface incremented it - since its being used externally (not by
//us), we only want the ref count to be 1
pClassFactory->Release();

//return the result from QueryInterface
return hResult;
}

/**************************************************************************

   DllRegisterServer

**************************************************************************/

STDAPI DllRegisterServer(void)
{
//Register the desk band object.
if(!RegisterServer(CLSID_SampleDeskBand, TEXT("Sample &Desk Band")))
   return SELFREG_E_CLASS;

//Register the component categories for the desk band object.
if(!RegisterComCat(CLSID_SampleDeskBand, CATID_DeskBand))
   return SELFREG_E_CLASS;

//Register the vertical explorer bar object.
if(!RegisterServer(CLSID_SampleExplorerBar, TEXT("Sample &Vertical Explorer Bar")))
   return SELFREG_E_CLASS;

//Register the component categories for the explorer bar object.
if(!RegisterComCat(CLSID_SampleExplorerBar, CATID_InfoBand))
   return SELFREG_E_CLASS;

//Register the comm band object.
if(!RegisterServer(CLSID_SampleCommBand, TEXT("Sample &Horizontal Explorer Bar")))
   return SELFREG_E_CLASS;

//Register the component categories for the comm band object.
if(!RegisterComCat(CLSID_SampleCommBand, CATID_CommBand))
   return SELFREG_E_CLASS;

return S_OK;
}

/**************************************************************************

   RegisterServer

**************************************************************************/

typedef struct{
   HKEY  hRootKey;
   LPTSTR szSubKey;//TCHAR szSubKey[MAX_PATH];
   LPTSTR lpszValueName;
   LPTSTR szData;//TCHAR szData[MAX_PATH];
}DOREGSTRUCT, *LPDOREGSTRUCT;

BOOL RegisterServer(CLSID clsid, LPTSTR lpszTitle)
{
int      i;
HKEY     hKey;
LRESULT  lResult;
DWORD    dwDisp;
TCHAR    szSubKey[MAX_PATH];
TCHAR    szCLSID[MAX_PATH];
TCHAR    szModule[MAX_PATH];
LPWSTR   pwsz;

//get the CLSID in string form
StringFromIID(clsid, &pwsz);

if(pwsz)
   {
#ifdef UNICODE
   lstrcpy(szCLSID, pwsz);
#else
   WideCharToMultiByte( CP_ACP,
                        0,
                        pwsz,
                        -1,
                        szCLSID,
                        ARRAYSIZE(szCLSID),
                        NULL,
                        NULL);
#endif

   //free the string
   LPMALLOC pMalloc;
   CoGetMalloc(1, &pMalloc);
   pMalloc->Free(pwsz);
   pMalloc->Release();
   }

//get this app's path and file name
GetModuleFileName(g_hInst, szModule, ARRAYSIZE(szModule));

DOREGSTRUCT ClsidEntries[ ] = {HKEY_CLASSES_ROOT,   TEXT("CLSID\\%s"),                  NULL,                   lpszTitle,
                              HKEY_CLASSES_ROOT,   TEXT("CLSID\\%s\\InprocServer32"),  NULL,                   szModule,
                              HKEY_CLASSES_ROOT,   TEXT("CLSID\\%s\\InprocServer32"),  TEXT("ThreadingModel"), TEXT("Apartment"),
                              NULL,                NULL,                               NULL,                   NULL};

//register the CLSID entries
for(i = 0; ClsidEntries[i].hRootKey; i++)
   {
   //create the sub key string - for this case, insert the file extension
   wsprintf(szSubKey, ClsidEntries[i].szSubKey, szCLSID);

   lResult = RegCreateKeyEx(  ClsidEntries[i].hRootKey,
                              szSubKey,
                              0,
                              NULL,
                              REG_OPTION_NON_VOLATILE,
                              KEY_WRITE,
                              NULL,
                              &hKey,
                              &dwDisp);

   if(NOERROR == lResult)
      {
      TCHAR szData[MAX_PATH];

      //if necessary, create the value string
      wsprintf(szData, ClsidEntries[i].szData, szModule);

      lResult = RegSetValueEx(   hKey,
                                 ClsidEntries[i].lpszValueName,
                                 0,
                                 REG_SZ,
                                 (LPBYTE)szData,
                                 (lstrlen(szData) + 1) * sizeof(TCHAR));

      RegCloseKey(hKey);
      }
   else
      return FALSE;
   }

return TRUE;
}

/**************************************************************************

   RegisterComCat

**************************************************************************/

BOOL RegisterComCat(CLSID clsid, CATID CatID)
{
ICatRegister   *pcr;
HRESULT        hr = S_OK ;

CoInitialize(NULL);

hr = CoCreateInstance(  CLSID_StdComponentCategoriesMgr,
                        NULL,
                        CLSCTX_INPROC_SERVER,
                        IID_ICatRegister,
                        (LPVOID*)&pcr);

if(SUCCEEDED(hr))
   {
   hr = pcr->RegisterClassImplCategories(clsid, 1, &CatID);

   pcr->Release();
   }

CoUninitialize();

return SUCCEEDED(hr);
}

/*
*/


ClsFact.cpp

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          ClsFact.cpp

   Description:   Implements CClassFactory.

**************************************************************************/

/**************************************************************************
   #include statements
**************************************************************************/

#include "ClsFact.h"
#include "Guid.h"

/**************************************************************************
   private function prototypes
**************************************************************************/

/**************************************************************************
   global variables
**************************************************************************/

///////////////////////////////////////////////////////////////////////////
//
// IClassFactory implementation
//

/**************************************************************************

   CClassFactory::CClassFactory

**************************************************************************/

CClassFactory::CClassFactory(CLSID clsid)
{
m_clsidObject = clsid;
m_ObjRefCount = 1;
g_DllRefCount++;
}

/**************************************************************************

   CClassFactory::~CClassFactory

**************************************************************************/

CClassFactory::~CClassFactory()
{
g_DllRefCount--;
}

/**************************************************************************

   CClassFactory::QueryInterface

**************************************************************************/

STDMETHODIMP CClassFactory::QueryInterface(REFIID riid, LPVOID *ppReturn)
{
*ppReturn = NULL;

if(IsEqualIID(riid, IID_IUnknown))
   {
   *ppReturn = this;
   }

else if(IsEqualIID(riid, IID_IClassFactory))
   {
   *ppReturn = (IClassFactory*)this;
   }

if(*ppReturn)
   {
   (*(LPUNKNOWN*)ppReturn)->AddRef();
   return S_OK;
   }

return E_NOINTERFACE;
}

/**************************************************************************

   CClassFactory::AddRef

**************************************************************************/

STDMETHODIMP_(DWORD) CClassFactory::AddRef()
{
return ++m_ObjRefCount;
}

/**************************************************************************

   CClassFactory::Release

**************************************************************************/

STDMETHODIMP_(DWORD) CClassFactory::Release()
{
if(--m_ObjRefCount == 0)
   {
   delete this;
   return 0;
   }

return m_ObjRefCount;
}

/**************************************************************************

   CClassFactory::CreateInstance

**************************************************************************/

STDMETHODIMP CClassFactory::CreateInstance(  LPUNKNOWN pUnknown,
                                             REFIID riid,
                                             LPVOID *ppObject)
{
HRESULT  hResult = E_FAIL;
LPVOID   pTemp = NULL;

*ppObject = NULL;

if(pUnknown != NULL)
   return CLASS_E_NOAGGREGATION;

//create the proper object
if(IsEqualCLSID(m_clsidObject, CLSID_SampleDeskBand))
   {
   CDeskBand *pDeskBand = new CDeskBand();
   if(NULL == pDeskBand)
      return E_OUTOFMEMORY;

   pTemp = pDeskBand;
   }

if(IsEqualCLSID(m_clsidObject, CLSID_SampleExplorerBar))
   {
   CExplorerBar *pExplorerBar = new CExplorerBar();
   if(NULL == pExplorerBar)
      return E_OUTOFMEMORY;

   pTemp = pExplorerBar;
   }

if(IsEqualCLSID(m_clsidObject, CLSID_SampleCommBand))
   {
   CCommBand *pCommBand = new CCommBand();
   if(NULL == pCommBand)
      return E_OUTOFMEMORY;

   pTemp = pCommBand;
   }

if(pTemp)
   {
   //get the QueryInterface return for our return value
   hResult = ((LPUNKNOWN)pTemp)->QueryInterface(riid, ppObject);

   //call Release to decement the ref count
   ((LPUNKNOWN)pTemp)->Release();
   }

return hResult;
}

/**************************************************************************

   CClassFactory::LockServer

**************************************************************************/

STDMETHODIMP CClassFactory::LockServer(BOOL)
{
return E_NOTIMPL;
}

/*
*/


ClsFact.h

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          ClsFact.h

   Description:   CClassFactory definitions.

**************************************************************************/

#ifndef CLASSFACTORY_H
#define CLASSFACTORY_H

#include <windows.h>
#include "Globals.h"
#include "DeskBand.h"
#include "ExplrBar.h"
#include "CommBand.h"

/**************************************************************************

   CClassFactory class definition

**************************************************************************/

class CClassFactory : public IClassFactory
{
protected:
   DWORD m_ObjRefCount;

public:
   CClassFactory(CLSID);
   ~CClassFactory();

   //IUnknown methods
   STDMETHODIMP QueryInterface(REFIID, LPVOID*);
   STDMETHODIMP_(DWORD) AddRef();
   STDMETHODIMP_(DWORD) Release();

   //IClassFactory methods
   STDMETHODIMP CreateInstance(LPUNKNOWN, REFIID, LPVOID*);
   STDMETHODIMP LockServer(BOOL);

private:
   CLSID m_clsidObject;
};

#endif   //CLASSFACTORY_H

/*
*/


CommBand.cpp

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          CommBand.cpp

   Description:   Implements CCommBand

**************************************************************************/

/**************************************************************************
   #include statements
**************************************************************************/

#include "CommBand.h"
#include "Guid.h"

/**************************************************************************

   CCommBand::CCommBand()

**************************************************************************/

CCommBand::CCommBand()
{
m_pSite = NULL;

m_hWnd = NULL;
m_hwndParent = NULL;

m_bFocus = FALSE;

m_dwViewMode = 0;
m_dwBandID = 0;

m_ObjRefCount = 1;
g_DllRefCount++;
}

/**************************************************************************

   CCommBand::~CCommBand()

**************************************************************************/

CCommBand::~CCommBand()
{
//this should have been freed in a call to SetSite(NULL), but just to be safe
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

g_DllRefCount--;
}

///////////////////////////////////////////////////////////////////////////
//
// IUnknown Implementation
//

/**************************************************************************

   CCommBand::QueryInterface

**************************************************************************/

STDMETHODIMP CCommBand::QueryInterface(REFIID riid, LPVOID *ppReturn)
{
*ppReturn = NULL;

//IUnknown
if(IsEqualIID(riid, IID_IUnknown))
   {
   *ppReturn = this;
   }

//IOleWindow
else if(IsEqualIID(riid, IID_IOleWindow))
   {
   *ppReturn = (IOleWindow*)this;
   }

//IDockingWindow
else if(IsEqualIID(riid, IID_IDockingWindow))
   {
   *ppReturn = (IDockingWindow*)this;
   }

//IInputObject
else if(IsEqualIID(riid, IID_IInputObject))
   {
   *ppReturn = (IInputObject*)this;
   }

//IObjectWithSite
else if(IsEqualIID(riid, IID_IObjectWithSite))
   {
   *ppReturn = (IObjectWithSite*)this;
   }

//IDeskBand
else if(IsEqualIID(riid, IID_IDeskBand))
   {
   *ppReturn = (IDeskBand*)this;
   }

//IPersist
else if(IsEqualIID(riid, IID_IPersist))
   {
   *ppReturn = (IPersist*)this;
   }

//IPersistStream
else if(IsEqualIID(riid, IID_IPersistStream))
   {
   *ppReturn = (IPersistStream*)this;
   }

if(*ppReturn)
   {
   (*(LPUNKNOWN*)ppReturn)->AddRef();
   return S_OK;
   }

return E_NOINTERFACE;
}

/**************************************************************************

   CCommBand::AddRef

**************************************************************************/

STDMETHODIMP_(DWORD) CCommBand::AddRef()
{
return ++m_ObjRefCount;
}

/**************************************************************************

   CCommBand::Release

**************************************************************************/

STDMETHODIMP_(DWORD) CCommBand::Release()
{
if(--m_ObjRefCount == 0)
   {
   delete this;
   return 0;
   }

return m_ObjRefCount;
}

///////////////////////////////////////////////////////////////////////////
//
// IOleWindow Implementation
//

/**************************************************************************

   CCommBand::GetWindow()

**************************************************************************/

STDMETHODIMP CCommBand::GetWindow(HWND *phWnd)
{
*phWnd = m_hWnd;

return S_OK;
}

/**************************************************************************

   CCommBand::ContextSensitiveHelp()

**************************************************************************/

STDMETHODIMP CCommBand::ContextSensitiveHelp(BOOL fEnterMode)
{
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IDockingWindow Implementation
//

/**************************************************************************

   CCommBand::ShowDW()

**************************************************************************/

STDMETHODIMP CCommBand::ShowDW(BOOL fShow)
{
if(m_hWnd)
   {
   if(fShow)
      {
      //show our window
      ShowWindow(m_hWnd, SW_SHOW);
      }
   else
      {
      //hide our window
      ShowWindow(m_hWnd, SW_HIDE);
      }
   }

return S_OK;
}

/**************************************************************************

   CCommBand::CloseDW()

**************************************************************************/

STDMETHODIMP CCommBand::CloseDW(DWORD dwReserved)
{
ShowDW(FALSE);

if(IsWindow(m_hWnd))
   DestroyWindow(m_hWnd);

m_hWnd = NULL;

return S_OK;
}

/**************************************************************************

   CCommBand::ResizeBorderDW()

**************************************************************************/

STDMETHODIMP CCommBand::ResizeBorderDW(   LPCRECT prcBorder,
                                          IUnknown* punkSite,
                                          BOOL fReserved)
{
/*
This method is never called for Band Objects.
*/
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IInputObject Implementation
//

/**************************************************************************

   CCommBand::UIActivateIO()

**************************************************************************/

STDMETHODIMP CCommBand::UIActivateIO(BOOL fActivate, LPMSG pMsg)
{
if(fActivate)
   SetFocus(m_hWnd);

return S_OK;
}

/**************************************************************************

   CCommBand::HasFocusIO()

   If this window or one of its decendants has the focus, return S_OK. Return
   S_FALSE if we don't have the focus.

**************************************************************************/

STDMETHODIMP CCommBand::HasFocusIO(void)
{
if(m_bFocus)
   return S_OK;

return S_FALSE;
}

/**************************************************************************

   CCommBand::TranslateAcceleratorIO()

   If the accelerator is translated, return S_OK or S_FALSE otherwise.

**************************************************************************/

STDMETHODIMP CCommBand::TranslateAcceleratorIO(LPMSG pMsg)
{
return S_FALSE;
}

///////////////////////////////////////////////////////////////////////////
//
// IObjectWithSite implementations
//

/**************************************************************************

   CCommBand::SetSite()

**************************************************************************/

STDMETHODIMP CCommBand::SetSite(IUnknown* punkSite)
{
//If a site is being held, release it.
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

//If punkSite is not NULL, a new site is being set.
if(punkSite)
   {
   //Get the parent window.
   IOleWindow  *pOleWindow;

   m_hwndParent = NULL;

   if(SUCCEEDED(punkSite->QueryInterface(IID_IOleWindow, (LPVOID*)&pOleWindow)))
      {
      pOleWindow->GetWindow(&m_hwndParent);
      pOleWindow->Release();
      }

   if(!m_hwndParent)
      return E_FAIL;

   if(!RegisterAndCreateWindow())
      return E_FAIL;

   //Get and keep the IInputObjectSite pointer.
   if(SUCCEEDED(punkSite->QueryInterface(IID_IInputObjectSite, (LPVOID*)&m_pSite)))
      {
      return S_OK;
      }

   return E_FAIL;
   }

return S_OK;
}

/**************************************************************************

   CCommBand::GetSite()

**************************************************************************/

STDMETHODIMP CCommBand::GetSite(REFIID riid, LPVOID *ppvReturn)
{
*ppvReturn = NULL;

if(m_pSite)
   return m_pSite->QueryInterface(riid, ppvReturn);

return E_FAIL;
}

///////////////////////////////////////////////////////////////////////////
//
// IDeskBand implementation
//

/**************************************************************************

   CCommBand::GetBandInfo()

**************************************************************************/

STDMETHODIMP CCommBand::GetBandInfo(DWORD dwBandID, DWORD dwViewMode, DESKBANDINFO* pdbi)
{
if(pdbi)
   {
   m_dwBandID = dwBandID;
   m_dwViewMode = dwViewMode;

   if(pdbi->dwMask & DBIM_MINSIZE)
      {
      pdbi->ptMinSize.x = 0;
      pdbi->ptMinSize.y = 30;
      }

   if(pdbi->dwMask & DBIM_MAXSIZE)
      {
      pdbi->ptMaxSize.x = -1;
      pdbi->ptMaxSize.y = 30;
      }

   if(pdbi->dwMask & DBIM_INTEGRAL)
      {
      pdbi->ptIntegral.x = 1;
      pdbi->ptIntegral.y = 1;
      }

   if(pdbi->dwMask & DBIM_ACTUAL)
      {
      pdbi->ptActual.x = 0;
      pdbi->ptActual.y = 0;
      }

   if(pdbi->dwMask & DBIM_TITLE)
      {
      lstrcpyW(pdbi->wszTitle, L"");
      }

   if(pdbi->dwMask & DBIM_MODEFLAGS)
      {
      pdbi->dwModeFlags = DBIMF_NORMAL;
      }

   if(pdbi->dwMask & DBIM_BKCOLOR)
      {
      //Use the default background color by removing this flag.
      pdbi->dwMask &= ~DBIM_BKCOLOR;
      }

   return S_OK;
   }

return E_INVALIDARG;
}

///////////////////////////////////////////////////////////////////////////
//
// IPersistStream implementations
//
// This is only supported to allow the desk band to be dropped on the
// desktop and to prevent multiple instances of the desk band from showing
// up in the shortcut menu. This desk band doesn't actually persist any data.
//

/**************************************************************************

   CCommBand::GetClassID()

**************************************************************************/

STDMETHODIMP CCommBand::GetClassID(LPCLSID pClassID)
{
*pClassID = CLSID_SampleCommBand;

return S_OK;
}

/**************************************************************************

   CCommBand::IsDirty()

**************************************************************************/

STDMETHODIMP CCommBand::IsDirty(void)
{
return S_FALSE;
}

/**************************************************************************

   CCommBand::Load()

**************************************************************************/

STDMETHODIMP CCommBand::Load(LPSTREAM pStream)
{
return S_OK;
}

/**************************************************************************

   CCommBand::Save()

**************************************************************************/

STDMETHODIMP CCommBand::Save(LPSTREAM pStream, BOOL fClearDirty)
{
return S_OK;
}

/**************************************************************************

   CCommBand::GetSizeMax()

**************************************************************************/

STDMETHODIMP CCommBand::GetSizeMax(ULARGE_INTEGER *pul)
{
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// private method implementations
//

/**************************************************************************

   CCommBand::WndProc()

**************************************************************************/

LRESULT CALLBACK CCommBand::WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam)
{
CCommBand  *pThis = (CCommBand*)GetWindowLong(hWnd, GWL_USERDATA);

switch (uMessage)
   {
   case WM_NCCREATE:
      {
      LPCREATESTRUCT lpcs = (LPCREATESTRUCT)lParam;
      pThis = (CCommBand*)(lpcs->lpCreateParams);
      SetWindowLong(hWnd, GWL_USERDATA, (LONG)pThis);

      //set the window handle
      pThis->m_hWnd = hWnd;
      }
      break;

   case WM_PAINT:
      return pThis->OnPaint();

   case WM_COMMAND:
      return pThis->OnCommand(wParam, lParam);

   case WM_SETFOCUS:
      return pThis->OnSetFocus();

   case WM_KILLFOCUS:
      return pThis->OnKillFocus();
   }

return DefWindowProc(hWnd, uMessage, wParam, lParam);
}

/**************************************************************************

   CCommBand::OnPaint()

**************************************************************************/

LRESULT CCommBand::OnPaint(void)
{
PAINTSTRUCT ps;
RECT        rc;

BeginPaint(m_hWnd, &ps);

GetClientRect(m_hWnd, &rc);
SetTextColor(ps.hdc, RGB(0, 0, 0));
SetBkMode(ps.hdc, TRANSPARENT);
DrawText(ps.hdc, TEXT("Sample Comm Band"), -1, &rc, DT_SINGLELINE | DT_CENTER | DT_VCENTER);

EndPaint(m_hWnd, &ps);

return 0;
}

/**************************************************************************

   CCommBand::OnCommand()

**************************************************************************/

LRESULT CCommBand::OnCommand(WPARAM wParam, LPARAM lParam)
{
return 0;
}

/**************************************************************************

   CCommBand::FocusChange()

**************************************************************************/

void CCommBand::FocusChange(BOOL bFocus)
{
m_bFocus = bFocus;

//inform the input object site that the focus has changed
if(m_pSite)
   {
   m_pSite->OnFocusChangeIS((IDockingWindow*)this, bFocus);
   }
}

/**************************************************************************

   CCommBand::OnSetFocus()

**************************************************************************/

LRESULT CCommBand::OnSetFocus(void)
{
FocusChange(TRUE);

return 0;
}

/**************************************************************************

   CCommBand::OnKillFocus()

**************************************************************************/

LRESULT CCommBand::OnKillFocus(void)
{
FocusChange(FALSE);

return 0;
}

/**************************************************************************

   CCommBand::RegisterAndCreateWindow()

**************************************************************************/

BOOL CCommBand::RegisterAndCreateWindow(void)
{
//If the window doesn't exist yet, create it now.
if(!m_hWnd)
   {
   //Can't create a child window without a parent.
   if(!m_hwndParent)
      {
      return FALSE;
      }

   //If the window class has not been registered, then do so.
   WNDCLASS wc;
   if(!GetClassInfo(g_hInst, CB_CLASS_NAME, &wc))
      {
      ZeroMemory(&wc, sizeof(wc));
      wc.style          = CS_HREDRAW | CS_VREDRAW | CS_GLOBALCLASS;
      wc.lpfnWndProc    = (WNDPROC)WndProc;
      wc.cbClsExtra     = 0;
      wc.cbWndExtra     = 0;
      wc.hInstance      = g_hInst;
      wc.hIcon          = NULL;
      wc.hCursor        = LoadCursor(NULL, IDC_ARROW);
      wc.hbrBackground  = (HBRUSH)CreateSolidBrush(RGB(0, 192, 0));
      wc.lpszMenuName   = NULL;
      wc.lpszClassName  = CB_CLASS_NAME;

      if(!RegisterClass(&wc))
         {
         //If RegisterClass fails, CreateWindow below will fail.
         }
      }

   RECT  rc;

   GetClientRect(m_hwndParent, &rc);

   //Create the window. The WndProc will set m_hWnd.
   CreateWindowEx(   0,
                     CB_CLASS_NAME,
                     NULL,
                     WS_CHILD | WS_CLIPSIBLINGS | WS_BORDER,
                     rc.left,
                     rc.top,
                     rc.right - rc.left,
                     rc.bottom - rc.top,
                     m_hwndParent,
                     NULL,
                     g_hInst,
                     (LPVOID)this);

   }

return (NULL != m_hWnd);
}

/*
*/


CommBand.h

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          CommBand.h

   Description:   CCommBand definitions.

**************************************************************************/

#include <windows.h>
#include <shlobj.h>

#include "Globals.h"

#ifndef COMMBAND_H
#define COMMBAND_H

#define CB_CLASS_NAME (TEXT("CommBandSampleClass"))

/**************************************************************************

   CCommBand class definition

**************************************************************************/

class CCommBand : public IDeskBand,
                  public IInputObject,
                  public IObjectWithSite,
                  public IPersistStream
{
protected:
   DWORD m_ObjRefCount;

public:
   CCommBand();
   ~CCommBand();

   //IUnknown methods
   STDMETHODIMP QueryInterface(REFIID, LPVOID*);
   STDMETHODIMP_(DWORD) AddRef();
   STDMETHODIMP_(DWORD) Release();

   //IOleWindow methods
   STDMETHOD (GetWindow) (HWND*);
   STDMETHOD (ContextSensitiveHelp) (BOOL);

   //IDockingWindow methods
   STDMETHOD (ShowDW) (BOOL fShow);
   STDMETHOD (CloseDW) (DWORD dwReserved);
   STDMETHOD (ResizeBorderDW) (LPCRECT prcBorder, IUnknown* punkToolbarSite, BOOL fReserved);

   //IDeskBand methods
   STDMETHOD (GetBandInfo) (DWORD, DWORD, DESKBANDINFO*);

   //IInputObject methods
   STDMETHOD (UIActivateIO) (BOOL, LPMSG);
   STDMETHOD (HasFocusIO) (void);
   STDMETHOD (TranslateAcceleratorIO) (LPMSG);

   //IObjectWithSite methods
   STDMETHOD (SetSite) (IUnknown*);
   STDMETHOD (GetSite) (REFIID, LPVOID*);

   //IPersistStream methods
   STDMETHOD (GetClassID) (LPCLSID);
   STDMETHOD (IsDirty) (void);
   STDMETHOD (Load) (LPSTREAM);
   STDMETHOD (Save) (LPSTREAM, BOOL);
   STDMETHOD (GetSizeMax) (ULARGE_INTEGER*);

private:
    BOOL m_bFocus;
    HWND m_hwndParent;
    HWND m_hWnd;
    DWORD m_dwViewMode;
   DWORD m_dwBandID;
   IInputObjectSite *m_pSite;

private:
    void FocusChange(BOOL);
   LRESULT OnKillFocus(void);
    LRESULT OnSetFocus(void);
    static LRESULT CALLBACK WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam);
    LRESULT OnPaint(void);
    LRESULT OnCommand(WPARAM wParam, LPARAM lParam);
   BOOL RegisterAndCreateWindow(void);
};

#endif   //COMMBAND_H

/*
*/


DeskBand.cpp

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          DeskBand.cpp

   Description:   Implements CDeskBand

**************************************************************************/

/**************************************************************************
   #include statements
**************************************************************************/

#include "DeskBand.h"
#include "Guid.h"

/**************************************************************************

   CDeskBand::CDeskBand()

**************************************************************************/

CDeskBand::CDeskBand()
{
m_pSite = NULL;

m_hWnd = NULL;
m_hwndParent = NULL;

m_bFocus = FALSE;

m_dwViewMode = 0;
m_dwBandID = 0;

m_ObjRefCount = 1;
g_DllRefCount++;
}

/**************************************************************************

   CDeskBand::~CDeskBand()

**************************************************************************/

CDeskBand::~CDeskBand()
{
//this should have been freed in a call to SetSite(NULL), but just to be safe
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

g_DllRefCount--;
}

///////////////////////////////////////////////////////////////////////////
//
// IUnknown Implementation
//

/**************************************************************************

   CDeskBand::QueryInterface

**************************************************************************/

STDMETHODIMP CDeskBand::QueryInterface(REFIID riid, LPVOID *ppReturn)
{
*ppReturn = NULL;

//IUnknown
if(IsEqualIID(riid, IID_IUnknown))
   {
   *ppReturn = this;
   }

//IOleWindow
else if(IsEqualIID(riid, IID_IOleWindow))
   {
   *ppReturn = (IOleWindow*)this;
   }

//IDockingWindow
else if(IsEqualIID(riid, IID_IDockingWindow))
   {
   *ppReturn = (IDockingWindow*)this;
   }

//IInputObject
else if(IsEqualIID(riid, IID_IInputObject))
   {
   *ppReturn = (IInputObject*)this;
   }

//IObjectWithSite
else if(IsEqualIID(riid, IID_IObjectWithSite))
   {
   *ppReturn = (IObjectWithSite*)this;
   }

//IDeskBand
else if(IsEqualIID(riid, IID_IDeskBand))
   {
   *ppReturn = (IDeskBand*)this;
   }

//IPersist
else if(IsEqualIID(riid, IID_IPersist))
   {
   *ppReturn = (IPersist*)this;
   }

//IPersistStream
else if(IsEqualIID(riid, IID_IPersistStream))
   {
   *ppReturn = (IPersistStream*)this;
   }

//IContextMenu
else if(IsEqualIID(riid, IID_IContextMenu))
   {
   *ppReturn = (IContextMenu*)this;
   }

if(*ppReturn)
   {
   (*(LPUNKNOWN*)ppReturn)->AddRef();
   return S_OK;
   }

return E_NOINTERFACE;
}

/**************************************************************************

   CDeskBand::AddRef

**************************************************************************/

STDMETHODIMP_(DWORD) CDeskBand::AddRef()
{
return ++m_ObjRefCount;
}

/**************************************************************************

   CDeskBand::Release

**************************************************************************/

STDMETHODIMP_(DWORD) CDeskBand::Release()
{
if(--m_ObjRefCount == 0)
   {
   delete this;
   return 0;
   }

return m_ObjRefCount;
}

///////////////////////////////////////////////////////////////////////////
//
// IOleWindow Implementation
//

/**************************************************************************

   CDeskBand::GetWindow()

**************************************************************************/

STDMETHODIMP CDeskBand::GetWindow(HWND *phWnd)
{
*phWnd = m_hWnd;

return S_OK;
}

/**************************************************************************

   CDeskBand::ContextSensitiveHelp()

**************************************************************************/

STDMETHODIMP CDeskBand::ContextSensitiveHelp(BOOL fEnterMode)
{
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IDockingWindow Implementation
//

/**************************************************************************

   CDeskBand::ShowDW()

**************************************************************************/

STDMETHODIMP CDeskBand::ShowDW(BOOL fShow)
{
if(m_hWnd)
   {
   if(fShow)
      {
      //show our window
      ShowWindow(m_hWnd, SW_SHOW);
      }
   else
      {
      //hide our window
      ShowWindow(m_hWnd, SW_HIDE);
      }
   }

return S_OK;
}

/**************************************************************************

   CDeskBand::CloseDW()

**************************************************************************/

STDMETHODIMP CDeskBand::CloseDW(DWORD dwReserved)
{
ShowDW(FALSE);

if(IsWindow(m_hWnd))
   DestroyWindow(m_hWnd);

m_hWnd = NULL;

return S_OK;
}

/**************************************************************************

   CDeskBand::ResizeBorderDW()

**************************************************************************/

STDMETHODIMP CDeskBand::ResizeBorderDW(   LPCRECT prcBorder,
                                          IUnknown* punkSite,
                                          BOOL fReserved)
{
/*
This method is never called for Band Objects.
*/
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IInputObject Implementation
//

/**************************************************************************

   CDeskBand::UIActivateIO()

**************************************************************************/

STDMETHODIMP CDeskBand::UIActivateIO(BOOL fActivate, LPMSG pMsg)
{
if(fActivate)
   SetFocus(m_hWnd);

return S_OK;
}

/**************************************************************************

   CDeskBand::HasFocusIO()

   If this window or one of its decendants has the focus, return S_OK. Return
   S_FALSE if we don't have the focus.

**************************************************************************/

STDMETHODIMP CDeskBand::HasFocusIO(void)
{
if(m_bFocus)
   return S_OK;

return S_FALSE;
}

/**************************************************************************

   CDeskBand::TranslateAcceleratorIO()

   If the accelerator is translated, return S_OK or S_FALSE otherwise.

**************************************************************************/

STDMETHODIMP CDeskBand::TranslateAcceleratorIO(LPMSG pMsg)
{
return S_FALSE;
}

///////////////////////////////////////////////////////////////////////////
//
// IObjectWithSite implementations
//

/**************************************************************************

   CDeskBand::SetSite()

**************************************************************************/

STDMETHODIMP CDeskBand::SetSite(IUnknown* punkSite)
{
//If a site is being held, release it.
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

//If punkSite is not NULL, a new site is being set.
if(punkSite)
   {
   //Get the parent window.
   IOleWindow  *pOleWindow;

   m_hwndParent = NULL;

   if(SUCCEEDED(punkSite->QueryInterface(IID_IOleWindow, (LPVOID*)&pOleWindow)))
      {
      pOleWindow->GetWindow(&m_hwndParent);
      pOleWindow->Release();
      }

   if(!m_hwndParent)
      return E_FAIL;

   if(!RegisterAndCreateWindow())
      return E_FAIL;

   //Get and keep the IInputObjectSite pointer.
   if(SUCCEEDED(punkSite->QueryInterface(IID_IInputObjectSite, (LPVOID*)&m_pSite)))
      {
      return S_OK;
      }

   return E_FAIL;
   }

return S_OK;
}

/**************************************************************************

   CDeskBand::GetSite()

**************************************************************************/

STDMETHODIMP CDeskBand::GetSite(REFIID riid, LPVOID *ppvReturn)
{
*ppvReturn = NULL;

if(m_pSite)
   return m_pSite->QueryInterface(riid, ppvReturn);

return E_FAIL;
}

///////////////////////////////////////////////////////////////////////////
//
// IDeskBand implementation
//

/**************************************************************************

   CDeskBand::GetBandInfo()

**************************************************************************/

STDMETHODIMP CDeskBand::GetBandInfo(DWORD dwBandID, DWORD dwViewMode, DESKBANDINFO* pdbi)
{
if(pdbi)
   {
   m_dwBandID = dwBandID;
   m_dwViewMode = dwViewMode;

   if(pdbi->dwMask & DBIM_MINSIZE)
      {
      if(DBIF_VIEWMODE_FLOATING & dwViewMode)
         {
         pdbi->ptMinSize.x = 200;
         pdbi->ptMinSize.y = 400;
         }
      else
         {
         pdbi->ptMinSize.x = MIN_SIZE_X;
         pdbi->ptMinSize.y = MIN_SIZE_Y;
         }
      }

   if(pdbi->dwMask & DBIM_MAXSIZE)
      {
      pdbi->ptMaxSize.x = -1;
      pdbi->ptMaxSize.y = -1;
      }

   if(pdbi->dwMask & DBIM_INTEGRAL)
      {
      pdbi->ptIntegral.x = 1;
      pdbi->ptIntegral.y = 1;
      }

   if(pdbi->dwMask & DBIM_ACTUAL)
      {
      pdbi->ptActual.x = 100;
      pdbi->ptActual.y = 100;
      }

   if(pdbi->dwMask & DBIM_TITLE)
      {
      lstrcpyW(pdbi->wszTitle, L"Sample Desk Band");
      }

   if(pdbi->dwMask & DBIM_MODEFLAGS)
      {
      pdbi->dwModeFlags = DBIMF_NORMAL;

      pdbi->dwModeFlags |= DBIMF_VARIABLEHEIGHT;
      }

   if(pdbi->dwMask & DBIM_BKCOLOR)
      {
      //Use the default background color by removing this flag.
      pdbi->dwMask &= ~DBIM_BKCOLOR;
      }

   return S_OK;
   }

return E_INVALIDARG;
}

///////////////////////////////////////////////////////////////////////////
//
// IPersistStream implementations
//
// This is only supported to allow the desk band to be dropped on the
// desktop and to prevent multiple instances of the desk band from showing
// up in the shortcut menu. This desk band doesn't actually persist any data.
//

/**************************************************************************

   CDeskBand::GetClassID()

**************************************************************************/

STDMETHODIMP CDeskBand::GetClassID(LPCLSID pClassID)
{
*pClassID = CLSID_SampleDeskBand;

return S_OK;
}

/**************************************************************************

   CDeskBand::IsDirty()

**************************************************************************/

STDMETHODIMP CDeskBand::IsDirty(void)
{
return S_FALSE;
}

/**************************************************************************

   CDeskBand::Load()

**************************************************************************/

STDMETHODIMP CDeskBand::Load(LPSTREAM pStream)
{
return S_OK;
}

/**************************************************************************

   CDeskBand::Save()

**************************************************************************/

STDMETHODIMP CDeskBand::Save(LPSTREAM pStream, BOOL fClearDirty)
{
return S_OK;
}

/**************************************************************************

   CDeskBand::GetSizeMax()

**************************************************************************/

STDMETHODIMP CDeskBand::GetSizeMax(ULARGE_INTEGER *pul)
{
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IContextMenu Implementation
//

/**************************************************************************

   CDeskBand::QueryContextMenu()

**************************************************************************/

STDMETHODIMP CDeskBand::QueryContextMenu( HMENU hMenu,
                                          UINT indexMenu,
                                          UINT idCmdFirst,
                                          UINT idCmdLast,
                                          UINT uFlags)
{
if(!(CMF_DEFAULTONLY & uFlags))
   {
   InsertMenu( hMenu,
               indexMenu,
               MF_STRING | MF_BYPOSITION,
               idCmdFirst + IDM_COMMAND,
               "&Desk Band Command");

   return MAKE_HRESULT(SEVERITY_SUCCESS, 0, USHORT(IDM_COMMAND + 1));
   }

return MAKE_HRESULT(SEVERITY_SUCCESS, 0, USHORT(0));
}

/**************************************************************************

   CDeskBand::InvokeCommand()

**************************************************************************/

STDMETHODIMP CDeskBand::InvokeCommand(LPCMINVOKECOMMANDINFO lpcmi)
{
switch (LOWORD(lpcmi->lpVerb))
   {
   case IDM_COMMAND:
      MessageBox(lpcmi->hwnd, TEXT("Desk Band Command selected."), TEXT("Sample Desk Band"), MB_OK | MB_ICONINFORMATION);
      break;

   default:
      return E_INVALIDARG;
   }

return NOERROR;
}

/**************************************************************************

   CDeskBand::GetCommandString()

**************************************************************************/

STDMETHODIMP CDeskBand::GetCommandString( UINT idCommand,
                                          UINT uFlags,
                                          LPUINT lpReserved,
                                          LPSTR lpszName,
                                          UINT uMaxNameLen)
{
HRESULT  hr = E_INVALIDARG;

switch(uFlags)
   {
   case GCS_HELPTEXT:
      switch(idCommand)
         {
         case IDM_COMMAND:
            lstrcpy(lpszName, TEXT("Desk Band command help text"));
            hr = NOERROR;
            break;
         }
      break;

   case GCS_VERB:
      switch(idCommand)
         {
         case IDM_COMMAND:
            lstrcpy(lpszName, TEXT("command"));
            hr = NOERROR;
            break;
         }
      break;

   case GCS_VALIDATE:
      hr = NOERROR;
      break;
   }

return hr;
}

///////////////////////////////////////////////////////////////////////////
//
// private method implementations
//

/**************************************************************************

   CDeskBand::WndProc()

**************************************************************************/

LRESULT CALLBACK CDeskBand::WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam)
{
CDeskBand  *pThis = (CDeskBand*)GetWindowLong(hWnd, GWL_USERDATA);

switch (uMessage)
   {
   case WM_NCCREATE:
      {
      LPCREATESTRUCT lpcs = (LPCREATESTRUCT)lParam;
      pThis = (CDeskBand*)(lpcs->lpCreateParams);
      SetWindowLong(hWnd, GWL_USERDATA, (LONG)pThis);

      //set the window handle
      pThis->m_hWnd = hWnd;
      }
      break;

   case WM_PAINT:
      return pThis->OnPaint();

   case WM_COMMAND:
      return pThis->OnCommand(wParam, lParam);

   case WM_SETFOCUS:
      return pThis->OnSetFocus();

   case WM_KILLFOCUS:
      return pThis->OnKillFocus();

   case WM_SIZE:
      return pThis->OnSize(lParam);
   }

return DefWindowProc(hWnd, uMessage, wParam, lParam);
}

/**************************************************************************

   CDeskBand::OnPaint()

**************************************************************************/

LRESULT CDeskBand::OnPaint(void)
{
PAINTSTRUCT ps;
RECT        rc;

BeginPaint(m_hWnd, &ps);

GetClientRect(m_hWnd, &rc);
SetTextColor(ps.hdc, RGB(0, 0, 0));
SetBkMode(ps.hdc, TRANSPARENT);
DrawText(ps.hdc, TEXT("Sample Desk Band"), -1, &rc, DT_SINGLELINE | DT_CENTER | DT_VCENTER);

EndPaint(m_hWnd, &ps);

return 0;
}

/**************************************************************************

   CDeskBand::OnCommand()

**************************************************************************/

LRESULT CDeskBand::OnCommand(WPARAM wParam, LPARAM lParam)
{
return 0;
}

/**************************************************************************

   CDeskBand::OnSize()

**************************************************************************/

LRESULT CDeskBand::OnSize(LPARAM lParam)
{
int   cx, cy;

cx = LOWORD(lParam);
cy = HIWORD(lParam);
return 0;
}

/**************************************************************************

   CDeskBand::FocusChange()

**************************************************************************/

void CDeskBand::FocusChange(BOOL bFocus)
{
m_bFocus = bFocus;

//inform the input object site that the focus has changed
if(m_pSite)
   {
   m_pSite->OnFocusChangeIS((IDockingWindow*)this, bFocus);
   }
}

/**************************************************************************

   CDeskBand::OnSetFocus()

**************************************************************************/

LRESULT CDeskBand::OnSetFocus(void)
{
FocusChange(TRUE);

return 0;
}

/**************************************************************************

   CDeskBand::OnKillFocus()

**************************************************************************/

LRESULT CDeskBand::OnKillFocus(void)
{
FocusChange(FALSE);

return 0;
}

/**************************************************************************

   CDeskBand::RegisterAndCreateWindow()

**************************************************************************/

BOOL CDeskBand::RegisterAndCreateWindow(void)
{
//If the window doesn't exist yet, create it now.
if(!m_hWnd)
   {
   //Can't create a child window without a parent.
   if(!m_hwndParent)
      {
      return FALSE;
      }

   //If the window class has not been registered, then do so.
   WNDCLASS wc;
   if(!GetClassInfo(g_hInst, DB_CLASS_NAME, &wc))
      {
      ZeroMemory(&wc, sizeof(wc));
      wc.style          = CS_HREDRAW | CS_VREDRAW | CS_GLOBALCLASS;
      wc.lpfnWndProc    = (WNDPROC)WndProc;
      wc.cbClsExtra     = 0;
      wc.cbWndExtra     = 0;
      wc.hInstance      = g_hInst;
      wc.hIcon          = NULL;
      wc.hCursor        = LoadCursor(NULL, IDC_ARROW);
      wc.hbrBackground  = (HBRUSH)CreateSolidBrush(RGB(192, 0, 0));
      wc.lpszMenuName   = NULL;
      wc.lpszClassName  = DB_CLASS_NAME;

      if(!RegisterClass(&wc))
         {
         //If RegisterClass fails, CreateWindow below will fail.
         }
      }

   RECT  rc;

   GetClientRect(m_hwndParent, &rc);

   //Create the window. The WndProc will set m_hWnd.
   CreateWindowEx(   0,
                     DB_CLASS_NAME,
                     NULL,
                     WS_CHILD | WS_CLIPSIBLINGS | WS_BORDER,
                     rc.left,
                     rc.top,
                     rc.right - rc.left,
                     rc.bottom - rc.top,
                     m_hwndParent,
                     NULL,
                     g_hInst,
                     (LPVOID)this);

   }

return (NULL != m_hWnd);
}

/*
*/


DeskBand.h

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          DeskBand.h

   Description:   CDeskBand definitions.

**************************************************************************/

#include <windows.h>
#include <shlobj.h>

#include "Globals.h"

#ifndef DESKBAND_H
#define DESKBAND_H

#define DB_CLASS_NAME (TEXT("DeskBandSampleClass"))

#define MIN_SIZE_X   10
#define MIN_SIZE_Y   10

#define IDM_COMMAND  0

/**************************************************************************

   CDeskBand class definition

**************************************************************************/

class CDeskBand : public IDeskBand,
                  public IInputObject,
                  public IObjectWithSite,
                  public IPersistStream,
                  public IContextMenu
{
protected:
   DWORD m_ObjRefCount;

public:
   CDeskBand();
   ~CDeskBand();

   //IUnknown methods
   STDMETHODIMP QueryInterface(REFIID, LPVOID*);
   STDMETHODIMP_(DWORD) AddRef();
   STDMETHODIMP_(DWORD) Release();

   //IOleWindow methods
   STDMETHOD (GetWindow) (HWND*);
   STDMETHOD (ContextSensitiveHelp) (BOOL);

   //IDockingWindow methods
   STDMETHOD (ShowDW) (BOOL fShow);
   STDMETHOD (CloseDW) (DWORD dwReserved);
   STDMETHOD (ResizeBorderDW) (LPCRECT prcBorder, IUnknown* punkToolbarSite, BOOL fReserved);

   //IDeskBand methods
   STDMETHOD (GetBandInfo) (DWORD, DWORD, DESKBANDINFO*);

   //IInputObject methods
   STDMETHOD (UIActivateIO) (BOOL, LPMSG);
   STDMETHOD (HasFocusIO) (void);
   STDMETHOD (TranslateAcceleratorIO) (LPMSG);

   //IObjectWithSite methods
   STDMETHOD (SetSite) (IUnknown*);
   STDMETHOD (GetSite) (REFIID, LPVOID*);

   //IPersistStream methods
   STDMETHOD (GetClassID) (LPCLSID);
   STDMETHOD (IsDirty) (void);
   STDMETHOD (Load) (LPSTREAM);
   STDMETHOD (Save) (LPSTREAM, BOOL);
   STDMETHOD (GetSizeMax) (ULARGE_INTEGER*);

   //IContextMenu methods
   STDMETHOD (QueryContextMenu)(HMENU, UINT, UINT, UINT, UINT);
   STDMETHOD (InvokeCommand)(LPCMINVOKECOMMANDINFO);
   STDMETHOD (GetCommandString)(UINT, UINT, LPUINT, LPSTR, UINT);

private:
    BOOL m_bFocus;
    HWND m_hwndParent;
    HWND m_hWnd;
    DWORD m_dwViewMode;
   DWORD m_dwBandID;
   IInputObjectSite *m_pSite;

private:
    void FocusChange(BOOL);
   LRESULT OnKillFocus(void);
    LRESULT OnSetFocus(void);
    static LRESULT CALLBACK WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam);
    LRESULT OnPaint(void);
    LRESULT OnCommand(WPARAM wParam, LPARAM lParam);
    LRESULT OnSize(LPARAM);
   BOOL RegisterAndCreateWindow(void);
};

#endif   //DESKBAND_H

/*
*/


ExplrBar.cpp

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          ExplorerBar.cpp

   Description:   Implements CExplorerBar

**************************************************************************/

/**************************************************************************
   #include statements
**************************************************************************/

#include "ExplrBar.h"
#include "Guid.h"

/**************************************************************************

   CExplorerBar::CExplorerBar()

**************************************************************************/

CExplorerBar::CExplorerBar()
{
m_pSite = NULL;

m_hWnd = NULL;
m_hwndParent = NULL;

m_bFocus = FALSE;

m_dwViewMode = 0;
m_dwBandID = 0;

m_ObjRefCount = 1;
g_DllRefCount++;
}

/**************************************************************************

   CExplorerBar::~CExplorerBar()

**************************************************************************/

CExplorerBar::~CExplorerBar()
{
//this should have been freed in a call to SetSite(NULL), but just to be safe
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

g_DllRefCount--;
}

///////////////////////////////////////////////////////////////////////////
//
// IUnknown Implementation
//

/**************************************************************************

   CExplorerBar::QueryInterface

**************************************************************************/

STDMETHODIMP CExplorerBar::QueryInterface(REFIID riid, LPVOID *ppReturn)
{
*ppReturn = NULL;

//IUnknown
if(IsEqualIID(riid, IID_IUnknown))
   {
   *ppReturn = this;
   }

//IOleWindow
else if(IsEqualIID(riid, IID_IOleWindow))
   {
   *ppReturn = (IOleWindow*)this;
   }

//IDockingWindow
else if(IsEqualIID(riid, IID_IDockingWindow))
   {
   *ppReturn = (IDockingWindow*)this;
   }

//IInputObject
else if(IsEqualIID(riid, IID_IInputObject))
   {
   *ppReturn = (IInputObject*)this;
   }

//IObjectWithSite
else if(IsEqualIID(riid, IID_IObjectWithSite))
   {
   *ppReturn = (IObjectWithSite*)this;
   }

//IDeskBand
else if(IsEqualIID(riid, IID_IDeskBand))
   {
   *ppReturn = (IDeskBand*)this;
   }

//IPersist
else if(IsEqualIID(riid, IID_IPersist))
   {
   *ppReturn = (IPersist*)this;
   }

//IPersistStream
else if(IsEqualIID(riid, IID_IPersistStream))
   {
   *ppReturn = (IPersistStream*)this;
   }

if(*ppReturn)
   {
   (*(LPUNKNOWN*)ppReturn)->AddRef();
   return S_OK;
   }

return E_NOINTERFACE;
}

/**************************************************************************

   CExplorerBar::AddRef

**************************************************************************/

STDMETHODIMP_(DWORD) CExplorerBar::AddRef()
{
return ++m_ObjRefCount;
}

/**************************************************************************

   CExplorerBar::Release

**************************************************************************/

STDMETHODIMP_(DWORD) CExplorerBar::Release()
{
if(--m_ObjRefCount == 0)
   {
   delete this;
   return 0;
   }

return m_ObjRefCount;
}

///////////////////////////////////////////////////////////////////////////
//
// IOleWindow Implementation
//

/**************************************************************************

   CExplorerBar::GetWindow()

**************************************************************************/

STDMETHODIMP CExplorerBar::GetWindow(HWND *phWnd)
{
*phWnd = m_hWnd;

return S_OK;
}

/**************************************************************************

   CExplorerBar::ContextSensitiveHelp()

**************************************************************************/

STDMETHODIMP CExplorerBar::ContextSensitiveHelp(BOOL fEnterMode)
{
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IDockingWindow Implementation
//

/**************************************************************************

   CExplorerBar::ShowDW()

**************************************************************************/

STDMETHODIMP CExplorerBar::ShowDW(BOOL fShow)
{
if(m_hWnd)
   {
   if(fShow)
      {
      //show our window
      ShowWindow(m_hWnd, SW_SHOW);
      }
   else
      {
      //hide our window
      ShowWindow(m_hWnd, SW_HIDE);
      }
   }

return S_OK;
}

/**************************************************************************

   CExplorerBar::CloseDW()

**************************************************************************/

STDMETHODIMP CExplorerBar::CloseDW(DWORD dwReserved)
{
ShowDW(FALSE);

if(IsWindow(m_hWnd))
   DestroyWindow(m_hWnd);

m_hWnd = NULL;

return S_OK;
}

/**************************************************************************

   CExplorerBar::ResizeBorderDW()

**************************************************************************/

STDMETHODIMP CExplorerBar::ResizeBorderDW(   LPCRECT prcBorder,
                                          IUnknown* punkSite,
                                          BOOL fReserved)
{
/*
This method is never called for Band Objects.
*/
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// IInputObject Implementation
//

/**************************************************************************

   CExplorerBar::UIActivateIO()

**************************************************************************/

STDMETHODIMP CExplorerBar::UIActivateIO(BOOL fActivate, LPMSG pMsg)
{
if(fActivate)
   SetFocus(m_hWnd);

return S_OK;
}

/**************************************************************************

   CExplorerBar::HasFocusIO()

   If this window or one of its decendants has the focus, return S_OK. Return
   S_FALSE if we don't have the focus.

**************************************************************************/

STDMETHODIMP CExplorerBar::HasFocusIO(void)
{
if(m_bFocus)
   return S_OK;

return S_FALSE;
}

/**************************************************************************

   CExplorerBar::TranslateAcceleratorIO()

   If the accelerator is translated, return S_OK or S_FALSE otherwise.

**************************************************************************/

STDMETHODIMP CExplorerBar::TranslateAcceleratorIO(LPMSG pMsg)
{
return S_FALSE;
}

///////////////////////////////////////////////////////////////////////////
//
// IObjectWithSite implementations
//

/**************************************************************************

   CExplorerBar::SetSite()

**************************************************************************/

STDMETHODIMP CExplorerBar::SetSite(IUnknown* punkSite)
{
//If a site is being held, release it.
if(m_pSite)
   {
   m_pSite->Release();
   m_pSite = NULL;
   }

//If punkSite is not NULL, a new site is being set.
if(punkSite)
   {
   //Get the parent window.
   IOleWindow  *pOleWindow;

   m_hwndParent = NULL;

   if(SUCCEEDED(punkSite->QueryInterface(IID_IOleWindow, (LPVOID*)&pOleWindow)))
      {
      pOleWindow->GetWindow(&m_hwndParent);
      pOleWindow->Release();
      }

   if(!m_hwndParent)
      return E_FAIL;

   if(!RegisterAndCreateWindow())
      return E_FAIL;

   //Get and keep the IInputObjectSite pointer.
   if(SUCCEEDED(punkSite->QueryInterface(IID_IInputObjectSite, (LPVOID*)&m_pSite)))
      {
      return S_OK;
      }

   return E_FAIL;
   }

return S_OK;
}

/**************************************************************************

   CExplorerBar::GetSite()

**************************************************************************/

STDMETHODIMP CExplorerBar::GetSite(REFIID riid, LPVOID *ppvReturn)
{
*ppvReturn = NULL;

if(m_pSite)
   return m_pSite->QueryInterface(riid, ppvReturn);

return E_FAIL;
}

///////////////////////////////////////////////////////////////////////////
//
// IDeskBand implementation
//

/**************************************************************************

   CExplorerBar::GetBandInfo()

**************************************************************************/

STDMETHODIMP CExplorerBar::GetBandInfo(DWORD dwBandID, DWORD dwViewMode, DESKBANDINFO* pdbi)
{
if(pdbi)
   {
   m_dwBandID = dwBandID;
   m_dwViewMode = dwViewMode;

   if(pdbi->dwMask & DBIM_MINSIZE)
      {
      pdbi->ptMinSize.x = MIN_SIZE_X;
      pdbi->ptMinSize.y = MIN_SIZE_Y;
      }

   if(pdbi->dwMask & DBIM_MAXSIZE)
      {
      pdbi->ptMaxSize.x = -1;
      pdbi->ptMaxSize.y = -1;
      }

   if(pdbi->dwMask & DBIM_INTEGRAL)
      {
      pdbi->ptIntegral.x = 1;
      pdbi->ptIntegral.y = 1;
      }

   if(pdbi->dwMask & DBIM_ACTUAL)
      {
      pdbi->ptActual.x = 0;
      pdbi->ptActual.y = 0;
      }

   if(pdbi->dwMask & DBIM_TITLE)
      {
      lstrcpyW(pdbi->wszTitle, L"Sample Explorer Bar");
      }

   if(pdbi->dwMask & DBIM_MODEFLAGS)
      {
      pdbi->dwModeFlags = DBIMF_VARIABLEHEIGHT;
      }

   if(pdbi->dwMask & DBIM_BKCOLOR)
      {
      //Use the default background color by removing this flag.
      pdbi->dwMask &= ~DBIM_BKCOLOR;
      }

   return S_OK;
   }

return E_INVALIDARG;
}

///////////////////////////////////////////////////////////////////////////
//
// IPersistStream implementations
//
// This is only supported to allow the desk band to be dropped on the
// desktop and to prevent multiple instances of the desk band from showing
// up in the shortcut menu. This desk band doesn't actually persist any data.
//

/**************************************************************************

   CExplorerBar::GetClassID()

**************************************************************************/

STDMETHODIMP CExplorerBar::GetClassID(LPCLSID pClassID)
{
*pClassID = CLSID_SampleExplorerBar;

return S_OK;
}

/**************************************************************************

   CExplorerBar::IsDirty()

**************************************************************************/

STDMETHODIMP CExplorerBar::IsDirty(void)
{
return S_FALSE;
}

/**************************************************************************

   CExplorerBar::Load()

**************************************************************************/

STDMETHODIMP CExplorerBar::Load(LPSTREAM pStream)
{
return S_OK;
}

/**************************************************************************

   CExplorerBar::Save()

**************************************************************************/

STDMETHODIMP CExplorerBar::Save(LPSTREAM pStream, BOOL fClearDirty)
{
return S_OK;
}

/**************************************************************************

   CExplorerBar::GetSizeMax()

**************************************************************************/

STDMETHODIMP CExplorerBar::GetSizeMax(ULARGE_INTEGER *pul)
{
return E_NOTIMPL;
}

///////////////////////////////////////////////////////////////////////////
//
// private method implementations
//

/**************************************************************************

   CExplorerBar::WndProc()

**************************************************************************/

LRESULT CALLBACK CExplorerBar::WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam)
{
CExplorerBar  *pThis = (CExplorerBar*)GetWindowLong(hWnd, GWL_USERDATA);

switch (uMessage)
   {
   case WM_NCCREATE:
      {
      LPCREATESTRUCT lpcs = (LPCREATESTRUCT)lParam;
      pThis = (CExplorerBar*)(lpcs->lpCreateParams);
      SetWindowLong(hWnd, GWL_USERDATA, (LONG)pThis);

      //set the window handle
      pThis->m_hWnd = hWnd;
      }
      break;

   case WM_PAINT:
      return pThis->OnPaint();

   case WM_COMMAND:
      return pThis->OnCommand(wParam, lParam);

   case WM_SETFOCUS:
      return pThis->OnSetFocus();

   case WM_KILLFOCUS:
      return pThis->OnKillFocus();
   }

return DefWindowProc(hWnd, uMessage, wParam, lParam);
}

/**************************************************************************

   CExplorerBar::OnPaint()

**************************************************************************/

LRESULT CExplorerBar::OnPaint(void)
{
PAINTSTRUCT ps;
RECT        rc;

BeginPaint(m_hWnd, &ps);

GetClientRect(m_hWnd, &rc);
SetTextColor(ps.hdc, RGB(255, 255, 255));
SetBkMode(ps.hdc, TRANSPARENT);
DrawText(ps.hdc, TEXT("Sample Explorer Bar"), -1, &rc, DT_SINGLELINE | DT_CENTER | DT_VCENTER);

EndPaint(m_hWnd, &ps);

return 0;
}

/**************************************************************************

   CExplorerBar::OnCommand()

**************************************************************************/

LRESULT CExplorerBar::OnCommand(WPARAM wParam, LPARAM lParam)
{
return 0;
}

/**************************************************************************

   CExplorerBar::FocusChange()

**************************************************************************/

void CExplorerBar::FocusChange(BOOL bFocus)
{
m_bFocus = bFocus;

//inform the input object site that the focus has changed
if(m_pSite)
   {
   m_pSite->OnFocusChangeIS((IDockingWindow*)this, bFocus);
   }
}

/**************************************************************************

   CExplorerBar::OnSetFocus()

**************************************************************************/

LRESULT CExplorerBar::OnSetFocus(void)
{
FocusChange(TRUE);

return 0;
}

/**************************************************************************

   CExplorerBar::OnKillFocus()

**************************************************************************/

LRESULT CExplorerBar::OnKillFocus(void)
{
FocusChange(FALSE);

return 0;
}

/**************************************************************************

   CExplorerBar::RegisterAndCreateWindow()

**************************************************************************/

BOOL CExplorerBar::RegisterAndCreateWindow(void)
{
//If the window doesn't exist yet, create it now.
if(!m_hWnd)
   {
   //Can't create a child window without a parent.
   if(!m_hwndParent)
      {
      return FALSE;
      }

   //If the window class has not been registered, then do so.
   WNDCLASS wc;
   if(!GetClassInfo(g_hInst, EB_CLASS_NAME, &wc))
      {
      ZeroMemory(&wc, sizeof(wc));
      wc.style          = CS_HREDRAW | CS_VREDRAW | CS_GLOBALCLASS;
      wc.lpfnWndProc    = (WNDPROC)WndProc;
      wc.cbClsExtra     = 0;
      wc.cbWndExtra     = 0;
      wc.hInstance      = g_hInst;
      wc.hIcon          = NULL;
      wc.hCursor        = LoadCursor(NULL, IDC_ARROW);
      wc.hbrBackground  = (HBRUSH)CreateSolidBrush(RGB(0, 0, 192));
      wc.lpszMenuName   = NULL;
      wc.lpszClassName  = EB_CLASS_NAME;

      if(!RegisterClass(&wc))
         {
         //If RegisterClass fails, CreateWindow below will fail.
         }
      }

   RECT  rc;

   GetClientRect(m_hwndParent, &rc);

   //Create the window. The WndProc will set m_hWnd.
   CreateWindowEx(   0,
                     EB_CLASS_NAME,
                     NULL,
                     WS_CHILD | WS_CLIPSIBLINGS | WS_BORDER,
                     rc.left,
                     rc.top,
                     rc.right - rc.left,
                     rc.bottom - rc.top,
                     m_hwndParent,
                     NULL,
                     g_hInst,
                     (LPVOID)this);

   }

return (NULL != m_hWnd);
}

/*
*/


ExplrBar.h

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          ExplorerBar.h

   Description:   CExplorerBar definitions.

**************************************************************************/

#include <windows.h>
#include <shlobj.h>

#include "Globals.h"

#ifndef EXPLORERBAR_H
#define EXPLORERBAR_H

#define EB_CLASS_NAME (TEXT("ExplorerBarSampleClass"))

#define MIN_SIZE_X   10
#define MIN_SIZE_Y   10

/**************************************************************************

   CExplorerBar class definition

**************************************************************************/

class CExplorerBar : public IDeskBand,
                     public IInputObject,
                     public IObjectWithSite,
                     public IPersistStream
{
protected:
   DWORD m_ObjRefCount;

public:
   CExplorerBar();
   ~CExplorerBar();

   //IUnknown methods
   STDMETHODIMP QueryInterface(REFIID, LPVOID*);
   STDMETHODIMP_(DWORD) AddRef();
   STDMETHODIMP_(DWORD) Release();

   //IOleWindow methods
   STDMETHOD (GetWindow) (HWND*);
   STDMETHOD (ContextSensitiveHelp) (BOOL);

   //IDockingWindow methods
   STDMETHOD (ShowDW) (BOOL fShow);
   STDMETHOD (CloseDW) (DWORD dwReserved);
   STDMETHOD (ResizeBorderDW) (LPCRECT prcBorder, IUnknown* punkToolbarSite, BOOL fReserved);

   //IDeskBand methods
   STDMETHOD (GetBandInfo) (DWORD, DWORD, DESKBANDINFO*);

   //IInputObject methods
   STDMETHOD (UIActivateIO) (BOOL, LPMSG);
   STDMETHOD (HasFocusIO) (void);
   STDMETHOD (TranslateAcceleratorIO) (LPMSG);

   //IObjectWithSite methods
   STDMETHOD (SetSite) (IUnknown*);
   STDMETHOD (GetSite) (REFIID, LPVOID*);

   //IPersistStream methods
   STDMETHOD (GetClassID) (LPCLSID);
   STDMETHOD (IsDirty) (void);
   STDMETHOD (Load) (LPSTREAM);
   STDMETHOD (Save) (LPSTREAM, BOOL);
   STDMETHOD (GetSizeMax) (ULARGE_INTEGER*);

private:
    BOOL m_bFocus;
    HWND m_hwndParent;
    HWND m_hWnd;
    DWORD m_dwViewMode;
   DWORD m_dwBandID;
   IInputObjectSite *m_pSite;

private:
    void FocusChange(BOOL);
   LRESULT OnKillFocus(void);
    LRESULT OnSetFocus(void);
    static LRESULT CALLBACK WndProc(HWND hWnd, UINT uMessage, WPARAM wParam, LPARAM lParam);
    LRESULT OnPaint(void);
    LRESULT OnCommand(WPARAM wParam, LPARAM lParam);
   BOOL RegisterAndCreateWindow(void);
};

#endif   //EXPLORERBAR_H

/*
*/


Globals.h

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          Globals.h

**************************************************************************/

/**************************************************************************
   global variables
**************************************************************************/

extern HINSTANCE  g_hInst;
extern UINT       g_DllRefCount;

#define ARRAYSIZE(a)    (sizeof(a)/sizeof(a[0]))

/*
*/


Guid.h

/**************************************************************************
   THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF
   ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO
   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
   PARTICULAR PURPOSE.

   Copyright 1997 Microsoft Corporation.  All Rights Reserved.
**************************************************************************/

/**************************************************************************

   File:          Guid.h

   Description:   Private GUID definition.

**************************************************************************/

// {85E0B170-04FA-11d1-B7DA-00A0C90348D6}
DEFINE_GUID(CLSID_SampleDeskBand,
0x85e0b170, 0x4fa, 0x11d1, 0xb7, 0xda, 0x0, 0xa0, 0xc9, 0x3, 0x48, 0xd6);

// {85E0B171-04FA-11d1-B7DA-00A0C90348D6}
DEFINE_GUID(CLSID_SampleExplorerBar,
0x85e0b171, 0x4fa, 0x11d1, 0xb7, 0xda, 0x0, 0xa0, 0xc9, 0x3, 0x48, 0xd6);

// {85E0B172-04FA-11d1-B7DA-00A0C90348D6}
DEFINE_GUID(CLSID_SampleCommBand,
0x85e0b172, 0x4fa, 0x11d1, 0xb7, 0xda, 0x0, 0xa0, 0xc9, 0x3, 0x48, 0xd6);

/*
*/


MAKEFILE

Proj = BandObjs
dll = 1

# These are "extra" libs beyond the standard set that inetsdk.mak will
#  append to the libs set

libs=shell32.lib

# pull in the master SDK makefile that defines all of the macros
#  and all of the build rules

!include <inetsdk.mak>

# itemize all of the required Object files

Objs =   $(ObjDir)\$(Proj).Obj  \
         $(ObjDir)\ClsFact.Obj \
         $(ObjDir)\CommBand.Obj \
         $(ObjDir)\DeskBand.Obj \
         $(ObjDir)\ExplrBar.Obj

# itemize all of the required include files

Includes =  ClsFact.h \
            CommBand.h \
            DeskBand.h \
            ExplrBar.h \
            Globals.h \
            Guid.h

# add the .def file to the link flags
linkflags = $(linkflags) -def:BandObjs.def

$(ObjDir)\BandObjs.Obj  : $(@B).Cpp $(Includes)
$(ObjDir)\ClsFact.Obj   : $(@B).Cpp $(Includes)
$(ObjDir)\CommBand.Obj  : $(@B).Cpp $(Includes)
$(ObjDir)\DeskBand.Obj  : $(@B).Cpp $(Includes)
$(ObjDir)\ExplrBar.Obj  : $(@B).Cpp $(Includes)

$(ObjDir)\$(Proj).dll   : $(Objs)

All: $(ObjDir)\$(Proj).dll
   regsvr32.exe /s /c $(ObjDir)\$(Proj).dll >> $(ObjDir)\Register.Out

/*
*/


File Manager Extensions

In Microsoft® Windows®, File Manager extensions are dynamic-link libraries (DLLs) that add menus and buttons to File Manager. File Manager extensions can also display (in the status bar) Help text for the buttons. This document describes how to create and install extensions for File Manager.

About File Manager Extensions

File Manager maintains a list of extensions in an initialization file and loads the extensions when starting. An extension DLL contains an entry point that processes menu commands and notification messages sent by File Manager. Up to five extension DLLs can be installed at any one time.

Creating a File Manager Extension

A File Manager extension must reside in a DLL that includes a standard entry point, the Microsoft® Win32® FMExtensionProc callback function. The extension must include the Wfext.h header file that defines File Manager messages and structures. File Manager communicates with the extension DLL by sending the following messages to the DLL's FMExtensionProc function.
Message | Meaning
1–99 | The user selected an item from the extension-supplied menu. The value is the identifier of the selected menu item.
FMEVENT_HELPSTRING | The user selected an extension menu or a toolbar command item. File Manager wants the extension to supply a Help string.
FMEVENT_HELPMENUITEM | The user pressed F1 while selecting an extension menu or a toolbar command item. File Manager wants the extension to call WinHelp appropriately for the command item.
FMEVENT_INITMENU | The user selected the extension's menu. The extension should initialize items in the menu.
FMEVENT_LOAD | File Manager is loading the extension DLL and prompts the DLL for information about the menu that the DLL supplies.
FMEVENT_SELCHANGE | Selection in the File Manager directory window or Search Results window has changed.
FMEVENT_TOOLBARLOAD | File Manager is creating the toolbar and prompts the extension DLL for information about any buttons the DLL adds to the toolbar.
FMEVENT_UNLOAD | File Manager is unloading the extension DLL.
FMEVENT_USER_REFRESH | The user selected the Refresh command from the Window menu. The extension should update items in the menu, if necessary.

Creating the entry-point function

File Manager communicates with an extension DLL through the FMExtensionProc callback function. Make sure to export this function by listing it in the EXPORTS statement of your extension's module-definition (.def) file. The FMExtensionProc function handles the messages listed in the preceding section by performing the tasks listed below:
Task | Action
Initializing the extension (FMEVENT_LOAD) | Provides File Manager with the name and handle to the menu and saves the menu-item delta value.
Initializing the menu (FMEVENT_INITMENU) | Initializes all top-level menu items and the items in any submenus.
Initializing the toolbar (FMEVENT_TOOLBARLOAD) | Provides File Manager with information about the buttons to add to the toolbar, including the command identifier, Help string identifier, styles, and bitmap identifier.
Processing menu selections (1–99) | Carries out commands that the user chooses from the extension's menu.
Processing file selections (FMEVENT_SELCHANGE) | Queries File Manager for information about the file that the user has selected from the directory window or Search Results window.
Updating items in the menu (FMEVENT_USER_REFRESH) | Modifies the menu as appropriate when the user chooses File Manager's Refresh command from the Window menu.
Providing menu item Help strings (FMEVENT_HELPSTRING) | Provides File Manager with a Help string for a specified command in a specified menu. File Manager displays this string in the area at the bottom left of the window.
Passing menu item help requests on to WinHelp (FMEVENT_HELPMENUITEM) | Provides WinHelp with the window passed by File Manager and with menu item information.
Quitting the extension DLL (FMEVENT_UNLOAD) | Frees any memory allocated and prepares to exit.

The FMExtensionProc function is defined as follows:

LONG WINAPI FMExtensionProc(hwnd, wMsg, lParam)
    HWND hwnd;
    WORD wMsg;
    LONG lParam;

The hwnd parameter identifies the File Manager window. An extension should use this window handle to specify the parent window for any dialog box or message box it must display. It should also use this handle to send query messages to File Manager. The wMsg parameter contains one of the File Manager messages listed previously. The lParam parameter contains a message-specific value. The return value from the FMExtensionProc function depends on the value of the wMsg parameter.

The menu added to File Manager may be a hierarchical (cascaded) menu and may contain grayed, disabled, or checked menu items in addition to command items. Menu items should be text only; owner-drawn menus and bitmap menus are not supported. Changing the bitmap for check marks is not supported.

Whenever File Manager calls the FMExtensionProc function, it waits to refresh its directory windows (for changes in the file system) until after the function returns. This allows the extension to perform large numbers of file operations without excessive repainting on the part of File Manager. It is not necessary for the extension to send the FM_REFRESH_WINDOWS message to notify File Manager to repaint its directory windows.

Loading the extension

To begin loading the extension, File Manager first sends the FMEVENT_LOAD message to the FMExtensionProc function. The lParam parameter accompanying the FMEVENT_LOAD message points to an FMS_LOAD structure that File Manager uses to obtain information about the extension-supplied menu, including the menu name and menu handle.

File Manager also uses the FMS_LOAD structure to pass the menu-item delta value to the extension. To avoid conflicts with its own menu-item identifiers, File Manager renumbers the menu-item identifiers in an extension-supplied menu by adding the delta value to each identifier. An extension DLL that must modify its menu after File Manager has loaded it must use the delta value. For example, to delete a menu item, the extension DLL finds the sum of the delta value and the menu-item identifier and passes the sum as the idItem parameter to the DeleteMenu function.

If an extension returns FALSE in response to the FMEVENT_LOAD message, File Manager calls the FreeLibrary function and ends any communication with the extension DLL. This is the only place where an extension can notify File Manager of initialization problems and thus prevent the extension from being loaded.

Adding custom buttons

A File Manager extension can add custom buttons to the File Manager toolbar by returning button information in response to the FMEVENT_TOOLBARLOAD message. File Manager sends this message to the FMExtensionProc function of the extension only if the extension successfully installed a custom menu during the processing of the FMEVENT_LOAD message. Use custom buttons as accelerator keys for menu commands specified in the custom menu.

When FMExtensionProc receives the FMEVENT_TOOLBARLOAD message, the lParam parameter points to an FMS_TOOLBARLOAD structure. The File Manager extension must copy information about the custom buttons to the structure, including the number of buttons and a specifier for the bitmap containing the button images (either the identifier for a bitmap resource or a handle to a memory bitmap). The extension must also include the address of an array of EXT_BUTTON structures, each of which must contain a command identifier for the corresponding button. If the button is an accelerator for a menu command, the button identifier and corresponding menu-command identifier must be equal.

The bitmap containing the button images must be a bitmap resource or a memory bitmap. The extension must copy either the resource identifier or the memory bitmap's handle to the FMS_TOOLBARLOAD structure. In the case of a bitmap resource, the resource must be in the extension's executable file.

The bitmap must contain one image for each specified button. The bitmap height is always 15 pixels. The width is always a multiple of 16 pixels because each button image must be 16 pixels wide. Button images are concatenated from left to right. For example, the image of the first button specified in the array of EXT_BUTTON structures must be the leftmost image in the bitmap.

An extension can provide a line of Help text for a button by specifying the identifier of a string resource in the idsHelp member of the EXT_BUTTON structure. When the user selects the button, File Manager retrieves the string resource and displays it on the toolbar.

Processing menu selections

The menu resource that you define for your extension's menu must use menu-item identifiers in the range of 1 through 99. When the user selects an item, the extension receives a command notification that is the identifier of the selected item as defined in the resource definition file (which has the .rc file name extension). The command notification is not the sum of the delta value and the identifier. An extension DLL's FMExtensionProc function carries out commands by processing command notifications.

Initializing the extension menu

When the user selects the extension's main menu item from File Manager's menu bar, File Manager sends the FMEVENT_INITMENU message to the extension DLL. An extension can use this message to initialize its menu items. For example, an extension can add check marks, disable items, or gray items during this message. The extension must initialize all menu items, including those in any submenus, because File Manager will not send the FMEVENT_INITMENU message for submenus within the extension's menu.

Updating the extension menu

When the user chooses the Refresh command from the Window menu, File Manager sends an FMEVENT_USER_REFRESH message to an extension DLL. The extension can use this opportunity to update its menu items.

Processing file selections

When the user selects a file name in the directory window or in the Search Results window, File Manager sends the FMEVENT_SELCHANGE message to an extension DLL. The extension can use this opportunity to send a query message to File Manager to obtain more information about the user's selection.

Because the user can change the selection often, the extension should return promptly after processing the FMEVENT_SELCHANGE message to avoid slowing the user's selection process.

Quitting the extension dynamic-link library

When File Manager quits, it sends the FMEVENT_UNLOAD message to each extension DLL and then calls the FreeLibrary function to free the DLLs. Each DLL should free any memory that it has allocated.

Installing Extensions

File Manager installs extensions that have settings in the [AddOns] section of the Winfile.ini initialization file. Each setting contains an entry and a value. An entry consists of a string that represents the name of an extension. The value assigned to the entry consists of a string that specifies the path to the extension DLL. An application can use the WritePrivateProfileString function to add a setting to Winfile.ini. The following example shows a setting in Winfile.ini.

[AddOns]
MyExtension=C:\NT\SYSTEM\MYEXT.DLL

File Manager does not display an error message if it cannot find an extension DLL, so an extension DLL can be deleted in order to uninstall it. Even so, an application that installs an extension DLL should provide an uninstall option to remove the extension's setting from the Winfile.ini file.

Extension Messages

An extension can send the following window messages to retrieve relevant information from File Manager. File Manager is guaranteed to respond correctly only to messages sent from the extension's FMExtensionProc function.
Message | Description
FM_GETDRIVEINFO | File Manager returns drive information from the active window. An extension provides a pointer to an FMS_GETDRIVEINFO structure; File Manager fills the structure with drive information.
FM_GETFILESEL | File Manager returns information about a selected file from the active File Manager window (either the directory window or the Search Results window). An extension provides a pointer to an FMS_GETFILESEL structure; File Manager fills the structure with file information.
FM_GETFILESELLFN | Same as the FM_GETFILESEL message except that the selected file may have a long file name.
FM_GETFOCUS | File Manager returns a value that identifies the type of window with input focus.
FM_GETSELCOUNT | File Manager returns the count of selected files in the directory and Search Results windows.
FM_GETSELCOUNTLFN | Same as the FM_GETSELCOUNT message except that the count includes files with long file names.
FM_REFRESH_WINDOWS | File Manager repaints either its active window or all of its windows. This message is similar to File Manager's Refresh command on the Window menu.
FM_RELOAD_EXTENSIONS | File Manager reloads all extensions. First, File Manager unloads all extensions, sending an FMEVENT_UNLOAD message to each extension. Then it reloads the extensions, sending an FMEVENT_LOAD message to each extension. The FM_RELOAD_EXTENSIONS message allows an extension to uninstall itself by removing its setting from the Winfile.ini file; this action causes File Manager to reload the remaining extensions. Other applications and programs (for example, installation programs) can also post this message by calling the PostMessage function.

Processing Commands and Messages from File Manager

The following code example shows the FMExtensionProc function for a sample extension DLL. It demonstrates how an extension processes the menu commands and notification messages sent by File Manager.

HINSTANCE hinst;
HMENU hmenu;
WORD wMenuDelta;
BOOL fMultiple = FALSE;
BOOL fLFN = FALSE;

LONG WINAPI FMExtensionProc(hwnd, wMsg, lParam)
HWND hwnd;
WORD wMsg;
LONG lParam;

{
    CHAR szBuf[200];
    INT count;

    switch (wMsg) {
    case FMEVENT_LOAD:

       #define lpload  ((LPFMS_LOAD) lParam)

       /* Save the menu-item delta value. */

       wMenuDelta = lpload->wMenuDelta;

       /* Fill the FMS_LOAD structure. */

       lpload->dwSize = sizeof(FMS_LOAD);
       lstrcpy(lpload->szMenuName, "&Extension");

       /* Return the handle to the menu. */

       hinst = GetModuleHandle("ext.dll");
       lpload->hMenu = GetSubMenu(LoadMenu(hinst,
       MAKEINTRESOURCE(MYMENU)), 0);

       return (LONG)TRUE;

   case FMEVENT_UNLOAD:

       /* Perform any cleanup procedures here. */

       break;

   case FMEVENT_INITMENU:

       /* Copy the menu handle. */

       hmenu = (HMENU) lParam;

       /*
             * Add check marks to menu items as appropriate.
             * Add menu-item delta values to menu-item
             * identifiers to specify the menu items to check.
        */

       CheckMenuItem(hmenu,
               wMenuDelta + IDM_MULTIPLE,
               fMultiple ? MF_BYCOMMAND | MF_CHECKED :
                       MF_BYCOMMAND | MF_UNCHECKED);
       CheckMenuItem(hmenu,
               wMenuDelta + IDM_LFN,
               fLFN ? MF_BYCOMMAND | MF_CHECKED :
                       MF_BYCOMMAND | MF_UNCHECKED);
       break;

   case FMEVENT_TOOLBARLOAD:
   {
       static EXT_BUTTON extbtn[ ] = {
          {1, 0, 0},
       };

            /* Fill the FMS_TOOLBARLOAD structure. */

       #define lptbld ((LPFMS_TOOLBARLOAD) lParam)

       lptbld->dwSize = sizeof(FMS_TOOLBARLOAD);
       lptbld->lpButtons = (LPEXT_BUTTON) &extbtn;
       lptbld->cButtons = 1;
       lptbld->cBitmaps = 1;
       lptbld->idBitmap = ID_BUTTONBITMAP;

       return (LONG)TRUE;

   }

   case FMEVENT_USER_REFRESH:
            MessageBox(hwnd, "User refresh event",
                "Hey!", MB_OK);
       break;

   case FMEVENT_SELCHANGE:
       break;

        /*
         * The following messages are generated when the user
         * chooses items from the extension menu.
         */

   case FMEVENT_HELPSTRING:

       #define lphs ((LPFMS_HELPSTRING)lParam)

       if (lphs->idCommand == -1)
          lstrcpy(lphs->szHelp, "Help for extension menu");
       else
          wsprintf(lphs->szHelp, "Help for item %d", lphs->idCommand);

       break;

   case FMEVENT_HELPMENUITEM:

       wsprintf(szBuf, "Help for %d", lParam);
       MessageBox(hwnd, szBuf, "WinHelp call", MB_OK);

       /*
        * Use: WinHelp(hwnd, "ExtHelp.hlp", HELP_CONTEXT, lParam);
        */

       break;

   case IDM_GETFOCUS:
       wsprintf(szBuf, "Focus %d",
               (INT) SendMessage(hwnd, FM_GETFOCUS, 0, 0));
       MessageBox(hwnd, szBuf, "Focus", MB_OK);
       break;

   case IDM_GETCOUNT:
       count = (INT) SendMessage(hwnd,
                fLFN ? FM_GETSELCOUNTLFN : FM_GETSELCOUNT,
                0, 0);

       wsprintf(szBuf, "%d files selected", count);
       MessageBox(hwnd, szBuf, "Selection Count", MB_OK);
       break;

   case IDM_GETFILE:
   {
       FMS_GETFILESEL file;

       count = (INT) SendMessage(hwnd,
               fLFN ? FM_GETSELCOUNTLFN : FM_GETSELCOUNT,
               FMFOCUS_DIR,
               0);

       while (count >= 1) {
                /*
                 * Selection indices are zero-based (0 is
                 * first).
                 */

      count--;
      SendMessage(hwnd, FM_GETFILESEL, count,
          (LONG) (LPFMS_GETFILESEL) &file);
      wsprintf(szBuf, "file %s\nSize %ld",
          (LPSTR) file.szName, file.dwSize);
                MessageBox(hwnd, szBuf, "File Information",
                    MB_OK);

      if (!fMultiple)
         break;
       }
       break;
   }

   case IDM_GETDRIVE:
   {
       FMS_GETDRIVEINFO drive;

       SendMessage(hwnd, FM_GETDRIVEINFO, 0,
       (LONG) (LPFMS_GETDRIVEINFO)&drive);
       wsprintf(szBuf,
                "%s\nFree %ld\nTotal %ld\nVolume %s\nShare %s",
       (LPSTR) drive.szPath, drive.dwFreeSpace,
       drive.dwTotalSpace, (LPSTR) drive.szVolume,
       (LPSTR) drive.szShare);
       MessageBox(hwnd, szBuf, "Drive Info", MB_OK);
       break;
   }

   case IDM_LFN:
       MessageBox(hwnd, "IDM_LFN", "Hi", MB_OK);
       fLFN = !fLFN;
       break;

   case IDM_MULTIPLE:
       MessageBox(hwnd, "IDM_MULTIPLE", "Hi", MB_OK);
       fMultiple = !fMultiple;
       break;

   case IDM_REFRESH:
   case IDM_REFRESHALL:
       SendMessage(hwnd, FM_REFRESH_WINDOWS,
       wMsg == IDM_REFRESHALL, 0);
       break;

   case IDM_RELOAD:
       PostMessage(hwnd, FM_RELOAD_EXTENSIONS, 0, 0);
       break;
    }
    return 0L;
}

Adding the Undelete Command

File Manager supports a hook for adding an Undelete command to the File menu. If an undelete dynamic-link library is specified in the Winfile.ini file, File Manager adds the Undelete command to the File menu when starting. When the user chooses the Undelete command, File Manager calls the DLL.

The [settings] section of the Winfile.ini file should include a reference to the undelete DLL, as follows:

[settings]
UNDELETE.DLL=C:\MYDIR\OTHER.DLL

An undelete DLL must include a standard entry point, the UndeleteFile function. This function must be exported by specifying the name of the function in the EXPORTS statement of the DLL's module-definition (.def) file.

The UndeleteFile function is defined as follows:

DWORD APIENTRY UndeleteFile(hwndParent, lpszDir)
    HWND hwndParent;
    LPSTR lpszDir;

The hwndParent parameter identifies the parent window for any dialog boxes the DLL creates. The lpszDir parameter specifies the initial directory to be used (for example, C:\TEMP).


File Parsers

A file parser is a dynamic-link library (DLL) that provides the low-level parsing needed to generate a quick view for a file of a given type.

  • About File Parsers
  • File Parser Constants

About File Parsers

File parsers work in conjunction with the file viewing components of the Microsoft® Windows® operating system. These components are the Shell, the Quick View program (Quikview.exe), and display engines. When the user wants to generate a quick view for a file, the Shell responds by calling the Quick View program. The program manages the process, directing one of the display engines to draw the Quick View window and fill it with a view of the file. The display engine uses a file parser to determine the contents of the file and to draw those contents correctly.

You can extend the file viewing capabilities of Windows by supplying additional file parsers. Each file parser is responsible for a specific type or class of file and is associated with one of the display engines. For example, you can allow a quick view to be generated for a .doc file by creating a file parser to support that file type and associating the file parser with the word processor display engine.

This overview describes the file parser interface and explains how to write file parsers for word processing documents, spreadsheets, databases, bitmapped graphics, and vector graphics. For information about extending the file viewing capabilities in other ways, see File Viewers.

The file viewing technology used in the Quick View feature system has been jointly developed by Microsoft Corporation and Systems Compatibility Corporation.

Adding or Removing File Parsers

For performance reasons, the file viewer builds a cache of the file parsers in the system the first time the Quick View feature is used. This cache is stored in the registry. If a file parser is added or removed, this cache must be rebuilt. To make the system rebuild the cache, set the "verify data" value under the following key to something other than zero:

\\HKEY_LOCAL_MACHINE\SOFTWARE\SCC\Viewer Technology\MS1

Implementing a File Parser

Every file parser must implement the following functions from the Microsoft Platform SDK:
VwStreamCloseFunc | VwStreamSectionFunc
VwStreamOpenFunc | VwStreamSeekFunc
VwStreamReadFunc | VwStreamTellFunc
VwStreamReadRecordFunc |

The display engine calls these functions to display a file of the type supported by the file parser.

The display engine starts the file viewing process by calling VwStreamOpenFunc, sending the name of a file to the file parser. The first responsibility of any parser is to verify that the given file has the proper format and can be processed. If the file is viewable, the file parser returns a value to the display engine acknowledging the request.

Once the parser completes verification, the display engine calls VwStreamSectionFunc, directing the file parser to identify the type and name of the first section of the file to be processed. A section is a portion of the file in which all the data is of one type; it forms a logical breaking point for the processing of the file. The standard section types are word processing, spreadsheet, database, bitmapped graphics, and vector graphics. A file can consist of a single section, multiple sections of the same type, or a combination of sections of different types. The actions that the display engine takes to display the file depend on the type of section currently being processed. The file parser must call the SOPutSectionType and SOPutSectionName functions to output the section type and to set the section name.

Before the file parser returns from VwStreamSectionFunc, it may need to provide the display engine with additional information. If the portion to be processed is a word processing section, the file parser must set entries for the font table by using the SOPutFontTableEntry function. If it is a spreadsheet section, the file parser must set the column width by calling the SOPutColumnInfo function. If it is a database section, the file parser must set the field format by calling the SOPutFieldInfo function. The file parser can also set the date base used by spreadsheets and databases to calculate dates by using the SOSetDateBase function. In addition, the file parser can set header entries by calling the SOPutHdrEntry function.

After the section type and general information are set, the display engine requests data for the section by calling VwStreamReadFunc. The file parser fulfills this request by calling the stream output functions. These functions pass the data to the display engine in a form that is easiest for the engine to display, copy to the clipboard, or write to disk.

The stream output functions used by the file parser depend on the section type. For word processing sections, the file parser uses the SOPutParaSpacing, SOPutCharAttr, and SOPutChar functions to set the spacing for paragraphs, set the style attributes for characters, and output characters, respectively. For spreadsheet sections, the parser uses the SOPutDataCell and SOPutTextCell functions to output the content (data or text) of cells. For database sections, it uses the SOPutField and SOPutVarField functions to output the data of fields. The parser uses the SOPutBitmapHeader and SOPutScanLineData functions for bitmapped graphics sections and the SOVectorAttr and SOVectorObject functions for vector graphics sections.

To set a break for a paragraph, cell, or field, the file parser calls the SOPutBreak function with an appropriate value, either SO_PARABREAK, SO_CELLBREAK, or SO_RECORDBREAK. The return value from SOPutBreak tells the file parser how to proceed. If it is the SO_STOP value, the file parser stops all processing and returns from VwStreamReadFunc.

The file parser continues to output data until it reaches the end of the section. The parser must end a section by calling SOPutBreak with the SO_SECTIONBREAK value. If this is the last section in the file, the file parser indicates that the end of the file has been reached by using the SO_EOFBREAK value instead.

If there are subsequent sections in the file, the display engine calls VwStreamSectionFunc again to request the type and name of the next section, and processing continues just as it did for the first section.

After the last section, the display engine calls VwStreamCloseFunc to indicate that processing is complete and that no further requests for data will be made. The file parser must close the file and any related files it has opened and clean up resources, such as freeing memory.

If an error occurs while a file is parsed, the file parser should call the SOBailOut function to notify the display engine of the error condition. The parser must immediately return from VwStreamReadFunc after calling the SOBailOut function.

Restartable Parsing

You must design the file parser so that parsing can be efficiently restarted at discrete locations within a file. The goal is to give the display engine the best performance without it having to store a completely converted copy of a file.

To facilitate restartable parsing, the display engine incorporates a module, which is called the chunker, that essentially caches data from the parser. The chunker does not cache all the data—only the data that the display engine has most recently requested. However, it does cache state data for restartable locations in the file. This means that as long as the parser maintains its own internal data in a way that can be efficiently restarted, the display engine and the parser can work cooperatively to locate and restart processing at the cached locations.

The file parser is responsible for determining the best locations for restarting parsing. It does this by calling the SOPutBreak function. The chunker assumes that each break is a restartable location in the file. Before calling SOPutBreak, however, the file parser must save up-to-date data about the location so that it can quickly retrieve and begin processing the data at the location if requested to do so.

The display engine uses the VwStreamSeekFunc and VwStreamTellFunc functions to direct the file parser to a restartable location.

Word Processing Sections

Word processing sections contain text organized as paragraphs, tables, and subdocuments. Of these, paragraphs and tables can have attributes, such as indentation, tab stops, and spacing. The text in word processing sections consists of characters having attributes, such as font, height, and weight. Word processing sections can also include embedded objects, allowing bitmapped art and other graphics to be included with the text.

A file parser processes the text associated with a word processing section when the display engine calls the VwStreamReadFunc function. The file parser must set all attributes before calling the SOPutChar function or other text output functions. The file parser must never automatically set an attribute as a default. If the state of a current attribute is not known, the file parser must not set it.

Paragraph attributes

The file parser sets the attributes of a paragraph before outputting characters for the paragraph. The attributes are the alignment, indentation, spacing, tab stops, and margins.

The file parser sets the alignment to be left, right, centered, or justified by using the SOPutParaAlign function and sets the left, right, and first line indents by using the SOPutParaIndents function. The file parser sets the spacing before and after the paragraph and between lines of the paragraph by using the SOPutParaSpacing function. The file parser sets tab stops by using the SOPutTabStop function, calling the function once for each tab stop. To mark the start and end of a tab stop definition, the file parser calls the SOStartTabStops and SOEndTabStops functions. The file parser sets page margins for the paragraph by using the SOPutParaMargins function.

Tables

The file parser can add tables to a word processing section's text by using the SOBeginTable and SOEndTable functions to mark the start and end of the table definition. It can format the rows and cells in tables by using the SOPutTableRowFormat and SOPutTableCellInfo functions. The file parser uses the character and paragraph functions to output the text for each cell and set the attributes.

The file parser marks the end of each cell and each row by using the SOPutBreak function with the SO_TABLECELLBREAK and SO_TABLEROWBREAK values. A file parser must insert a cell break after each cell and a row break at the end of each row. If a file parser inserts a row break before inserting as many cells as were defined for the row, the remaining cells are assumed to be empty. Empty cells may be inserted in the middle of a row by inserting consecutive cell breaks.

Row and cell formats must be defined before the last cell of a row. After defining the row properties by using the SOPutTableRowFormat function, the parser must call the SOPutTableCellInfo function for each cell in the row. After a row is defined, the row properties are assumed to apply to subsequent rows until new row properties are specified. Thus, a filter can define an entire table by specifying the row and cell properties once and then using the appropriate row and cell breaks.

You can add borders to cells by setting the pLeftBorder, pRightBorder, pTopBorder, and pBottomBorder members of the SOTABLECELLINFO structure to appropriate values when setting the cell format.

You can add tabs to cells by using the special character, the SO_CHCELLTAB value. This character is defined for cells that are merged with their neighbors and acts as a tab that moves the current text position to the location of the next boundary that would have existed if the cells had not been merged.

Subdocuments

The file parser can add subdocuments to the document. Subdocuments consist of headers, footers, footnotes, and comments. Subdocuments are added to the document using the SOPutBreak function. To start a subdocument, the file parser calls SOPutBreak with the SO_SUBDOCBEGINBREAK value. To end the subdocument, the file parser calls SOPutBreak with the SO_SUBDOCENDBREAK value.

After ending a subdocument, the file parser must restore character and paragraph attributes to what they were before the subdocument was started. The file parser can use the SUUserPushData and SUUserPopData functions to save and restore nested subdocument information. A parser can nest subdocuments without limit. The following example shows when to save and restore this information.

This is a <Bold On> test

    // At this point, the filter should save its internal
    // information to reflect the fact that bold is on.
    SOPutBreak(SO_SUBDOCBEGINBREAK);
    SOPutSubdocInfo(...);
<Subdoc Begin> This is a <Bold Off>subdocument<Subdoc End>

    // At this point, the filter should restore its internal
    // information to reflect the fact that bold is on.
    SOPutBreak(SO_SUBDOCENDBREAK);

document <Bold Off>of mine.

File parsers are not expected to correctly exit a subdocument when run from a regular paragraph break (with the SO_PARABREAK value) inside the subdocument. The display engine lets the file parser run to the subdocument's end break (that is, the SO_SUBDOCENDBREAK value) and returns the SO_STOP value.

Characters and character attributes

The file parser outputs characters by using the SOPutChar function. It can specify extra properties for a character, such as grouped or hidden, when outputting by using the SOPutCharX function. The file parser outputs special characters, such as tabs, hard line breaks, hard page breaks, and hyphens by using the SOPutSpecialCharX function.

Before outputting characters, the file parser sets character attributes by using the SOPutCharAttr, SOPutCharFontById, SOPutCharFontByName, and SOPutCharHeight functions. These functions set the style, font, height, and width of the character. The SOPutCharAttr function lets the file parser set style attributes, such as italic, underline, and strikeout. The SOPutCharFontById and SOPutCharFontByName functions can specify any font that the parser added to the font table during processing of the VwStreamSectionFunc function. The SOPutCharHeight function sets the character height, in half points.

Embedded graphics objects

The file parser can embed graphics objects in the text of a paragraph section by using the SOPutEmbeddedObject function. The function inserts the embedded graphics object at the current location in the document.

Spreadsheet Sections

The file parser outputs content (data or text) for cells in a spreadsheet by using the SOPutDataCell and SOPutTextCell functions. Before outputting cell data, the file parser must retrieve the range of columns to be output by using the SOGetInfo function with the SOINFO_COLUMNRANGE value. When SOGetInfo returns, the low-order word of its pInfo parameter identifies the first column of data to generate output for, and the high-order word identifies the last column. The file parser should only call SOPutDataCell or SOPutTextCell for cells within the range indicated by a call to SOGetInfo. When there is no more data within a range of columns, the file parser must call the SOPutBreak function with either the SO_EOFBREAK or SO_SECTIONBREAK value, whichever applies. This must be done for each range of columns in the document.

For example, if the first column is 10 and the last column is 19, the filter reads the file from its current position, but it only calls SOPutDataCell or SOPutTextCell for cells that belong in columns 10 through 19, inclusively. (Column numbers are zero-based.) The parser skips over cells that belong in columns outside of this range. The filter must produce cells for all columns in the range, filling in with empty cells if necessary. As before, the filter continues until SOPutBreak returns the SO_STOP value.

In general, the file parser should carry out the following steps:

  1. Determine the desired range of columns.
  2. Determine the next cell available from the input file.
  3. Determine if the cell is in the given range of columns. If not, repeat step 2.
  4. If the cell is not empty, call SOPutDataCell or SOPutTextCell with the current data. Otherwise, call SOPutDataCell for a cell of the SO_CELLEMPTY type.
  5. Update local variables, such as row and column numbers.
  6. Call SOPutBreak with the SO_CELLBREAK value.
  7. If SOPutBreak returns the SO_STOP value, return from the VwStreamReadFunc function.
  8. If at the beginning of the next section, call SOPutBreak with the SO_SECTIONBREAK value and return.
  9. If at the end of the file, call SOPutBreak with the SO_EOFBREAK value and return.
  10. Repeat steps 2 through 10.

When the chunker saves local data for various seek positions in a document, it does so within SOPutBreak when the break is of the SO_CELLBREAK type. So when a file parser has its local data restored for a random seek position, the data will reflect the state of the file parser during its call to SOPutBreak for the last cell of the previous chunk in the current range of cells. Any tracking done by the parser, such as the current row number, should be updated before SOPutBreak is called for each cell.

Every horizontal range of columns, specified by the dwExtraData parameter in each call to your VwStreamReadFunc function, must eventually be terminated by a call to SOPutBreak with the SO_EOFBREAK or SO_SECTIONBREAK value, whichever is applicable. The type of break depends on the input file. A file parser must not put a section break at the end of the file, and an end-of-file (EOF) break, of course, cannot occur anywhere but at the actual end of the file.

For example, if the input document contains a single spreadsheet that is 30 columns wide, the display engine can call the parser with three different ranges of columns: 0 to 11, 12 to 23, and 24 to 29. The file parser calls SOPutBreak with an EOF break three times, once for each time it reaches the end of the file while processing a given range.

When calling SOPutBreak with a section break, the file parser must be sure that the seek position is at the beginning of the next section. This ensures that the file position is where the file parser needs to be when VwStreamSectionFunc is next called. Any one of the calls to SOPutBreak for a section break may be the one that sets the seek position for the top of the next section.

Database Sections

The file parser outputs data and text for a database by using the SOPutField, SOPutMoreVarField, and SOPutVarField functions. The parser uses the SOPutField function for fields of a fixed size. The other functions are used for variable length fields. The parser sets field information by using the SOPutFieldInfo function while processing the VwStreamSectionFunc function.

Bitmapped Sections

The file parser starts a bitmapped section by calling the SOPutSectionType function with the SO_BITMAP value while processing the VwStreamSectionFunc function. The file parser must also set the bitmap header information for the section by using the SOPutBitmapHeader function before returning from VwStreamSectionFunc. The information in the bitmap header allows the chunker to allocate storage for other bitmap information, such as the palette. This means that the file parser must call SOPutBitmapHeader before any other bitmapped section functions.

Section palettes

The file parser must generate a palette for those sections that have the SO_COLORPALETTE value set in the wImageFlags member of the SOBITMAPHEADER structure. The parser uses the SOStartPalette, SOPutPaletteEntry, and SOEndPalette functions to define the color palette for a bitmapped section. Only one palette may be defined for a bitmapped section.

All members set during the stream read can use RGB values, palette index values, or palette-relative RGB values. These values must be set through the SOPALETTEINDEX, SORGB, or SOPALETTERGB macro. For more information about these types of color values, see the description of the COLORREF value.

Tiles and scan lines

A bitmap image in a bitmapped section consists of tiles and scan lines. A tile is a rectangular portion of an image, containing at least one scan line. An image is one or more tiles wide and one or more tiles long. A tile column is the horizontal positioning of a tile; the tiles that have their x-coordinate equal to zero belong to tile column zero, with tile column numbers incrementing in the direction of the increasing x-coordinates.

The file parser specifies its tile length in terms of scan lines. Once the length is specified, the display engine always requests bitmap data as whole tiles; that is, it tells the parser to stop only on integer multiples of the tile length. For formats that contain multiple tiles, file parsers should set the tile length to the minimum number of scan lines required for a single tile. Formats that are not stored in tiles should have the tile width set equal to the image width and the tile length set to one scan line.

The following values are expected to be valid when tiles are created.

TILESACROSS = (ImageWidth+TileWidth-1)/TileWidth
TILESDOWN = (ImageLength+TileLength-1)/TileLength
TILESPERIMAGE=TILESACROSS*TILESDOWN

To output bitmap data, the file parser outputs a scan line at a time, in sequential order, by using the SOPutScanLineData function. All of the scan lines must belong to the same tile column. After each scan line, the file parser calls the SOPutBreak function with the SO_SCANLINEBREAK value. As is normally the case, the return value from SOPutBreak indicates whether the file parser should return from the VwStreamReadFunc function.

Building scan lines

The file parser builds the scan line data as a continuous stream of bits that define each pixel. Each pixel is packed into an array of bytes in such a way that if the data were written out in hexadecimal or binary numbers, the pixels could be read in order from left to right. For example, in a 4-bit-per-pixel format, the first pixel is stored in the high-order bits of the first byte (bit 7, bit 6, bit 5, and bit 4), and the second pixel is stored in low-order bits of that byte (bit 3, bit 2, bit 1, and bit 0). So if the first eight pixels of a 4-bit-per-pixel scan line have the hexadecimal values of 0, 2, C, 9, A, 4, 3, and F, the first four bytes of scan line data would be 02, C9, A4, and 3F.

If the parser provides a palette for the image, the data for each pixel is interpreted as an index into the palette. If no palette exists for the image, the bits for each pixel specify either a true color (24-bit only) or a gray scale value. For 24-bit color, each 3 bytes of a scan line represent the intensities of red, green, and blue of a single pixel.

When the scan line has been completely specified, the parser must call SOPutBreak with the SO_SCANLINEBREAK value, except for the last line of the bitmap. The last line of the bitmap must end with a break of the SO_SECTIONBREAK or SO_EOFBREAK type, whichever applies.

The following example illustrates the use of the bitmapped functions in the simplest possible case. In this case, the parser has scan line data stored one tile wide. The scan line data is already in the format that the parser is required to provide it in, so the data requires no additional processing after being read in. This example also does not check for EOF or read errors.

WORD  wBytesRead;
WORD  wBufSize = Proc.ScanLineBufSize;

do
{
...

xread( hFile, Proc.ScanLineBuf, wBufSize, &wBytesRead );

SOPutScanLineData( Proc.ScanLineBuf, hProc );

...

} while( SOPutBreak( SO_SCANLINEBREAK, 0, hProc ) == SO_CONTINUE );

Vector Graphics Sections

The file parser starts a vector graphics section by calling the SOPutSectionType function with the SO_VECTOR value while processing the VwStreamSectionFunc function. The file parser must also set the vector header by using the SOPutVectorHeader function before returning from VwStreamSectionFunc. The information in the SOVECTORHEADER structure defines the size and attributes of the rectangle in which vector graphics are drawn.

The vector graphics functions are similar to the primitive graphic device interface (GDI) functions, but they include extensions based on the file formats being supported. All vector graphics objects are described in two-dimensional space on a logical coordinate system. The direction and resolution of the x- and y-axes are defined in SOVECTORHEADER.

The file parser uses two functions to transfer data. The SOVectorAttr function sets attributes related to drawing vector graphics objects, and the SOVectorObject function defines a vector graphics object to be drawn. The parser specifies an identifier, a data size, and the address of data when it calls a function. The identifier specifies the action to take and the size and data-defined details of the action. Each action has a corresponding structure in which the data must be given. For example, to define a logical font, the parser must set the members of the SOLOGFONT structure and pass the structure to SOVectorAttr.

Although vector graphics functions are similar to the GDI functions, they are not exactly the same. For example, the members of the SOLOGFONT and LOGFONT structures are not necessarily the same.

The file parser should call the SOPutBreak function with the SO_VECTOROBJECTBREAK value after drawing every object.

Writing a File Parser

File parsers should be contained in a set of source and include files as follows, where XXX represents a mnemonic for the data format. For specific examples, see the sample ASCII filter files identified in the following table:
Generic file name | Contents | Sample ASCII filter file
VS_XXX.C | Code | VS_ASC.C
VSD_XXX.C | Data | VSD_ASC.C
VS_XXX.H | Type definitions | VS_ASC.H
VSP_XXX.H | Portability information | VSP_ASC.H

The portability information file makes porting of filters platforms easier. A set of include files is provided that will allow conditional compilations to yield executable DLLs for all of these needs from the same set of source files.

Your VSP_XXX.H file should look something like the following. (For further information, see the corresponding ASCII filter file.)

  • The structure type and name of the static data.
    #define VwStreamStaticType  ???
#define VwStreamStaticName  ???

The parser must not change the contents of the structure because it is shared among all instances of the parser.

  • The structure type and name of the dynamic data.
    #define VwStreamDynamicType  ???
#define VwStreamDynamicName  ???

VwStreamDynamicName is for consistency and has no real use because all dynamic data is accessed through the function pseudonym. Each instance of the parser has a separate copy of dynamic data.

  • The structure type and name of the save data.
    #define VwStreamSaveType  ???
#define VwStreamSaveName  ???

VwStreamSaveName should reference an element in the VwStreamDynamicType structure. The data in this structure is saved after every call to VwStreamSectionFunc and VwStreamReadFunc and restored before every call to VwStreamReadFunc.

  • The structure type and name of the section data.
    #define VwStreamSectionType  ???
#define VwStreamSectionName  ???

If neither of these is defined, the file parser is assumed to be a single section only. VwStreamSectionName should reference an element in the VwStreamDynamicType structure. The data in this structure is saved after each call to VwStreamSectionFunc and is guaranteed to contain the current section's data on entry to VwStreamReadFunc.

This example shows the relationship of the various save areas to the dynamic data structure.

typedef struct {
 ...
} VwStreamSaveType;
typedef struct {
 ...
} VwStreamSectionType;
typedef struct {
 ...
    VwStreamSectionType VwStreamSectionName; // multisection only
    VwStreamSaveType VwStreamSaveName;
} VwStreamDynamicType;
  • The stream identifier name and count.
    #define VwStreamIdName   ???
#define VwStreamIdCount   ???

VwStreamIdName is the name of the FILTER_DESC array in VSD_XXX.C, and VwStreamIdCount is the number of elements in this array. Like the static data, this data should never be changed by a parser.

  • The name of the include file. All the structure types used by the parser should be defined in this file.
    #define VwInclude              "vs_xxx.h"
#define VwStreamUserSaveType   ???
#define VwStreamGenSeekName    ???
#define VwStreamOpenFunc        xxx_stream_open
#define VwStreamSeekFunc        xxx_stream_seek
#define VwStreamTellFunc        xxx_stream_tell
#define VwStreamReadFunc        xxx_stream_read
#define VwStreamReadRecordFunc  xxx_stream_readrecord
#define VwStreamSectionFunc     xxx_stream_section
#define VwStreamCloseFunc       xxx_stream_close
#define VwGetInfoFunc           xxx_getinfo
#define VwGetRtnsFunc           xxx_getrtns
#define VwGetDataFunc           xxx_getdata
#define VwSetDataFunc           xxx_setdata
#define VwAllocProcFunc         xxx_alloc_proc
#define VwFreeProcFunc          xxx_free_proc
#define VwLocalUpFunc           xxx_local_up
#define VwLocalDownFunc         xxx_local_down
#define VwGetSectionDataFunc    xxx_getsectiondata
#define VwSetSectionDataFunc    xxx_setsectiondata
  • The top of the VS_XXX.C file should look like this.
    #include "VSP_XXX.H"
#include "VSCTOP.H"
#include "VS_XXX.PRO"


File Parser Constants

The following vector object values and vector attribute values are used with the vector graphics functions.

Vector object values

SO_ARC | Draws an arc. dwDataSize must be four times the size of the SOPOINT structure, and pData must be the address of four SOPOINT structures.
SO_ARCANGLE | Draws an arc by defining the angles of the two points on the ellipse that locate the start and end of the arc. dwDataSize must be the size of the SOARCINFO structure, and pData must be the address of a SOARCINFO structure that defines the arc.
SO_ARCANGLECLOCKWISE | Draws an arc in the clockwise direction by defining the angles of the two points on the ellipse that locate the start and end of the arc. dwDataSize must be the size of the SOARCINFO structure, and pData must be the address of a SOARCINFO structure.
SO_ARCCLOCKWISE | Draws an arc in the clockwise direction. dwDataSize must be four times the size of the SOPOINT structure, and pData must be the address of four SOPOINT structures.
SO_BEGINGROUP | Starts the definition of a group. dwDataSize must be the size of the SOGROUPINFO structure added to GroupInfo.nTransforms times the size of the SOTRANSFORM structure, and pData must be the address of a SOGROUPINFO structure followed by the number of SOTRANSFORM structures defined in the nTransforms member of the SOGROUPINFO structure. The transformations will occur to all objects in the group in the order supplied. For more information, see the SO_OBJECTTRANSFORM vector attribute value.
SO_BEGINPATH Starts the definition of a path. dwDataSize must be the size of the SOPATHINFO structure added to GroupInfo.nTransforms times the size of the SOTRANSFORM structure, and pData must be the address of a SOPATHINFO structure followed by the number of SOTRANSFORM structures defined in the nTransforms member of the SOPATHINFO structure. The transformations will occur to all objects in the path in the order supplied. For more information, see the SO_OBJECTTRANSFORM vector attribute value later in this section.

This item is used to begin the definition of a path. Paths are a collection of points connected by lines that form opened or closed objects. Multiple subpaths may be created using SO_CLOSESUBPATH while defining a path. Note that the current object and group transformations will also apply during creation of a path. This allows maximum flexibility with transforming paths. Any object can be rendered to create the path. However, due to current limitations, text objects will not be added to the path. Multiple levels of paths are also allowed.

SO_BEGINSYMBOL | Starts the definition of a symbol. A symbol is collection of vector commands that together make up a single symbol. Symbols are considered in the wrapping algorithm of frame text. dwDataSize must be the size of the SORECT structure, and pData must be the address of a SORECT structure that identifies the bounding rectangle of all commands used within the symbol.
SO_BEGINTEXTFRAME | Starts the definition of a text frame. A text frame is used in conjunction with SO_TEXTINPARA to wrap text within a frame. Text is wrapped according to the SO_PARAINDENTS vector attribute value. Symbols are included in the wrapping algorithm. dwDataSize must be the size of the SORECT structure, and pData must be the address of a SORECT structure that identifies the bounding rectangle of the text frame.
SO_CHORD | Draws a chord. dwDataSize must be four times the size of the SOPOINT structure, and pData must be the address of four SOPOINT structures.
SO_CHORDANGLE | Draws a chord by defining the angles of the two points on the ellipse that locate the start and end of the chord. dwDataSize must be the size of the SOARCINFO structure, and pData must be the address of a SOARCINFO structure that defines the chord in terms of the arc located on the chord.
SO_CLOSESUBPATH | Closes the current subpath. dwDataSize must be zero, and pData must be NULL.
SO_CPARCANGLE | Draws an arc from the current point pivoting around the center point of the specified sweep angle. dwDataSize must be the size of the SOCPARCANGLE structure, and pData must be the address of a SOCPARCANGLE structure that gives the center point of the arc and the sweep angle.
SO_CPARCTRIPLE | Draws a circle arc from the current point through the first point and ending at the second point. dwDataSize must be two times the size of the SOPOINT structure, and pData must be the address of two SOPOINT structures.
SO_CPELLIPSE | Draws an ellipse around the current point with an x- and y-radius described by the SOPOINT data. dwDataSize must be the size of the SOPOINT structure, and pData must be the address of a variable containing the x- and y-radius values.
SO_CPLINE | Draws a line from the current pen position. dwDataSize must be the size of the SOPOINT structure, and pData must be the address of a variable containing the point to draw to.
SO_CPPIEANGLE | Draws a pie with the current position as the center and with the given start and sweep angles. dwDataSize must be the size of the SOCPPIEANGLE structure, and pData must be the address of a SOCPPIEANGLE structure that gives the radius of the circle.
SO_CPRECTANGLE | Draws a rectangle starting at the current pen position. dwDataSize must be the size of SOPOINT structure, and pData must be the address of a variable containing the point to be the opposite corner of the rectangle.
SO_CPSET | Moves the current pen position to this point. dwDataSize must be the size of the SOPOINT structure, and pData must be the address of the variable containing the point.
SO_DRAWPATH | Strokes, fills, or both strokes and fills the current path with the current pen and brush. Since the group, path, and object transformations were applied when the path was created, they are not applied again. dwDataSize must be the size of a WORD, and pData must be the address of a variable containing the SODP_STROKE or SODP_FILL value, or both.
SO_ELLIPSE | Draws an ellipse. dwDataSize must be two times the size of the SOPOINT structure, and pData must be the address of two SOPOINT structures.
SO_ENDGROUP | Ends the definition of a group. dwDataSize must be zero, and pData must be NULL.
SO_ENDPATH | Ends the definition of a path. dwDataSize must be zero, and pData must be NULL.
SO_ENDPOLY | Ends drawing of a polygon. dwDataSize must be zero, and pData must be NULL.
SO_ENDSYMBOL | Ends the definition of a symbol. dwDataSize must be zero, and pData must be NULL.
SO_ENDTEXTFRAME | Ends the definition of a text frame. dwDataSize must be zero, and pData must be NULL.
SO_FLOODFILL | Fills the area with the given color. dwDataSize must be the size of the SOPOINT structure plus the size of the SOCOLORREF structure, and pData must be the address of a variable containing the coordinates of the point to start at followed by the RGB color value to use to fill the area.
SO_LINE | Draws a line from point 1 to point 2 using the current pen. dwDataSize must be two times the size of the SOPOINT structure, and pData must be the address of two SOPOINT structures.
SO_PARAEND | Ends a paragraph. dwDataSize must be zero, and pData must be NULL.
SO_PIE | Draws a pie shape. dwDataSize must be four times the size of the SOPOINT structure, and pData must be the address of four SOPOINT structures.
SO_PIEANGLE | Draws a pie by defining the angles of the two points on the ellipse that locate the start and end of the pie. dwDataSize must be the size of the SOARCINFO structure, and pData must be the address of a SOARCINFO structure that defines the pie in terms of the arc located on the pie.
SO_POINTS | Specifies vertices of a polygon. dwDataSize must be N times the size of the SOPOINT structure, and pData must be the address of consecutively stored SOPOINT structures. At most, SOMAXPOINTS can be passed in a single SO_POINTS object. Multiple SO_POINTS objects can be generated to define all of the points associated with a polygon object. The number of points defined in SO_STARTPOLY must be defined using SO_POINTS before the object is closed with SO_ENDPOLY.
SO_RECTANGLE | Draws a rectangle. dwDataSize must be two times the size of the SOPOINT structure, and pData must be the address of two SOPOINT structures.
SO_ROUNDRECT | Draws a rectangle with rounded corners. dwDataSize must be three times the size of the SOPOINT structure, and pData must be address of the three SOPOINT structures.
SO_SETPIXEL | Sets the color of a pixel. dwDataSize must be the size of the SOPOINT structure plus the size of the SOCOLORREF structure, and pData must be the address of a variable containing the pixel point followed by the RGB color value to set.
SO_STARTPOLY | Starts drawing of a polygon. dwDataSize must be the size of the SOPOLYINFO structure, and pData must be the address of a SOPOLYINFO structure.
SO_TEXTATARCANGLE | Draws text at the given location. dwDataSize must be the size of the SOTEXTATARCANGLE structure plus the length of the text string, and pData must be the address of a SOTEXTATARCANGLE structure followed by the text string.
SO_TEXTATPOINT | Draws text at the given point. dwDataSize must be the size of the SOTEXTATPOINT structure plus the length of the text string, and pData must be the address of a SOTEXTATPOINT structure followed by the text string.
SO_TEXTINPARA | Draws the text string in the current font and text attributes at the current wrap location. The wrap location is moved by the text extent. Any words that would extend beyond the right indent of the frame are wrapped. This object is only valid within a text frame. dwDataSize must be the size of an INT plus the length of the text string, and pData must be the address of an integer variable containing the size of the text string that follows.
SO_TEXTINRECT | Draws text in a rectangle. dwDataSize must be the size of the SOTEXTINRECT structure plus the length of the text string, and pData must be the address of a SOTEXTINRECT structure followed by the text string.

Vector attribute values

SO_BKCOLOR | Sets the background color used for styled lines, hatched brushes, and text when the background mode is SOBK_OPAQUE. dwDataSize must be the size of the SOCOLORREF structure, and pData must be the address of a variable containing an RGB or palette-relative color value. To set this value, use the SORGB or SOPALETTE macro.
SO_BKMODE | Sets the background mode. dwDataSize must be the size of an INT, and pData must be the address of a variable containing either the SOBK_OPAQUE or SOBK_TRANSPARENT value.
SO_CLIPMODE | Sets the clipping mode. dwDataSize must be the size of a WORD, and pData must be the address of a variable containing either the SO_DONOTCLIP or SO_CLIPTOPATH value.
SO_DRAWMODE Sets the drawing mode used when drawing the pen and interiors. dwDataSize must be the size of an INT, and pData must be the address of a variable containing one of these values:
SOR2_BLACK | SOR2_NOT
SOR2_COPYPEN | SOR2_NOTCOPYPEN
SOR2_MASKNOTPEN | SOR2_NOTMASKPEN
SOR2_MASKPEN | SOR2_NOTMERGEPEN
SOR2_MASKPENNOT | SOR2_NOTXORPEN
SOR2_MERGENOTPEN | SOR2_WHITE
SOR2_MERGEPEN | SOR2_XORPEN
SOR2_NOP
SO_OBJECTTRANSFORM | Sets object transformations. dwDataSize must be the size of an INT plus nCount times the size of the SOTRANSFORM structure, and pData must be one INT (nCount) followed by that number of SOTRANSFORM structures. The transformations will occur in the order supplied.
SO_PARAALIGN | Sets the alignment of paragraph text being built into a text frame. dwDataSize must be the size of a WORD, and pData must be the address of a 16-bit variable containing the SO_ALIGNLEFT, SO_ALIGNCENTER, SO_ALIGNRIGHT, or SO_ALIGNJUSTIFY value.
SO_PARAINDENTS | Sets the paragraph indents within a text frame, defining the first, left, and right indents of paragraph text being built into the frame. These values are only valid when within a text frame. All values are in the current coordinate system. dwDataSize must be the size of the SOPARAINDENTS structure, and pData must be the address of a SOPARAINDENTS structure.
SO_POINTRELATION | Sets the coordinate orientation. dwDataSize must be the size of an INT, and pData must be the address of a variable containing the SOPR_ABSOLUTE or SOPR_RELATIVE value.
SO_POLYFILLMODE | Sets the polygon-filling mode. dwDataSize must be the size of an INT, and pData must be the address of a variable containing either the SOPF_ALTERNATE or SOPF_WINDING value.
SO_SELECTBRUSH | Selects the given brush. dwDataSize must be the size of the SOLOGBRUSH structure, and pData must be the address of a SOLOGBRUSH structure.
SO_SELECTFONT | Selects the given font. dwDataSize must be the size of the SOLOGFONT structure, and pData must be the address of a SOLOGFONT structure.
SO_SELECTPEN | Selects the given pen. dwDataSize must be the size of the SOLOGPEN structure, and pData must be the address of a SOLOGPEN structure.
SO_TEXTCHAREXTRA | Sets the text character extra value. dwDataSize must be the size of an INT, and pData must be the address of a variable containing a value. This attribute affects text objects.
SO_TEXTCOLOR | Sets the foreground color. dwDataSize must be the size of the SOCOLORREF structure, and pData must be the address of a variable containing an RGB or a palette-relative color value. To set this value, use the SORGB or SOPALETTE macro.


File Viewers

A file viewer is an OLE COM object implemented inside a 32-bit in-process server dynamic-link library (DLL), which is associated, in turn, with the file viewer's class identifier. A file viewer provides the user interface for viewing a file. Menu items, a toolbar, and a status bar are standard parts of the file viewer interface. A file viewer can optionally add other functionality for further Shell integration.

Note: File viewers are not supported by Microsoft® Windows 2000® and later systems.

About File Viewers

The Shell allows users to browse through the information in the file system and on the network. Using the Quick View feature of the Shell, the user can view the contents of a file without running the application that created it; the application doesn't even have to be installed on the user's computer. To view the file contents, the user selects a file and chooses the Quick View command from the shortcut menu of the selection (or from the File menu). The following illustration shows the shortcut menu.

The shortcut menu.

In response to the user choosing the Quick View command, the Shell activates a file-specific viewer for the selected file. The Shell uses the extension of the file to determine which viewer to activate. A file viewer associates itself with file classes and file name extensions in the system registry.

A file viewer object, which is separate from the class factory object in the in-process server, uses the standard OLE IPersistFile interface as well as the IFileViewer interface. The Shell does not interact directly with file viewer objects. Instead, the Shell starts an instance of a small program called Quick View (Quikview.exe) for each file to be viewed. Each instance of Quick View defines a process for a file viewer, giving the viewer its own message queue. Although Quick View is a Microsoft® Windows® executable file, it is not a complete application. It associates a path with a file viewer, creates an instance of the file viewer object, and instructs the file viewer to load and display the file.

Because a file viewer is an OLE COM object, additional interfaces and functionality can be added in future versions of Windows to support new features. For example, a file viewer can act as an OLE container application and can perform in-place activation of embedded objects inside the file being viewed. A file viewer can let the user make a selection in a document and copy the selection to the clipboard or use the selection in a drag-and-drop operation. However, such functionality is entirely up to the developer of the file viewer. This overview describes the basic functionality that a file viewer must provide and discusses user interface guidelines that all developers of file viewers should follow.

Adding or Replacing File Viewers

The file viewer interfaces allow you to add file viewers to Windows. For example, you may need to add a file viewer that supports a new file format or provides additional functionality. To understand how to add a file viewer to Windows, it is important first to understand how the default file viewers work.

The Shell calls the Quick View program to display a file. Quick View manages the file viewing process and presents error messages for error conditions returned by the display engines—a collection of DLLs that draws the viewer window and displays the file. Windows includes display engines for word processor documents, spreadsheets, databases, vector graphics, and raster graphics. File parser DLLs are associated with a particular display engine and are specific to a type or class of files. For example, spreadsheet and database files are associated with the spreadsheet and database display engines, respectively. These DLLs are typically between 25K and 75K in size and do all the low-level parsing of the files to be viewed.

There are two methods to add file viewing functionality to Windows. First, a particular file parser DLL may be added to the system. The advantage of this method is that file parsers are relatively straightforward to write and debug. The disadvantage is that the limitations built into the default display engines (such as no printing and no cut, copy, or paste operations) remain even when a new file parsing DLL is used. For more information about the interface between file parsers and display engines, see File Parsers.

The second method of including file viewing functionality in Windows is to add one or more DLLs that work directly with Quick View. An example of one of these file viewing systems for ASCII files is found in the Samples subdirectory of the Microsoft Platform Software Development Kit (SDK). The main advantage of this method is that the code you write can support whatever file viewing functionality you wish to provide. This may be particularly important if your file format does not display well with one of the four default display engines. For example, an accounting package might have this problem because its file format is not recognized by one of the default display engines. The main disadvantage of this method is that writing for the Quick View interface requires additional development and testing effort.

The file viewing technology used by the Quick View feature was developed jointly by Microsoft Corporation and Systems Compatibility Corporation.

File Viewer Registration

During installation, a file viewer should ensure that entries exist in the registry that accurately associate a file with the class identifier of the file viewer's in-process server DLL. The file viewer's installation program may merge the contents of a registration (.reg) file into the registry. A file viewer can register itself for more than one file type if it can handle multiple file formats. If a file type has more than one registered file viewer, the Shell activates the most recently registered viewer for the file type when the user chooses the Quick View command.

Determining file types

The Quick View program attempts a simple association using the file name extension. If there is no file name extension or if there are no file viewers registered for the file name extension, Quick View calls each registered file viewer to see if any of them recognize the file. If more than one file viewer is registered for the same file name extension, Quick View calls each file viewer starting with the last one in the list. If Quick View cannot find a file viewer that can read the file, the Quick View operation fails and Quick View displays the following message:

There are no viewers registered for this type of file. Would you like to try the default viewer?

The default viewer displays a hexadecimal dump using the word processing engine.

Structure of registry entries

The following registry structure is required for Quick View to associate a class identifier or file name extension with the class identifier of a file viewer.

HKEY_CLASSES_ROOT
    \QuickView
        \<extension> = <human-readable document type>
            \{<CLSID>} = <human-readable viewer name>
            \{<CLSID>} = <human-readable viewer name>
            \{<CLSID>} = <human-readable viewer name>

        ...[More extension entries for additional file types]
            ...

    \CLSID
        \{<CLSID>} = <human-readable viewer name>
            \InprocServer32 = <full path to file viewer DLL>
                            = ThreadingModel = "Apartment"

        ...[More class IDs for file viewers and other object servers]

A description of the registry entries follows.
Entry | Description
HKEY_CLASSES_ROOT | Root of the registry.
QuickView | Top-level key under which associations are stored.
CLSID | 16-byte OLE class identifier spelled out in hexadecimal digits in the form of 12345678-1234-1234-1234-1234567890AB (with the hyphens included). All class identifiers are surrounded by curly braces when stored in the registry.
human-readable document type | String describing the file type associated with the class identifier or file name extension that can be displayed to the user. A file viewer can change the type when it is installed so that the name always reflects the preferred viewer. For example, this string might be "Windows Write Document."
human-readable viewer name | String that describes the vendor of the file viewer, as it might be displayed in an About box, such as "Company ABC Write Document Viewer."
<extension> | Three-character file name extension with the period, as is consistent with the standard 8.3 file name format (for example, .wri).

CLSID and InprocServer32 are standard OLE (32-bit) subkey names. The "ThreadingModel = Apartment" entry is required for file viewers. The apartment threading model, which is new for OLE in Microsoft Windows 95 and Microsoft Windows NT® version 3.51, allows the OleInitialize and CoInitialize functions to be called from multiple threads.

The QuickView key can have any number of file name extension subkeys, each representing a registered file type. Each file name extension subkey can have one or more class identifier subkeys, each representing a registered file viewer object. The most recently registered file viewer appears first in the list of class identifier subkeys, and it is the first one found when Quick View enumerates the registered file viewers.

Note The file viewer class identifier should always differ from the file type class identifier because the application that created the file may already be using the file type class identifier to identify the application as a compound document server.

Each class identifier stored under the file name extension subkeys must correspond to an entry of the same class identifier stored under the top-level key called CLSID. This is the standard location for storing information for OLE object servers. For file viewers, there must be an InprocServer32 subkey under the file viewer's class identifier key. The value of the InprocServer32 subkey is the full path to the file viewer DLL. You should store the full path and not depend on the DLL being in the path of the Windows 95 environment. InprocServer32 is a standard OLE subkey where the path to a COM object server is stored. Using this subkey allows the Quick View program to use standard OLE methods to access and create objects from file viewer servers.

Registering a file viewer

This section shows how to register a hypothetical file viewer for "AcmeWord Document" files with the .awd file name extension. The file viewer is implemented in an in-process server DLL called Acmewrdv.dll. The DLL has this class identifier: 00021116-0000-0000-C000-000000000046. The program that installs the file viewer creates the following registry entries:

HKEY_CLASSES_ROOT
    \QuickView
        \.AWD = AcmeWord Document
            \{00021117-0000-0000-C000-000000000046} = AcmeWord Document
                                                      Viewer
    \CLSID
        \{00021117-0000-0000-C000-000000000046} = AcmeWord Document
                                                  Viewer
            \InprocServer32 = c:\acmeword\acmewrdv.dll
                            = ThreadingModel = "Apartment"

The .reg file, which is an ASCII text file, contains these entries. (Note that wrapped lines are indented on the second line.)

HKEY_CLASSES_ROOT\QuickView\.AWD = AcmeWord Document
HKEY_CLASSES_ROOT\QuickView\.AWD \{00021117-0000-0000-C000-
    000000000046} = AcmeWord Document Viewer
HKEY_CLASSES_ROOT\CLSID\{00021117-0000-0000-C000-000000000046} =
    AcmeWord Document Viewer
HKEY_CLASSES_ROOT\CLSID\{00021117-0000-0000-C000-000000000046}
    \InprocServer32 = c:\acmeword\acmewrdv.dll
                    = ThreadingModel = "Apartment"

The Quick View program uses these registry entries to associate a path with the class identifier of a file viewer's in-process server DLL.

Quick View Program

The Quick View program (Quikview.exe) acts on behalf of the Shell to locate and activate a file viewer for a given path. There is a one-to-one correspondence between each running instance of Quick View and each file being displayed in a file viewer. Each instance of Quick View defines a process for a file viewer, giving the file viewer its own message queue. Quick View turns over execution of the process to the file viewer until the file viewer shuts down.

Quick view execution and error conditions

The lifetime of each instance of the Quick View program consists of the following steps.

  1. When the user chooses the Quick View or Print command, the Shell starts an instance of Quikview.exe for each selected file (by using the Microsoft Win32® CreateProcess or WinExec function). The Shell may specify a Show command, and Quick View passes the command to the file viewer. The command-line argument that the Shell passes to Quick View has the following options.
    Option | Meaning
    -f:pathname | Path of the file to view or print. Universal Naming Convention (UNC) file names are allowed. If this option is not specified, Quick View terminates without displaying any messages.
    -v | File to be opened for viewing in the file viewer. If this option is specified, Quick View ignores all of the options described below. This is the default option in the absence of both -v and -p.
    -d | Quick View and the file viewer will suppress all user interface elements if -p is also specified. Quick View suppresses any error messages, and the file viewer should not display any dialog boxes for printing. Quick View ignores this option in the absence of -p.
    -p | File to be opened for printing. If -v is also present, Quick View ignores this option.
    -&:pathname | Printer driver to use to print the file. Quick View ignores this option in the absence of -p. If -p is present but -& is not, Quick View instructs the file viewer to use the default printer driver.
  2. Quick View starts and checks for a path on the command line. If there is no path, the user has attempted to start Quick View by itself and the program immediately terminates without displaying any messages.
  3. Quick View parses the file name extension from the path given in the -f option. If no file name extension is given, Quick View proceeds to stage E1 (error condition 1). Otherwise, Quick View uses the following procedure to find a file viewer class identifier associated with the given file name extension.
    A. Quick View attempts to open the HKEY_CLASS_ROOT\QuickView\extension key, where extension is parsed from the path.
    • If the file name extension maps to a type such as HKEY_CLASS_ROOT\extension = typename and there is a registry entry with the form HKEY_CLASS_ROOT\typename\QuickView = *, Quick View looks for file viewer class identifiers under HKEY_CLASS_ROOT\QuickView\*. If a key with the HKEY_CLASS_ROOT\*\QuickView = * form exists, the system attempts to use all the viewers listed under the "*" section.
    • Otherwise, Quick View begins enumerating the file viewer class identifiers under the HKEY_CLASS_ROOT\QuickView\extension key. If the enumeration fails (that is, there is nothing in the registry to enumerate), Quick View closes the key and proceeds to stage E2 (error condition 2). Otherwise, Quick View reads the first file viewer class identifier in the enumeration and proceeds to step 4.
    B. If an error occurs in step 4, the enumeration continues until all file viewer class identifiers have been tried. If no file viewer is activated, Quick View closes the key from A and proceeds to stage E2.
  4. When given a class identifier of a file viewer DLL, Quick View attempts to create an instance of a file viewer object of the given class by using the following procedure:
    A. | Quick View calls a function to create an instance of a file viewer object, specifying parameters that include the class identifier and the IID_IPersistFile interface identifier. This instructs OLE to load the DLL listed under the class identifier's InprocServer32 subkey, obtain an instance of the object from the DLL, and return an IPersistFile interface pointer to the object. If the instance cannot be created because of lack of memory, Quick View proceeds to stage E4. If it fails for some other reason, Quick View proceeds to stage E3. (Note that, because DLL objects are involved, any call to QueryInterface will not fail with REGDB_IID_NOTREG, which typically signals a corrupted registry. That error is generated only when LRPC proxies and stubs are involved.)
    B. | When given the IPersistFile interface pointer pIPersistFile, Quick View calls the IPersistFile::Load method, specifying the path of the file and the STGM_READ and STGM_SHARE_DENY_NONE values, which instruct the object to open the file for read access. If Load fails, Quick View calls the Release method of pIPersistFile and proceeds to stage E4 if the error is due to a lack of memory. Otherwise, Quick View proceeds to stage E3.
    C. | Quick View obtains the file viewer object's IFileViewer interface by specifying the IID_IFileViewer interface identifier in a call to the QueryInterface method of pIPersistFile. Quick View calls the Release method of pIPersistFile, regardless of the outcome. If this call fails due to lack of memory, Quick View proceeds to stage E4. Otherwise, Quick View proceeds to stage E3.
    D. | (1) If the -v option was present or both the -v and -p options were absent, Quick View calls the ShowInitialize method of pIFileViewer, which instructs the file viewer to load the file and perform any initialization prone to failure (including the creation of windows, the loading of resources, and so on). This is the file viewer's one chance to fail. If it fails, Quick View proceeds to stage E4 if the error is due to lack of memory or to stage E3 otherwise. If ShowInitialize succeeds, Quick View calls the Show method of pIFileViewer, specifying the show command that was passed to Quick View's WinMain function. Show does not return until the user closes the file viewer, and it always returns NOERROR in that case. If Show is called before ShowInitialize, it returns E_UNEXPECTED.
    (2) If the -p option was present (and the -v option was absent), Quick View calls the PrintTo method of pIFileViewer specifying the path of the printer driver provided in the -& option (or NULL if -& was absent) and a value indicating if the -d option was present on the command line (user interface suppression flag). PrintTo does not return until printing is complete or an error occurs. If an error occurs, the file viewer is responsible for notifying the user if the user interface suppression flag is FALSE.
    E. | When Show or PrintTo returns (whichever was called in steps D1 or D2), Quick View calls the Release method of pIFileViewer, regardless of the return value. If the file viewer successfully executed the IFileViewer::ShowInitialize method, the Release method will not fail. Release fails only if it is called before ShowInitialize. If PrintTo fails but the -d option was not specified on the command line, Quick View assumes that the file viewer displayed a message to indicate printing failed, and Quick View fails without displaying a message in that case. In any case, Quick View proceeds to step 5.
  5. Quick View releases any interface pointers it has and calls OleUninitialize. Quick View then terminates normally.

Quick View may encounter the following four error conditions (stages E1 through E4) during the lifetime of an instance.
E1 If Quick View fails to associate the path with a file viewer class identifier (using a file name extension), it displays this message.
There are no viewers for this type of file. Would you like to try the default viewers?

If the user clicks No, Quick View terminates. If the user clicks Yes, Quick View displays the Searching dialog box, enumerates all registered file viewers (regardless of file type or file name extension), and attempts to have each one load and display the file. Quick View tries each file viewer of a given class identifier once. If no file viewer successfully displays the file, Quick View removes the Searching dialog box and displays this message.

Error opening or reading file.
When the user closes the dialog box, Quick View terminates.
E2 If Quick View successfully determines the file type but fails to enumerate any file viewers associated with the file name extension, it displays the Searching dialog box and attempts to have each registered viewer display the file, trying each file viewer class identifier once. If that fails, the Quick View removes the Searching dialog box and displays this message.
There are no viewers capable of viewing human-readable document type files.
When the user closes the dialog box, Quick View terminates.
E3 If Quick View successfully locates an initial file viewer but fails to view the file for any reason other than an out-of-memory condition, Quick View displays the Searching dialog box and continues enumerating viewers under the class identifier or file name extension key currently in use. If Quick View tries all viewers registered for the type unsuccessfully, processing continues as in stage E2 by trying all registered viewers regardless of registered type.
E4 If an out-of-memory condition occurs for one file viewer, it is likely that other viewers will not succeed either. In that case, Quick View displays a dialog box (using MB_ICONEXCLAMATION) with this message.
There is not enough memory to view or print file name. Quit one or more files or programs, and then try again.

A file viewer can return a number of error values to Quick View. When Quick View receives an error value, it displays an error message. Quick View recognizes the following error values:
FV_E_BADFILE | ((HRESULT)0x8534E102L)
FV_E_EMPTYFILE | ((HRESULT)0x8534E108L)
FV_E_FILEOPENFAILED | ((HRESULT)0x8534E105L)
FV_E_INVALIDID | ((HRESULT)0x8534E106L)
FV_E_MISSINGFILES | ((HRESULT)0x8534E104L)
FV_E_NOFILTER | ((HRESULT)0x8534E100L)
FV_E_NONSUPPORTEDTYPE | ((HRESULT)0x8534E101L)
FV_E_NOVIEWER | ((HRESULT)0x8534E10AL)
FV_E_OUTOFMEMORY | ((HRESULT)0x8534E107L)
FV_E_PROTECTEDFILE | ((HRESULT)0x8534E109L)
FV_E_UNEXPECTED | ((HRESULT)0x8534E103L)

Pinned windows

The Shell can request that Quick View display a new file in the same window used by the previous file viewer; this is called pinning a viewer window. Quick View communicates the Shell's request by sending a WM_DROPFILES message to the file viewer. The message contains an internal drop files structure whose members include the path of the new file to be displayed. A file viewer uses the same code to handle both the pinned state and drag-and-drop operations in which the file viewer displays a file the user has dropped on the viewer window.

Quick View implements the IFileViewerSite interface, which allows a file viewer to retrieve the handle to the current pinned window, if there is one, or set a new pinned window. When Quick View calls a file viewer's IFileViewer::ShowInitialize method, the file viewer receives the address of Quick View's IFileViewerSite interface. If the file viewer saves the address of the interface, it should call the AddRef method to increment the reference count.

Only one pinned window can exist at a time. A file viewer uses the IFileViewerSite::SetPinnedWindow method to set a new pinned window and the IFileViewerSite::GetPinnedWindow method to retrieve the handle to the current pinned window.

When Quick View calls the file viewer's IFileViewer::Show method, the file viewer receives the address of an FVSHOWINFO structure that includes an optional RECT structure. A valid RECT structure is a hint from the Shell that the file viewer window should be pinned; the file viewer should set the size and position of its window based on the information in the structure.

If the file viewer window receives a WM_DROPFILES message, it should fill in the strNewFile member of the FVSHOWINFO structure with the path of the new file to be displayed, fill the rect member with the size and position of the viewer window, and set the appropriate values in the dwFlags member. The file viewer should also fill the punkrel member with the address of an interface that the new file viewer should call to release the previous file viewer. Doing this allows the previous file viewer to perform cleanup operations. The new file viewer may be the same as the current file viewer if the current one supports the new file. If the old file viewer is the same as the new one, the release does not do anything because the reference count is greater than zero.

If a file viewer returns a file but Quick View cannot find a viewer for the new file, it calls the IFileViewer::Show method for the old file viewer with the FVSIF_NEWFAILED value. The file viewer can either terminate or continue showing the previous file.

Searching dialog box

When Quick View must enumerate more than one file viewer from the registry, it displays a dialog box containing a message that reads as follows:

Searching for a viewer to display or print the <human-readable
document type> in <file name>. Press Cancel to stop the search.

If the document type is not known, the following message appears:

Searching for a viewer to display or print <file name>.
Press Cancel to stop the search.

Quick View animates the magnifying glass icon in the dialog box to indicate that Quick View is searching the hard disk. Pressing the Cancel button stops any search in progress and closes Quick View without performing any further actions or providing any user interface.

File Viewer Structure and Implementation

A file viewer is an OLE COM object in an in-process server DLL that implements the IPersistFile and IFileViewer interfaces. The in-process server exports the DllGetClassObject and DllCanUnloadNow functions, implements a class factory object with the IClassFactory interface, and implements the file viewer object with the interfaces required. The following illustration shows the structure of a file viewer.

Structure of a file viewer.

There are a number of reasons why a file viewer is best implemented in a DLL with the given interfaces. In general, a DLL is faster to load and usually comes in a small package. In the future, these same DLLs will provide other nonuser interface features, such as content indexing, and a COM object DLL will be the fastest and most efficient way to access those features. In some cases, a file viewer object may need to display pop-up windows and process messages through its own message loop as in Windows 95. The DLL structure still allows this when used in conjunction with a stub process like Quick View, which gives the file viewer DLL the right to execute a message loop.

The IPersistFile interface in the file viewer object is intended to be a general mechanism through which the object is given a path for a file. Once the IPersistFile interface is obtained, the component that loaded the object can ask it to do any number of things with the file. Through Quick View, the Windows 95 Shell asks the object to show the file by using the IFileViewer::ShowInitialize and IFileViewer::Show methods or asks the object to print the file to a specific printer by using the IFileViewer::PrintTo method. In the future, the Shell may ask the object to perform content indexing, which would happen through an interface other than IFileViewer. For this reason, the file loading methods of IPersistFile are separate from the IFileViewer file methods, which is why IFileViewer was not just extended with its own Load method. Extending IFileViewer would have been more efficient (because it avoids IPersistFile entry point functions that are not implemented), but the current design is easier to extend.

IFileViewer interface

The Shell uses the IFileViewer interface to print the file or to tell a file viewer object when to show its user interface for the file being viewed. In addition to the usual IUnknown members, the interface includes the IFileViewer::ShowInitialize, IFileViewer::Show, and IFileViewer::PrintTo methods.

Before calling IFileViewer::Show, the Shell calls IFileViewer::ShowInitialize to instruct the file viewer to perform any necessary initialization. ShowInitialize can fail, whereas Show cannot because Quick View needs to know, before anything becomes visible and before transferring control to the file viewer, whether the file viewer can show the file. If the file viewer can show the file, Quick View hides its Searching dialog box before the file viewer window appears.

The ShowInitialize method should return the FV_ error codes listed in the Structure of registry entries section. Although the sample file viewer included in the Microsoft Platform SDK uses a more generic form of error codes, new file viewer DLLs should use the FV_ codes.

The Show method is similar to the Windows ShowWindow function in that it receives a Show command indicating how the file viewer should initially display its window. In general, Quick View passes the Show command from its WinMain function directly to IFileViewer::Show, which passes the command to ShowWindow. Since Quick View obtains this parameter from the Shell, this design enables the Shell to open a file viewer in the minimized, normal, or maximized state and even allows the Shell to hide a file viewer (with the SW_HIDE value). There is no extra overhead in providing this flexibility. Note that the Windows 95 Shell always starts Quick View with the SW_SHOWNORMAL value.

The only case when Show can fail is if ShowInitialize has not been called. In that case, it returns the E_UNEXPECTED status code. Otherwise, Show must return the NOERROR error code.

The PrintTo method is like Show in that it does not return until it finishes printing or an error occurs. If an error occurs, the file viewer object is responsible for informing the user of the problem. When calling PrintTo, the Shell specifies the name of the printer driver that the file viewer should use to print the file. The Shell also specifies a flag that indicates whether the file viewer should display any user interface elements, including error messages, during the print operation. If the flag is FALSE, the file viewer may show Print dialog boxes, Printer Setup dialog boxes, error messages, and so on.

The IFileViewer interface identifier is defined in the Windows header files as the IID_IFileViewer.

File viewer creation

You can create a file viewer that interacts appropriately with Quick View by following these steps:

  1. Define the file viewer object to use the IPersistFile and IFileViewer interfaces. The object must also implement a separate IUnknown interface that does not delegate calls in aggregation situations. In general, a file viewer object creates or attaches to a window that displays a file's contents.
  2. Implement the IPersistFile::Load and IPersistFile::GetCurFile methods (as well as the IUnknown methods). The IPersistFile::IsDirty method can simply return ResultFromScode (S_FALSE) because a file viewer does not modify the file, and the IPersistFile::Save and IPersistFile::SaveCompleted methods should simply return ResultFromScode (E_NOTIMPL). IPersistFile::Load stores the file name but delays opening the file until the later call to the IFileViewer::ShowInitialize method. IPersistFile::GetCurFile returns ResultFromScode (E_UNEXPECTED) if Load has not yet been called. Otherwise, it copies the path and returns the NOERROR error code.
  3. Implement the IFileViewer::ShowInitialize and IFileViewer::Show methods (as well as the IUnknown methods). ShowInitialize must perform all operations that are prone to failure. Therefore, if ShowInitialize succeeds, Show will never fail. The implementation of these two member functions is similar to the implementation of an application's WinMain function. ShowInitialize registers window classes, creates any necessary windows, and loads the file as read-only with the path given in the IPersistFile::Load method. ShowInitialize uses the instance handle that the DLL receives in its DllEntryPoint function, not the instance of Quick View, when registering and creating windows. Then Show displays the contents of the file in the viewport window, shows the top-level file viewer window, and enters a message loop. To enhance the appearance of the user interface, the file should be loaded and completely displayed in the viewport window before the windows are made visible.

    IFileViewer::Show does not return until the user has closed the window; Quick View waits for Show to return before it terminates. Quick View delegates the responsibility of the message loop to the Show method, so ShowInitialize and Show look and behave exactly like a WinMain function in any application (the code is just stored in a DLL).

    Note that the path in the IPersistFile::Load method may be a uniform naming convention (UNC) path. Functions such as Win32 OpenFile and OLE StgOpenStorage automatically handle UNC paths. If you open a file any other way, you must be sure to handle UNC paths properly.

  4. Define the class factory object with the IClassFactory interface and implement the interface completely to create a file viewer object. The class factory must support aggregation and server locking, as required by the IClassFactory interface.
  5. Implement the DllGetClassObject function to create an instance of the class factory mentioned in step 4, and return a pointer to one of its interfaces, as required for any COM object DLL.
  6. Implement the DllCanUnloadNow function to return the appropriate code, depending on the number of file viewer objects in service and the number of lock counts implemented by using the IClassFactory::LockServer method, as required for any COM object DLL.
  7. Include the Print To feature by using the IFileViewer::PrintTo method. This step is optional. If this feature is not implemented, the member function must return ResultFromScode (E_NOTIMPL).
  8. Finish the DLL implementation by using the DllEntryPoint function, as required for any Win32-based DLL.

In general, only the implementations of IPersistFile::Load and the IFileViewer methods are specific to a file viewer. The other steps that deal with creating an OLE COM object are standard OLE mechanisms.

File Viewer User Interface Guidelines

This section describes the minimal user interface recommended for a file viewer. These guidelines are provided to promote a consistent user interface in all file viewers. You should follow these guidelines as closely as possible and include viewer-specific features within the context of these guidelines.

File viewer main window

A file viewer's main window should have Minimize, Maximize, and Close buttons and these top-level menu items: File, View, and Help. A file viewer should also include a toolbar and a status window. The appearance and contents of the viewport window, which occupies all space not used by the toolbar and status window, is left to the developer. However, the viewport window typically has proportional scroll bars if the file contents are not entirely visible in the viewport. The initial show state of the window (normal, minimized, or maximized) is given in the IFileViewer::Show method.

The following illustration shows an example of a file viewer window.

File viewer window in the typical initial state.

A file viewer can include other top-level menu items for file-specific features. For example, a file viewer should include an Edit menu with a single Copy command to allow the user to make a selection in the viewport window and copy it to the clipboard. However, such extensions are not part of the basic user interface for a file viewer.

You should also use the window flags to create a 3-D window appearance and use scroll bars with proportional scroll boxes.

File viewer File menu items

The standard file viewer File menu has the following four items (as well as separators), two of which are optional. A file viewer can add other items to the menu, but in most cases there is no need for other items.
Menu item string | Result of selecting the menu item
"&Open File for Editing" Locates and starts the application that can open and edit the file. After successfully starting the application, the file viewer should hide its window immediately, shut down, and return from IFileViewer::Show, after which the Quick View process terminates. If the file viewer fails to start the application, it should display the following message:
There is no application available that can open this file.
Separator | Not applicable.
"Page Set&up" (optional) | Activates the standard Page Setup dialog box (or an application-specific dialog box if desired), the results of which affect the display of the file in the viewport window. The effects of the Page Setup command last only for the duration of the file viewer and do not affect the contents of the disk file. This menu item should appear if the file viewer supports printing and only if the Print menu item appears as well.
"&Print\tCtrl+P" (optional) | Activates the standard Print/Printer Setup property sheet. Any changes made to the printer setup that would affect the display of the file in the viewport window last only for the duration of the file viewer and do not affect the contents of the disk file. This menu item should appear only if the file viewer supports printing a file without starting the full application.
Separator | Not applicable.
"E&xit" | Hides the main window, closes the file, destroys all the windows, performs other necessary cleanup, and returns with NOERROR from IFileViewer::Show. The window should be hidden before cleanup happens to avoid marring its appearance when the system destroys the toolbar and other controls.

File viewer View menu items

The View menu of a standard file viewer has the following items.
Menu item string | Result of selecting the menu item
"&Toolbar" | Used to switch between displaying and hiding the toolbar. This item is checked when the toolbar is visible and unchecked when it is hidden.
"&Status Bar" | Used to switch between displaying and hiding the status window. This item is checked when the status bar is visible and unchecked when it is hidden.
"&Page View" | Used to switch between a full-sized view and a single-page view and vice versa.
"Replace &Window" | Used to switch between reusing the current window to view a file and creating a new window to view a file.
Separator | Not applicable.
"&Landscape" | Used to switch between landscape and portrait views when in page view.
"&Rotate" | Rotates a raster graphic image 90 degrees every time the image is selected.
Separator | Not applicable.
"&Font" | Displays a dialog box that allows the user to select a font and point size for viewing word processing documents and spreadsheets.

File viewer Help menu items

The standard file viewer Help menu has the following items.
Menu item string | Result of selecting the menu item
"&Help Topics" | Activates Winhelp.exe with the file viewer's Help file.
"&About fileviewer name" | Displays an About dialog box for the file viewer. The About dialog box identifies the vendor of the file viewer.

A file viewer can also add other Help items and context-sensitive Help.

File viewer toolbar buttons

A file viewer must include a toolbar with a single button tied to the Open File for Editing menu item on the File menu described previously. The image in this button is a 16-by-15-pixel bitmap derived from the icon of the application that would be started if the user opened the file from the Shell (using the Shell's association route). The image is obtained by calling the SHGetFileInfo function with the path of the file. If this function fails, a file viewer can include a button that contains its own image and attempt to start the parent application, or the file viewer can remove the button and disable the Open File for Editing menu item on the File menu. This single button must be the leftmost item on the toolbar and must be separated from any other buttons that are specific to the file viewer.

The following illustration shows an example of an Open File for Editing button implementation.

An Open File for Editing button.

Other buttons should correspond roughly to the functions present in the file viewer menus. A file viewer that supports a Font menu item should have Increase Font Size and Decrease Font Size buttons. Other file viewer classes may need to include printing and rotation buttons on the toolbar.

A standard toolbar button is the Replace Window button. The default behavior for file viewers is for a new file viewer instance to be created whenever the user chooses the Quick View menu item. When the Replace Window button is switched to the "on" position, however, a new instance is not created; instead, the contents of the relevant file viewer window are replaced by a view of the new file.

All buttons should have a corresponding ToolTip control that displays some context information when the mouse cursor is positioned on the button. The standard Windows 95 toolbar control provides built-in support for ToolTip controls, so you only have to provide the text string. The following illustration shows a ToolTip control for a toolbar button.

ToolTip control for a toolbar button.

The recommended ToolTip strings for various toolbar buttons follow.
Toolbar Button | ToolTip String
Open File for Editing | Open File for Editing
Font Increase | Increase Font Size
Font Decrease | Decrease Font Size
Small View | Toggle view size
Landscape | Toggle portrait/landscape
Rotate [Again] | Rotate image 90 degrees
Replace Window | Replace Window

File viewer status window messages

A file viewer should display status window messages for the system menu and all top-level and pop-up menu items. The messages for the system menu and other menu items used by the default Windows file viewers follow:
[Menu] Item | Message
[System] | Commands for manipulating this and other windows.
[System] Restore | Restores this window to normal size/Expands this window to full screen size.
[System] Move | Moves this window to another screen location.
[System] Size | Resizes this window.
[System] Minimize | Collapses this window to an icon.
[System] Maximize | Expands this window to full screen size.
[System] Close | Closes this window.
[System] Switch To... | Switch to another task.
[File] | Contains commands for opening the file and quitting Quick View.
[File] Open File for Editing | Opens the file for editing.
[File] Page Setup | Changes the page setup for printing.
[File] Print... | Prints the file contents.
[File] Exit | Quits Quick View.
[View] | Contains commands for customizing this window.
[View] Toolbar | Shows or hides the toolbar.
[View] Status Bar | Shows or hides the status bar.
[View] Page View | Switches between document and page views.
[View] Replace Window | Displays new files in current Quick View window.
[View] Landscape | Switches between portrait and landscape.
[View] Rotate (Again) | Rotates the image by 90 degrees.
[View] Font | Changes the display font.
[Help] | Contains commands for displaying Help and information about Quick View.
[Help] Help Topics | Displays the Help Contents and Index.
[Help] About | Displays program information, version number, and copyright.

The following standard messages for other conditions not related to menu items are implemented in the Windows default file viewers.

  • In the inactive state, when the user is doing nothing else, the status bar should read as follows:
    Display details may be inaccurate.

    This line should be the first visible message when the file viewer appears.

  • When the mouse cursor is positioned over the viewport window, the status window should read as follows:
    To edit, click Open File for Editing on the File menu.

    The following illustration shows a viewer window displaying this message.

    Example status bar text for a mouse move.

    Note that the document type is specific for the file viewer in use.

  • The status window should reflect longer versions of ToolTip messages when ToolTip controls are displayed. For example, a longer version of the Increase Font Size ToolTip is "Increase the font size of the display shown at the same time in the status window."

File viewer viewport window contents

The viewport window is where you provide most file-specific user interface elements. The viewport occupies all space in the client area of the main window not used for the toolbar and status bar. It displays the file contents in whatever mode is applicable, and it is sensitive to the user-selected printer and page setup, as well as other View menu commands.

If the contents of the file are too large to be completely displayed within the viewport, the file viewer should provide scroll bars (with proportional scroll boxes) to shift the image. If the contents of the file are smaller than the viewport window, no scroll bars should appear. In addition, the file contents should not be initially scaled to fill the viewport window unless the user selects scaling through the View menu commands.

The only other requirement for the viewport window is that it should provide a shortcut menu for the file. The shortcut menu should appear when the user clicks the viewport with the right mouse button. The shortcut menu should include the following items.
Menu item string | Equivalent found on other menu
"&Open File for Editing" | Open File for Editing command on the File menu
Separator | Not applicable
"Page Se&tup" (optional) | Page Setup command on the File menu
"&Print" (optional) | Print command on the File menu (note, no accelerator)
Separator | Not applicable

You can add more menu items as needed. The Toolbar and Status bar menu item commands on the View menu should not appear in the shortcut menu.

Drag-and-Drop in File Viewers

The default file viewers in Windows allow the user to drag a file from the desktop or Explorer and drop the file on a file viewer's window. A file viewer should show the small document icon that includes the + sign when the mouse is over the file viewer's window before the drop takes place. The Replace Window command in the View menu controls whether another file viewer window is displayed or the same window is reused.

Sophisticated File Viewers

This overview only describes the minimal file viewer user interface. There are, of course, many other possibilities besides just rudimentary printing and viewing capabilities. One useful feature is the ability to copy data from a document either to the clipboard or in a drag-and-drop operation. In such cases, the file viewer needs to provide the ability to select data in the file, a Copy command (on an Edit menu as well as in a shortcut menu), and the ability to pick up the selection and drag it elsewhere. However, the file viewer should not be a drop target and should not support the Cut and Paste commands on the Edit menu (or other variants) because those operations modify the file.

If the parent application creating the files that are handled in a specific file viewer is an OLE compound document container, the file viewer itself must be sensitive to viewing a compound document. That means that the file viewer itself will support some minimal container features and will, of course, use OLE to load and display compound document objects in the file itself. If the file viewer also supports in-place activation, it can activate inside-out objects in-place to allow the user to select and copy data from embedded objects.


Shell Library

Shell Functions

A Shell is an application that enables users to group, start, and otherwise control other applications. This overview describes features of the Shell for the Microsoft® Windows® operating system.

  • About the Shell Library
  • Shell Library Reference

About the Shell Library

The following features are supported by the dynamic-link library Shell.dll:

  • The drag-and-drop feature.
  • Associations used to find and start applications.
  • Extraction of icons from executable files.

Using the Drag-and-Drop Feature

When an application implements the drag-and-drop feature, a user can select one or more files in File Manager, drag them to an open application, and drop them there. The application in which the files were dropped receives a message it can use to retrieve the file names and the coordinates of the point at which the files were dropped.

An application that can accept dropped files from File Manager calls the DragAcceptFiles function for one or more of its windows. When the user releases the mouse button to drop a file or files in the window specified in the call to DragAcceptFiles, File Manager sends the application a WM_DROPFILES message. (File Manager does not send the WM_DROPFILES message to an application unless the application calls DragAcceptFiles.) WM_DROPFILES contains a handle to a structure that the application can query to retrieve the name of the dropped file and the coordinates of the cursor when the file was dropped. The application can use the DragQueryFile function to retrieve a count of the files that were dropped and their names. The DragQueryPoint function returns the window coordinates of the cursor when the user released the mouse button.

To free the memory allocated by the system for the WM_DROPFILES message, an application calls the DragFinish function when it is finished.

For example, an application can call the DragAcceptFiles function when it starts and call a drag-and-drop function when it receives a WM_DROPFILES message, as shown in the following example.

case WM_CREATE:
    DragAcceptFiles(hwnd, TRUE);
    break;

case WM_DROPFILES:
    DragFunc(hwnd, wParam); /* application-defined function */
    break;

case WM_DESTROY:
    DragAcceptFiles(hwnd, FALSE);
    break;

The following example uses the DragQueryPoint function to determine where to begin to write text. The first call to the DragQueryFile function determines the number of dropped files. The loop writes the name of each file, beginning at the point returned by DragQueryPoint.

POINT pt;
WORD cFiles, a;
char lpszFile[80];

DragQueryPoint((HANDLE) wParam, &pt);

cFiles = DragQueryFile((HANDLE) wParam, 0xFFFF, (LPSTR) NULL, 0);
for(a = 0; a < cFiles; pt.y += 20, a++) {
    DragQueryFile((HANDLE) wParam, a, lpszFile, sizeof(lpszFile));
    TextOut(hdc, pt.x, pt.y, lpszFile, lstrlen(lpszFile));
}

DragFinish((HANDLE) wParam);

Using Associations to Find and Start Applications

File Manager includes an Associate dialog box that makes it possible for users to associate a file name extension with a specific application. File Manager stores these associations in the registry (under HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Extensions). If a file has a file name extension that is associated with an application, that application starts automatically whenever the user double-clicks that file in File Manager.

Using the FindExecutable and ShellExecute functions, applications can take advantage of such associations to find and start applications or open and print files.

An application can use the FindExecutable function to retrieve the name and handle to the executable file that is associated with a specified file name. The ShellExecute function either opens or prints a specified file, depending on the value of its lpOperation parameter. To open a document file, the function relies on the association of the file name extension.

You can use ShellExecute to open or explore a folder. To open a folder, use either of the following calls:

ShellExecute(handle, NULL, "path_to_folder", NULL, NULL, SW_SHOWNORMAL);

or

ShellExecute(handle, "open", "path_to_folder", NULL, NULL, SW_SHOWNORMAL);

To explore a folder, use the following call:

ShellExecute(handle, "explore", "path_to_folder", NULL, NULL, SW_SHOWNORMAL);

If the lpOperation parameter is NULL, the function opens the file specified by its lpFile parameter. If lpOperation is "open", the function will open the file in a new window. If lpOperation is "explore", the function will browse to the folder using an existing Explorer window, if one is open. If an Explorer window is not open, a new one will be created.

Extracting Icons from Executable Files

An application can use the ExtractIcon function to retrieve the handle to an icon from a specified executable file, dynamic-link library, or icon file. The following example uses the DragQueryPoint function to retrieve the coordinates of the point where a file was dropped, the DragQueryFile function to retrieve the file name of a dropped file, and the ExtractIcon function to retrieve the handle to the first icon in the file, if any.

POINT pt;
WORD cFiles;
HDC hdc;
char lpszFile[80];
HANDLE hCurrentInst, hicon;

DragQueryPoint((HANDLE) wParam, &pt);

cFiles = DragQueryFile((HANDLE) wParam, 0xFFFF, NULL, NULL);

if(cFiles > 1) {
    TextOut(hdc, pt.x, pt.y,
        "Please drop only one icon file.", 31);
    return FALSE;
}
else {
    DragQueryFile((HANDLE) wParam, 0, lpszFile, sizeof(lpszFile));
    hCurrentInst = (HINSTANCE) GetWindowLong(hwnd, GWL_HINSTANCE);
    hicon = ExtractIcon(hCurrentInst, lpszFile, 0);
    if (hicon == NULL)
        TextOut(hdc, pt.x, pt.y, "No icons found.", 15);
    else if (hicon == (HICON) 1)
        TextOut(hdc, pt.x, pt.y,
            "File must be .EXE, .ICO, or .DLL.", 33);
    else
        DrawIcon(hdc, pt.x, pt.y, hicon);
}

DragFinish((HANDLE) wParam);

Shell Library Reference

The following programming elements are associated with Shell features.

Shell Library Functions

The following functions are used to implement Shell features.
DragAcceptFiles
DragFinish
DragQueryFile
DragQueryPoint
ExtractAssociatedIcon
ExtractIcon
ExtractIconEx
FindExecutable
ShellAbout
ShellExecute
ShellExecuteEx

Shell Library Messages

The following message is used to implement Shell features.
Message | Description
WM_DROPFILES | Sent to the window that the mouse is over when the user drops an item or items on the window. See the WM_DROPFILES description for more information.

Shell Library Structures

The following structure is used to implement Shell features.
SHELLEXECUTEINFO


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.

This documentation is provided for use with older versions of Windows. Starting with Windows 95, these function calls are mapped to the start menu. Applications should now use IShellLink, SHGetFolderPath, or the services in the Install Shield setup package to manage the contents of the start menu.

  • About Program Manager Initialization
  • Command-String Interface
  • Requesting 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)]

The characters: ';', ',', '|', '>', '<', ' " ', '?', '*', '\\', ':', and '/', cannot be used in file or folder names. The Program Manager will map them to '_'.

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

CreateGroup

DeleteGroup

DeleteItem

ExitProgman

Reload

ReplaceItem

ShowGroup


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.


IACList

The IACList interface is designed to improve the efficiency of autocompletion when the candidate strings are organized in a hierarchy.

Autocompletion normally requires three components:

  • The autocompletion client. This client is a window, such as a dialog box, that hosts the edit control.
  • The autocompletion object (CLSID_AutoComplete). This object is provided by the system, and handles the user interface, parsing, and background thread management.
  • The autocompletion list object. This object is responsible for providing lists of candidate strings to the autocompletion object.

A simple autocompletion list object needs only to export IEnumString in addition to IUnknown. When the user starts to enter characters in the edit box, the autocompletion object calls the list object's IEnumString interface to enumerate the list of strings that can be used to complete the partial string. The list object is responsible for maintaining a namespace and deciding which of those strings are relevant.

The simplest approach a list object can take is to return every string in its namespace every time the autocompletion object makes a request. For a discussion of how to implement this type of list object, see IAutoComplete. However, this approach is practical only if the namespace is relatively small. When large numbers of strings are involved, the list object needs to restrict itself to a small subset of the namespace.

The IACList interface is exported by autocompletion list objects to help them choose a sensible subset of strings from a hierarchically organized namespace. With a large namespace, this procedure substantially increases the efficiency of autocompletion. The basic procedure is:

  1. The autocompete object calls the list object's IEnumString interface. The list object returns the names of the top-level items in the hierarchy. For instance, if the namespace consists of every file and folder on the C: drive, the list object returns the fully qualified paths of the folders and files contained by the C:\ directory.
  2. The user continues to type until he or she enters a delimiter. The '\' and '/' characters are recognized as delimiters by the autocompletion object.
  3. The autocompletion object calls the list object's IACList::Expand method and passes it the current partial string.
  4. The autocomplete object then calls the list object's IEnumString interface again to request a new list of strings. If the partial string matches one of the top-level items in the namespace, the list object returns the names of the items that fall immediately under the selected item. For instance, if the user has entered "C:\Program Files\", the list object returns the names of the files and folders contained in that directory. If the name passed to IACList::Expand does not match any top-level item, the list object can simply stop returning strings until the autocomplete object calls IACList::Expand with a string that is in the list object's namespace.
  5. The process continues until the user selects a string, typically by pressing the ENTER key.

When to Implement

This interface is implemented by autocompletion list objects that maintain a hierarchically organized namespace. It is essential for acceptable performance if the namespace is large.

When to Use

Applications do not normally use this interface.

Methods

IACList exposes the following methods in addition to IUnknown.

Methods | Description
Expand | Requests that the autocomplete object expand a string.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IACList::Expand

Requests that the autocompletion client generate candidate strings associated with a specified item in its namespace.

HRESULT Expand(
    LPCOLESTR pszExpand
);

Parameters

pszExpand
[in] NULL-terminated string to be expanded by the autocomplete object.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

The autocomplete object calls this method when a delimiter is entered in the edit control. If the string pointed to by pszExpand matches an item in the autocompletion client's namespace, the client generates strings for those items that fall immediately under pszExpand in its namespace hierarchy. The client returns those strings next time the autocompletion object calls the client's IEnumString interface.

Assume, for example, that the client's namespace consists of all the files and folders on the C: drive, and pszExpand is set to "C:\Program Files\". The client should generate a list of strings corresponding to the fully qualified paths of the files and subfolders of "C:\Program Files\".

See Also

IACList

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IACList2

The IACList2 interface extends the IACList interface to allow clients of an autocomplete object to retrieve and set option flags.

When to Implement

Autocompletion clients implement this interface to allow the autocomplete object to retrieve and set options. The options are basically a request that the client generate a list with the names of all the files and subfolders contained by one or more specified folders. The autocomplete object then calls the client's IEnumString interface to request the strings.

When to Use

This interface is not normally used by applications.

Methods

IACList2 exposes the following methods in addition to IUnknown.

GetOptions | Retrieves the current autocomplete options.
SetOptions | Sets the current autocomplete options.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IACList2::GetOptions

Retrieves the current autocomplete options.

HRESULT GetOptions(
    DWORD *pdwFlag
);

Parameters

pdwFlag
[out] Pointer to a value that will hold the current option flag when the method returns. This can be a combination of the following values.
ACLO_CURRENTDIR | Enumerate the current working directory.
ACLO_DESKTOP | Enumerate the Desktop folder.
ACLO_FAVORITES | Enumerate the Favorites folder.
ACLO_FILESYSONLY | Enumerate only those items that are part of the file system. Do not enumerate items contained by virtual folders.
ACLO_MYCOMPUTER | Enumerate the My Computer folder.
ACLO_NONE | Don't enumerate anything.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IACList2

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IACList2::SetOptions

Sets the current autocomplete options.

HRESULT SetOptions(
    DWORD dwFlag
);

Parameters

dwFlag
[in] New option flags. Use these flags to ask the client to include the names of the files and subfolders of the specified folders the next time the client's IEnumString interface is called. This parameter can contain one or more of the following flags.
ACLO_CURRENTDIR | Enumerate the current working directory.
ACLO_DESKTOP | Enumerate the Desktop folder.
ACLO_FAVORITES | Enumerate the Favorites folder.
ACLO_FILESYSONLY | Enumerate only those items that are part of the file system. Do not enumerate items contained by virtual folders.
ACLO_MYCOMPUTER | Enumerate the My Computer folder.
ACLO_NONE | Don't enumerate anything.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IACList2

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IActiveDesktop

IActiveDesktop Interface

Allows a client program to manage the desktop items and wallpaper on a local computer.

IActiveDesktop Methods

AddDesktopItem | Adds a desktop item.
AddDesktopItemWithUI | Adds a desktop item to the Active Desktop using a user interface.
AddUrl | Adds the desktop item associated with the specified URL.
ApplyChanges | Applies changes to the Active Desktop.
GenerateDesktopItemHtml | Generates a generic HTML page containing the given desktop item.
GetDesktopItem | Retrieves the specified desktop item.
GetDesktopItemByID | Retrieves the desktop item that matches the given identification.
GetDesktopItemBySource | Retrieves a desktop item using its source URL.
GetDesktopItemCount | Retrieves a count of the desktop items.
GetDesktopItemOptions | Retrieves the desktop item's options.
GetPattern | Retrieves the pattern currently being used.
GetWallpaper | Retrieves the wallpaper currently being used.
GetWallpaperOptions | Retrieves the wallpaper options.
ModifyDesktopItem | Modifies the desktop item.
RemoveDesktopItem | Removes the specified desktop item from the desktop.
SetDesktopItemOptions | Sets the item's options.
SetPattern | Sets the ActiveDesktop pattern.
SetWallpaper | Sets the wallpaper for the Active Desktop.
SetWallpaperOptions | Sets the wallpaper options.

See Also

Active Desktop Interface (overview)

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::AddDesktopItem

IActiveDesktop::AddDesktopItem Method

Adds a desktop item.

HRESULT AddDesktopItem(
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Parameters

pcomp
Address of the COMPONENT structure associated with the item to be added.
dwReserved
Reserved. Must be set to zero.

Return Value

Returns one of the following values:

E_FAIL | Failed to add the desktop item or an instance of the desktop item already exists on the Active Desktop.
E_INVAILDARG | One or more of the parameters were invalid.
S_OK | Desktop item has been added succesfully.

Remarks

The desktop item is added to the desktop, but it does not save it to the registry. The client application must call IActiveDesktop::ApplyChanges separately to update the registry.

See Also

Active Desktop Interface (overview), IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::AddDesktopItemWithUI Method

Adds a desktop item to the Active Desktop after displaying user interfaces that confirm the addition of the desktop item, verify security zone permissions, and ask if the user wants to create a subscription.

HRESULT AddDesktopItemWithUI(
    HWND hwnd,
    LPCOMPONENT pcomp,
    DWORD dwFlags
);

Parameters

hwnd
Handle of the parent window. If NULL, the desktop item will be added without displaying any user interface.
pcomp
Address of the COMPONENT structure containing the details of the desktop item to be added.
dwFlags
Unsigned long integer value that contains the flags that control how the desktop item is added. Can be one of the following values:
Flag | Description
DTI_ADDUI_DEFAULT | Do default action. Identical to using zero.
DTI_ADDUI_DISPSUBWIZARD | Activate the subscription wizard to allow the user to subscribe to this desktop item.
DTI_ADDUI_POSITIONITEM | Instructs the system to look at the COMPPOS structure passed to the cpPos member of the COMPONENT structure to make sure that the values are within reasonable limits. This value was added for Microsoft® Internet Explorer 5.0.

Return Value

Returns one of the following values:

E_FAIL | Failed to add the desktop item or an instance of the desktop item already exists on the Active Desktop.
E_INVAILDARG | One or more of the parameters were invalid.
S_OK | If the ADDURL_SILENT flag has been set, the desktop item has either been added successfully or it already exists on the Active Desktop. Otherwise, the desktop item has been added succesfully.

Remarks

This method creates a second instance of the Active Desktop to add the desktop item, so the desktop item will not appear in the current instance. The application must call the IUnknown::Release method on this IActiveDesktop interface and the use the CoCreateInstance function to retrieve the Active Desktop object with the newly added component.

See Also

Active Desktop Interface (overview), IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::AddUrl Method

Adds the desktop item associated with the specified URL.

HRESULT AddUrl(
    HWND hwnd,
    LPCWSTR pszSource,
    LPCOMPONENT pcomp,
    DWORD dwFlags
);

Parameters

hwnd
Handle to the parent window for the user interface.
pszSource
Address of a string value that contains the URL of the desktop item.
pcomp
Address of the COMPONENT structure containing the details of the desktop item to be added.
dwFlags
Unsigned long integer value that controls this method. Can be set to ADDURL_SILENT to add a desktop item without displaying any user interfaces.

Return Value

Returns one of the following values:

E_FAIL | Failed to add the desktop item or an instance of the desktop item already exists on the Active Desktop.
E_INVAILDARG | One or more of the parameters were invalid.
S_OK | If the ADDURL_SILENT flag has been set, the desktop item has either been added successfully or it already exists on the Active Desktop. Otherwise, the desktop item has been added succesfully.

Remarks

By default, this method will display some user interface and then add the desktop item to the Active Desktop. Like IActiveDesktop::AddDesktopItem, the client application must call IActiveDesktop::ApplyChanges to have the changes saved to the registry.

See Also

Active Desktop Interface (overview), IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::ApplyChanges

Applies changes to the Active Desktop and saves them in the registry.

HRESULT ApplyChanges(
    DWORD dwFlags
);

Parameters

dwFlags
Unsigned long integer value that contains the changes to be applied. Can be one of the following values:
AD_APPLY_ALL
AD_APPLY_BUFFERED_REFRESH
AD_APPLY_DYNAMICREFRESH
AD_APPLY_FORCE
AD_APPLY_HTMLGEN
AD_APPLY_REFRESH
AD_APPLY_SAVE

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GenerateDesktopItemHtml

Generates a generic HTML page containing the given desktop item.

HRESULT GenerateDesktopItemHtml(
    LPCWSTR pwszFileName,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Parameters

pwszFileName
String value containing the name to store the HTML file under.
pcomp
Address of the COMPONENT structure of the desktop item to insert in the HTML page.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetDesktopItem

Retrieves the specified desktop item.

HRESULT GetDesktopItem(
    int nComponent,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Parameters

nComponent
Unsigned long integer value that contains the desktop item's index. The index values start at zero. Use IActiveDesktop::GetDesktopItemCount to retrieve a count on the total number of desktop items.
pcomp
Address of the COMPONENT structure of the retrieved desktop item.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

The index values will change as desktop items are added and removed from the Active Desktop. Applications cannot assume that an index value will always be associated with a particular desktop item.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetDesktopItemByID

Retrieves the desktop item that matches the given identification.

HRESULT GetComponentByID(
    DWORD dwID,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Parameters

dwID
Unsigned long integer value that contains the desktop item's identification.
pcomp
Address of the COMPONENT structure of the retrieved desktop item.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

The desktop item's identification is returned in the dwID member of the COMPONENT structure returned from the IActiveDesktop::GetDesktopItem method. This identification is only valid until the IActiveDesktop::ApplyChanges method is called. Applications that need to retrieve the same desktop item consistently should enumerate the desktop items using the IActiveDesktop::GetDesktopItem and IActiveDesktop::GetDesktopItemCount methods.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetDesktopItemBySource

Retrieves a desktop item using its source URL.

HRESULT GetDesktopItemBySource (
    LPCWSTR pszSource,
    LPCOMPONENT pcomp,
    DWORD dwReserved
);

Parameters

pszSource
String value containing the source URL of the desktop item.
pcomp
Address of the COMPONENT structure that will be used to store the details about the desktop item. The size of the structure must be initialized in order for it to work properly.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetPattern

Retrieves the pattern currently being used.

HRESULT GetPattern(
    LPWSTR pwszPattern,
    UINT cchPattern,
    DWORD dwReserved
);

Parameters

pwszPattern
Address of a string value that contains a string of decimals whose bit pattern represents a picture. Each decimal represents the on/off state of the 8 pixels in that row.
cchPattern
Unsigned long integer value that contains the size of the string.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetDesktopItemCount

Retrieves a count of the desktop items.

HRESULT GetDesktopItemCount(
    LPINT lpiCount,
    DWORD dwReserved
);

Parameters

lpiCount
Address of an integer value that contains the count.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

The lpiCount value can be used to enumerate all desktop items. The index values start at zero and go to lpiCount minus one.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetDesktopItemOptions

Retrieves the desktop item's options.

HRESULT GetDesktopItemOptions(
    LPCOMPONENTSOPT pco,
    DWORD dwReserved
);

Parameters

pco
Address of the COMPONENTSOPT structure containing the options that are currently set.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetWallpaper

Retrieves the wallpaper currently being used.

HRESULT GetWallpaper(
    LPWSTR pwszWallpaper,
    UINT cchWallpaper,
    DWORD dwReserved
);

Parameters

pwszWallpaper
String value that contains the file name of the wallpaper.
cchWallpaper
Unsigned integer value that contains size of the string.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::GetWallpaperOptions

Retrieves the wallpaper options.

HRESULT GetWallpaperOptions(
    LPWALLPAPEROPT pwpo,
    DWORD dwReserved
);

Parameters

pwpo
Address of a WALLPAPEROPT structure containing the options currently set.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::ModifyDesktopItem

Modifies the desktop item.

HRESULT ModifyDesktopItem(
    LPCCOMPONENT pcomp,
    DWORD dwFlags
);

Parameters

pcomp
Address of the COMPONENT structure containing the modifications. The desktop item associated with the wszSource member of the structure will be modified.
dwFlags
Unsigned long integer value containing the flags used for the modification. This can be one of the following values:
COMP_ELEM_ALL
COMP_ELEM_CHECKED
COMP_ELEM_CURITEMSTATE
COMP_ELEM_FRIENDLYNAME
COMP_ELEM_NOSCROLL
COMP_ELEM_ORIGINAL_CSI
COMP_ELEM_POS_LEFT
COMP_ELEM_POS_TOP
COMP_ELEM_POS_ZINDEX
COMP_ELEM_RESTORED_CSI
COMP_ELEM_SIZE_HEIGHT
COMP_ELEM_SIZE_WITDH
COMP_ELEM_TYPE

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

The client application must call IActiveDesktop::ApplyChanges separately to update the registry. For example, to change the friendly name, first call this function with either COMP_ELEM_FRIENDLYNAME or COMP_ELEM_ALL in the dwFlags member of COMPONENT. Then call IActiveDesktop::ApplyChanges.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::RemoveDesktopItem

Removes the specified desktop item from the desktop.

HRESULT RemoveDesktopItem(
    LPCCOMPONENT pcomp,
    DWORD dwReserved
);

Parameters

pcomp
Address of the COMPONENT structure that specifies the item to be removed. The desktop item associated with the wszSource member of the structure will be removed.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::SetDesktopItemOptions

Sets the item's options.

HRESULT SetDesktopItemOptions(
    LPCCOMPONENTSOPT pcomp,
    DWORD dwReserved
);

Parameters

pcomp
Address of the COMPONENTSOPT structure that contains the options to set.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::SetPattern

Sets the Active Desktop pattern.

HRESULT SetPattern(
    LPCWSTR pwszPattern,
    DWORD dwReserved
);

Parameters

pwszPattern
Address of a string value that contains a string of decimals whose bit pattern represents a picture. Each decimal represents the on/off state of the 8 pixels in that row.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::SetWallpaper

Sets the wallpaper for the Active Desktop.

HRESULT SetWallpaper(
    LPCWSTR pwszWallpaper,
    DWORD dwReserved
);

Parameters

pwszWallpaper
String value containing the file name of the wallpaper to be set.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IActiveDesktop::SetWallpaperOptions

Sets the wallpaper options.

HRESULT SetWallpaperOptions(
    LPCWALLPAPEROPT pwpo,
    DWORD dwReserved
);

Parameters

pwpo
Address of the WALLPAPEROPT structure containing the options to be set.
dwReserved
Reserved. Must be set to zero.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IActiveDesktop

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IAppPublisher Interface

This is preliminary documentation and is subject to change.

This is the principle interface implemented for publishing applications through the Add/Remove Programs Control Panel Application.

IAppPublisher Members

EnumApps | Creates an enumerator for enumerating all applications an application publisher publishes for a given category.
GetCategories | Retrieves a structure listing the categories provided by an application publisher.
GetNumberOfApps | Obsolete. Clients of Add/Remove Programs Control Panel Application can return E_NOTIMPL.
GetNumberOfCategories | Obsolete. Clients of the Add/Remove Programs Control Panel Application may return E_NOTIMPL.

Remarks

The Add/Remove Programs Control Panel Application creates your registered publisher object and requests its IAppPublisher interface. Through this interface, the application enumerator is created. Through the enumerator, the published application objects are created.

To publish applications to the Add/Remove Programs Control Panel Application, you must support IEnumPublishedApps, IAppPublisher, and IPublishedApp.

Interface Information

Stock Implementation | None
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IEnumPublishedApps, IPublishedApp


IAppPublisher::GetNumberOfCategories Method

This is preliminary documentation and is subject to change.

Obsolete. Clients of the Add/Remove Programs Control Panel Application may return E_NOTIMPL.

Syntax

void GetNumberOfCategories(VOID);

Return Value

No return value.

See Also

IEnumPublishedApps, IPublishedApp


IAppPublisher::GetNumberOfApps Method

This is preliminary documentation and is subject to change.

Obsolete. Clients of Add/Remove Programs Control Panel Application can return E_NOTIMPL.

Syntax

void GetNumberOfApps(VOID);

Return Value

No return value.

See Also

IEnumPublishedApps, IPublishedApp


IAppPublisher::GetCategories Method

This is preliminary documentation and is subject to change.

Retrieves a structure listing the categories provided by an application publisher.

Syntax

HRESULT GetCategories(
    APPCATEGORYINFOLIST *pInfoList
);

Parameters

pInfoList
[out] Pointer to an APPCATEGORYINFOLIST structure. This structure's cCategory member returns the count of supported categories. The pCategoryInfo member returns a pointer to an array of APPCATEGORYINFO structures. This array contains all the categories an application publisher supports and must be allocated with the Shell task allocator (cf. SHGetMalloc).

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The Add/Remove Programs Control Panel Application passes the identifier (ID) returned for a category to the IAppPublisher::EnumApps method to identify which category is to be enumerated.

Example

The following example shows how to calculate the size of the array of APPCATEGORYINFO structures.

sizeof(APPCATEGORYINFO) * cCategory;

See Also

APPCATEGORYINFO


IAppPublisher::EnumApps Method

This is preliminary documentation and is subject to change.

Creates an enumerator for enumerating all applications an application publisher publishes for a given category.

Syntax

HRESULT EnumApps(
    GUID *pAppCategoryID,
    IEnumPublishedApps **ppenum
);

Parameters

pAppCategoryID
[in] Pointer to a globally unique identifier (GUID) that specifies the application category to be enumerated. This must be one of the categories provided through IAppPublisher::GetCategories. If pAppCategoryID identifies a category not provided through IAppPublisher::GetCategories, creation of the enumerator succeeds with the enumerator returning zero items. If this parameter value is NULL, the enumerator returns applications published for all categories.
ppenum
[out] Pointer to an IEnumPublishedApps reference variable that points to a IEnumPublishedApps interface. Application publishers must create an enumeration object that supports the IEnumPublishedApps interface.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Note IEnumPublishedApps is not a standard enumeration interface. It does not support a Skip method nor does its Next method support retrieval of multiple items.

See Also

IEnumPublishedApps, IPublishedApp


IAsyncOperation

Allows interfaces that are normally synchronous to function asynchronously.

This interface is primarily exported by the data objects used with drag-and-drop and Clipboard operations. Normally, such operations are synchronous. However, if data rendering will be time-consuming, IASyncOperation can be used to allow data extraction to take place on a background thread. See Handling Shell Data Transfer Scenarios for a detailed discussion of how to use this interface.

When to Implement

IAsyncOperation is an optional interface that is implemented by a data object. It allows the drop target to negotiate with the drop source to extract data from the data object asynchronously.

When to Use

Drop sources and targets use this interface when they wish to have a lengthy data extraction processes handled by a background thread.

Methods

IAsyncOperation exposes the following methods in addition to IUnknown.

EndOperation | Notifies the data object that that asynchronous data extraction has ended.
GetAsyncMode | Called by a drop target to determine whether the data object supports asynchronous data extraction.
InOperation | Called by the drop source to determine whether the target is extracting data asynchronously.
SetAsyncMode | Called by a drop source to specify whether the data object supports asynchronous data extraction.
StartOperation | Called by a drop target to indicate that asynchronous data extraction is starting.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IASyncOperation::EndOperation

Notifies the data object that that asynchronous data extraction has ended.

HRESULT EndOperation(
    HRESULT hResult,
    IBindCtx *pbcReserved,
    DWORD dwEffects
);

Parameters

hResult
[in] An HRESULT value that indicates the outcome of the data extraction. Set to S_OK, if successful, or an OLE error code otherwise.
pbcReserved
[in] Reserved. Set to NULL.
dwEffects
[in] A DROPEFFECT value that indicates the result of an optimized move. This should be the same value that would be passed to the data object as a CFSTR_PERFORMMEDDROPEFFECT format with a normal data extraction operation.

Return Values

Returns S_OK if successful or an OLE error value otherwise.

Remarks

EndOperation retrieves the IAsyncOperation pointer stored by IAsyncOperation::SetAsyncMode, and passes its parameter values to that interface's IAsyncOperation::EndOperation method. EndOperation then releases the IAsyncOperation pointer.

EndOperation is also responsible for any clean-up operations that are needed. When finished, EndOperation should notify the drop source through a private interface.

See Also

IASyncOperation

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IASyncOperation::GetAsyncMode

Called by a drop target to determine whether the data object supports asynchronous data extraction.

HRESULT GetAsyncMode(
    BOOL *pfIsOpAsync
);

Parameters

pfIsOpAsync
[out] A Boolean value that is set to VARIANT_TRUE to indicate that an asynchronous operation is supported, VARIANT_FALSE otherwise.

Return Values

Returns S_OK if successful or an OLE error value otherwise.

Remarks

The purpose of this method is to give the drop target the value of the IAsyncOperation::SetAsyncMode method's fDoOpAsync parameter. This parameter is set to VARIANT_FALSE, by default. If the data object supports asynchronous data extraction, it must call IAsyncOperation::SetAsyncMode and set fDoOpAsync to VARIANT_TRUE.

See Also

IASyncOperation

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IASyncOperation::InOperation

Called by the drop source to determine whether the target is extracting data asynchronously.

HRESULT InOperation(
    BOOL *pfInAsyncOp
);

Parameters

pfInAsyncOp
[out] Set to VARIANT_TRUE if data extraction is being handled asynchronously, or VARIANT_FALSE otherwise.

Return Values

Returns S_OK if successful or an OLE error value otherwise.

Remarks

This method is called by the drop source after DoDragDrop returns. pfInAsyncOp should be set to VARIANT_TRUE only if the drop target has called IAsyncOperation::StartOperation.

See Also

IASyncOperation

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IASyncOperation::SetAsyncMode

Called by a drop source to specify whether the data object supports asynchronous data extraction.

HRESULT SetAsyncMode(
    BOOL fDoOpAsync
);

Parameters

fDoOpAsync
[in] A Boolean value that is set to VARIANT_TRUE to indicate that an asynchronous operation is supported, VARIANT_FALSE otherwise. It's default value is VARIANT_FALSE.

Return Values

Returns S_OK if successful or an OLE error value otherwise.

Remarks

This method is called by the drop source to indicate that the data object supports asynchronous data extraction. Store the fDoOpAsync for future use by IAsyncOperation::GetAsyncMode. The drop target determines whether asynchronous data extraction is supported by calling IAsyncOperation::GetAsyncMode to retrieve the fDoOpAsync value.

If fDoOpAsync is set to VARIANT_TRUE, SetAsyncMode must call IAsyncOperation::AddRef, and store the interface pointer for use by IAsyncOperation::EndOperation.

See Also

IASyncOperation

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IASyncOperation::StartOperation

Called by a drop target to indicate that asynchronous data extraction is starting.

HRESULT StartOperation(
    IBindCtx *pbcReserved
);

Parameters

pbcReserved
[in]Reserved. Set this value to NULL.

Return Values

Returns S_OK if successful or an OLE error value otherwise.

Remarks

The drop target calls this method to notify the data object that asynchronous data extraction is starting. The method should store this information, so that it can be returned by IAsyncOperation::InOperation. Once StartOperation has been called, the drop target returns the IDropTarget::Drop call as it would for normal synchronous data extraction.

See Also

IASyncOperation

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IAutoComplete

The IAutoComplete interface is exposed by the autocomplete object (CLSID_AutoComplete). It allows applications to initialize, enable, and disable the object.

Autocompletion expands strings that have been partially entered in an edit control into complete strings. For example, when a user starts to enter a URL in the Address edit control that is embedded in the Microsoft® Internet Explorer toolbar, autocompletion expands the string into one or more complete URLs that are consistent with the existing partial string. A partial URL string such as "mic" might be expanded to "http://www.microsoft.com" or "http://www.microsoft.com/windows". Autocompletion is typically used with edit controls or with controls that have an embedded edit control such as the comboboxex control.

Autocompletion has two modes for displaying the completed string. The modes are independent, so you can enable either or both. To specify the mode, call IAutoComplete2::SetOptions.

  • In autoappend mode, autocompletion appends the remainder of the most likely candidate string to the existing characters, highlighting the appended characters. The edit control behaves as if the user had entered the entire string manually and then highlighted the appended characters. If the user continues to enter characters, they are added to the existing partial string. If the user adds a character that is identical to the next highlighted character, the highlighting for that character will be turned off. The remaining characters will still be highlighted. If the user adds a character that does not match the next highlighted character, autocompletion attempts to generate a new candidate string based on the larger partial string. It appends the remainder of the new candidate string to the current partial string, as before. If no candidate string can be found, only the typed characters appear and the edit box behaves as it would without autocompletion. This process continues until the user accepts a string.
  • In autosuggest mode, autocompletion displays a drop-down list, with one or more suggested complete strings, beneath the edit control. The user can select one of the suggested strings, usually by clicking it with the mouse, or continue typing. As typing progresses, the drop-down list may be modified, based on the current partial string. If you set the ACO_SEARCH flag in the dwFlag parameter of IAutoComplete2::SetOptions, a "Search for 'XXX'" item is added to the bottom of the drop-down list. It is displayed even if there are no suggested strings. "XXX" is set to the current partial string and is updated as the user continues to type. If the user selects "Search for 'XXX'", your application should launch a search engine to assist the user.

The simplest way to implement autocompletion is to call SHAutoComplete. When this function is called for a system edit control, the control will autocomplete partially entered file system paths or URLs. To enable autocompletion for other types of strings, or to have more control over how autocompletion works, you can use the underlying autocomplete object directly.

When to Implement

This interface is not normally implemented by applications. It is exposed by the Shell's autocomplete object and used by applications.

When to Use

Use the IAutoComplete interface of the autocomplete object to initialize the object, and to enable or disable autocompletion.

To implement autocompletion for an edit control using the autocomplete object:

  1. Implement a string list COM object that exports an IEnumString interface. This string list object is responsible for providing the list of strings that the autocomplete object will use as candidates for completed strings.
  2. Create an instance of the autocomplete object with CoCreateInstance. Request a pointer to its IAutoComplete interface.
  3. Call IAutoComplete::Init. Set the hwndEdit parameter to the window handle of the edit control. If the edit control is embedded in another control, you must retrieve the handle to the edit control itself. For example, to retrieve a handle to the edit control embedded in a comboboxex control, send a CBEM_GETEDITCONTROL message. Set the punkACL parameter of IAutoComplete::Init to the IUnknown pointer of the string list object.
  4. If you do not want to use the default options, retrieve a pointer to the autocomplete object's IAutoComplete2 interface. Call IAutoComplete2::SetOptions to set the desired options.
  5. The autocomplete object uses the IUnknown pointer of the string list object, passed as punkACL in step 4, to retrieve a pointer to that object's IEnumString interface. The autocomplete object then calls that interface to generate its list of candidate strings. It selects strings from that list that are an acceptable match to the partial string in the control. In autoappend mode, the characters needed to complete the string are appended to the partial string and highlighted. In autosuggest mode, a drop-down box with a list of one or more possible strings is displayed below the edit control.
  6. If the user accepts an autocompleted string, the edit control behaves as if the string had been entered manually.

Autocompletion is enabled by default. Applications need only to call IAutoComplete::Enable to disable autocompletion or to reenable it if it has been disabled.

IAutoComplete exposes the following methods in addition to IUnknown.

Methods | Description
Enable | Enables or disables autocompletion.
Init | Initializes the autocomplete object.

See Also

IAutoComplete2, IObjMgr, IACList, IACList2, ICurrentWorkingDirectory

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shldisp.h.


IAutoComplete::Enable

Enables or disables autocompletion.

HRESULT Enable(
    BOOL fEnable
);

Parameters

fEnable
[in] Value that is set to TRUE to enable autocompletion, or to FALSE to disable it.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

Autocompletion is enabled by default. Applications need only to call this method to disable autocompletion or to reenable it if it has been disabled.

See Also

IAutoComplete

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shldisp.h.


IAutoComplete::Init

Initializes the autocomplete object.

HRESULT Init(
    HWND hwndEdit,
    IUnknown *punkACL,
    LPCOLESTR pwszRegKeyPath,
    LPCOLESTR pwszQuickComplete
);

Parameters

hwndEdit
[in] Handle to the window for the system edit control that is to have autocompletion enabled.
punkACL
[in] Pointer to the IUnknown interface of the string list object that is responsible for generating candidates for the completed string. The object must expose an IEnumString interface.
pwszRegKeyPath
[in] Pointer to an optional NULL-terminated Unicode string that gives the registry path, including the value name, where the format string is stored as a REG_SZ value. The autocomplete object first looks for the path under HKEY_CURRENT_USER. If it fails, it then tries HKEY_LOCAL_MACHINE. For a discussion of the format string, see the definition of pwszQuickComplete.
pwszQuickComplete
[in] Pointer to an optional string that specifies the format to be used if the user enters some text and presses CTRL+ENTER. Set this parameter to NULL to disable quick completion. Otherwise, the autocomplete object treats pwszQuickComplete as a sprintf format string, and the text in the edit box as its associated argument, to produce a new string. For example, set pwszQuickComplete to "http://www.%s.com/". When a user enters "MyURL" into the edit box and presses CTRL+ENTER, the text in the edit box is updated to "http://www.MyURL.com/".

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IAutoComplete

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shldisp.h.


IAutoComplete2

The IAutoComplete2 interface extends IAutoComplete. It allows clients of the autocomplete object to retrieve and set a number of options that control how autocompletion operates.

When to Implement

This interface is not normally implemented by applications. It is exposed by the Shell's autocomplete object and used by applications.

When to Use

Use this interface when you need to retrieve or set autocomplete options. The list of available options is given in the method references.

IAutoComplete2 exposes the following methods in addition to IUnknown.

Methods | Description
GetOptions | Retrieves the current autocomplete options.
SetOptions | Sets the current autocomplete options.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shldisp.h.


IAutoComplete2::GetOptions

Retrieves the current autocomplete options.

HRESULT GetOptions(
    DWORD *pdwFlag
);

Parameters

pdwFlag
[out] Flags that indicate the options that are currently set. This can be a combination of one or more of the following flags.
Flag | Description
ACO_NONE | No autocomplete.
ACO_AUTOSUGGEST | Enable the autosuggest drop-down list.
ACO_AUTOAPPEND | Enable autoappend.
ACO_SEARCH | Add a search item to the list of completed strings. Selecting this item launches a search engine.
ACO_FILTERPREFIXES | Don't match common prefixes, such as "www.", "http://", and so on.
ACO_USETAB | Use the TAB key to select an item from the drop-down list.
ACF_UPDOWNKEYDROPSLIST | Use the UP ARROW and DOWN ARROW keys to display the autosuggest drop-down list.
ACO_RTLREADING | Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Normally, a control's text is displayed in the same direction as the text in its parent window. If ACO_RTLREADING is set, the text reads in the opposite direction from the text in the parent window.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IAutoComplete2, IAutoComplete2::SetOptions

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shldisp.h.


IAutoComplete2::SetOptions

Sets the current autocomplete options.

HRESULT SetOptions(
    DWORD dwFlag
);

Parameters

dwFlag
[in] Flags that allow an application to specify autocomplete options. This can be a combination of one or more of the following flags.
Flag | Description
ACO_NONE | No autocompletion.
ACO_AUTOSUGGEST | Enable the autosuggest drop-down list.
ACO_AUTOAPPEND | Enable autoappend.
ACO_SEARCH | Add a search item to the dropdown list of completed strings. If this is item is selected, you should launch a search engine to assist the user.
ACO_FILTERPREFIXES | Don't match common prefixes, such as "www.", "http://", and so on.
ACO_USETAB | Use the TAB key to select an item from the drop-down list. This flag is disabled by default.
ACF_UPDOWNKEYDROPSLIST | Use the UP ARROW and DOWN ARROW keys to display the autosuggest drop-down list.
ACO_RTLREADING | Normal windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read right-to-left (RTL). Normally, a control's text is displayed in the same direction as the text in its parent window. If ACO_RTLREADING is set, the text is read in the opposite direction from the text in the parent window.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

The TAB key is disabled by default because it is normally used to navigate from control to control, not within a control. If you set the ACO_USETAB flag in dwFlag, users can navigate to a string in the drop-down list by pressing the TAB key. If the drop-down list is closed, the TAB key allows the user to navigate from control to control, as usual. The user can close the drop-down list by pressing the ESCAPE key.

See Also

IAutoComplete2

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shldisp.h.


ICategorizer Interface

This is preliminary documentation and is subject to change.

This interface provides methods that are used to obtain information about item identifier lists.

ICategorizer Members

CompareCategory | Determines the relative order of two items in their item identifier lists.
GetCategory | Retrieves a list of categories associated with a list of identifiers.
GetCategoryInfo | Retrieves information about a category, such as the default display and the text to display in the user interface.
GetDescription | Retrieves the name of a categorizer, such as "Group By Device Type", that can be displayed in the user interface.

Interface Information

Stock Implementation | Shell32.dll
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


ICategorizer::GetDescription Method

This is preliminary documentation and is subject to change.

Retrieves the name of a categorizer, such as "Group By Device Type", that can be displayed in the user interface.

Syntax

HRESULT GetDescription(
    LPWSTR pszDesc,
    UINT cch
);

Parameters

pszDesc
Pointer to a string that contains the categorizer name.
cch
Integer that specifies the number of characters in the categorizer name.

Return Value

Returns S_OK if successful, or an error value otherwise.


ICategorizer::GetCategoryInfo Method

This is preliminary documentation and is subject to change.

Retrieves information about a category, such as the default display and the text to display in the user interface.

Syntax

HRESULT GetCategoryInfo(
    DWORD dwCategoryId,
    CATEGORY_INFO *pci
);

Parameters

dwCategoryId
DWORD that specifies a category identifier.
pci
Pointer to a CATEGORY_INFO structure that contains the category information.

Return Value

Returns S_OK if successful, or an error value otherwise.


ICategorizer::GetCategory Method

This is preliminary documentation and is subject to change.

Retrieves a list of categories associated with a list of identifiers.

Syntax

HRESULT GetCategory(
    UINT cidl,
    LPCITEMIDLIST *apidl[cidl],
    DWORD *rgCategoryIds[cidl]
);

Parameters

cidl
[in] Integer that specifies the number of items in an item identifier list.
apidl
[in] Pointer to an array of item identifier list pointers.
rgCategoryIds
[in, out] Pointer to a DWORD array that receives the category identifiers.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The ICategorizer::GetCategory method accepts an array of pidls and fills an array of category identifiers.

Important -1 is an invalid category identifier.


ICategorizer::CompareCategory Method

This is preliminary documentation and is subject to change.

Determines the relative order of two items in their item identifier lists.

Syntax

HRESULT CompareCategory(
    CATSORT_FLAGS csfFlags,
    DWORD dwCategoryId1,
    DWORD dwCategoryId2
);

Parameters

csfFlags
Flag that specifies how the comparison should be performed. Parameter should be one of the values in CATSORT_FLAGS.
dwCategoryId1
DWORD that specifies the first category identifier to use in the comparison.
dwCategoryId2
DWORD that specifies the second category identifier to use in the comparison.

Return Value

If this method is successful, the CODE field of the HRESULT contains a value that specifies the outcome of the comparison, otherwise it returns an OLE error code.

Remarks

The following table shows the values returned in the CODE field of the HRESULT.

Less than zero | The first item should precede the second (dwCategoryId1 < dwCategoryId2).
Greater than zero | The first item should follow the second (dwCategoryId1 > dwCategoryId2).
Zero | The two items are the same (dwCategoryId1 = dwCategoryId2).


ICategoryProvider Interface

This is preliminary documentation and is subject to change.

This interface provides a list of categorizers registered on an IShellFolder.

ICategoryProvider Members

CanCategorizeOnSCID | Retrieves whether a column should be displayed in a specified view.
CreateCategory | Creates a category object.
EnumCategories | Retrieves a list of globally unique identifiers (GUIDs) that represent categories.
GetCategoryForSCID | Retrieves a globally unique identifier (GUID) that represents the categorizer to use for the specified Shell column.
GetCategoryName | Retrieves the name of the specified category.
GetDefaultCategory | Enables the folder to override the default grouping.

Interface Information

Stock Implementation | Shell32.dll
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


ICategoryProvider::GetDefaultCategory Method

This is preliminary documentation and is subject to change.

Enables the folder to override the default grouping.

Syntax

HRESULT GetDefaultCategory(
    GUID *pguid,
    SHCOLUMNID *pscid
);

Parameters

pguid
Pointer to a globally unique identifier (GUID).
pscid
Pointer to a SHCOLUMNID structure.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

ICategoryProvider returns either a GUID to create in ICategoryProvider::CreateCategory or a SHCOLUMNID that is used by the default categorizer. The method returns S_FALSE if a default group is not supported. If GUID_NULL is returned in pguid, it indicates that the client should use pscid as the default category.


ICategoryProvider::GetCategoryName Method

This is preliminary documentation and is subject to change.

Retrieves the name of the specified category.

Syntax

HRESULT GetCategoryName(
    GUID *pguid,
    LPWSTR pszName,
    UINT cch
);

Parameters

pguid
Pointer to a globally unique identifier (GUID).
pszName
Pointer to a string that receives the name of the category.
cch
Integer that receives the number of characters in the string.

Return Value

Returns S_OK if successful, or an error value otherwise.


ICategoryProvider::GetCategoryForSCID Method

This is preliminary documentation and is subject to change.

Retrieves a globally unique identifier (GUID) that represents the categorizer to use for the specified Shell column.

Syntax

HRESULT GetCategoryForSCID(
    SHCOLUMNID *pscid,
    GUID *pguid
);

Parameters

pscid
Pointer to a SHCOLUMNID structure.
pguid
Pointer to a GUID that represents the categorizer to use.

Return Value

Returns S_OK if successful, or an error value otherwise.


ICategoryProvider::EnumCategories Method

This is preliminary documentation and is subject to change.

Retrieves a list of globally unique identifiers (GUIDs) that represent categories.

Syntax

HRESULT EnumCategories(
    IEnumGUID **penum
);

Parameters

penum
Address of a pointer to an IEnumGUID interface that specifies a list of GUIDs that represent categories.

Return Value

Returns S_OK if successful, or an error value otherwise.


ICategoryProvider::CreateCategory Method

This is preliminary documentation and is subject to change.

Creates a category object.

Syntax

HRESULT CreateCategory(
    GUID *pguid,
    REFIID riid,
    void **ppv
);

Parameters

pguid
Pointer to the GUID for the category object.
riid
Identifier of the object to return.
ppv
Address of a pointer to the category object.

Return Value

Returns S_OK if successful, or an error value otherwise.


ICategoryProvider::CanCategorizeOnSCID Method

This is preliminary documentation and is subject to change.

Retrieves whether a column should be displayed in a specified view.

Syntax

HRESULT CanCategorizeOnSCID(
    SHCOLUMNID *pscid
);

Parameters

pscid
Pointer to a SHCOLUMNID structure that identifies the column.

Return Value

Returns S_OK if the view should display this column in the category selection user interface, or S_FALSE if the view should remove the column.


IColumnProvider

The Microsoft® Windows® Explorer Details view normally displays several standard columns. Each column lists information, such as the file size or type, for each file in the current folder. There can also be a number of columns that the user can choose to display. When the user right-clicks one of the column headers, a list of the available columns is displayed in a dialog box. By creating a column provider object that exports the IColumnProvider interface, you can add custom columns to that dialog box for display by Windows Explorer. For example, a collection of files that contain music could use a column provider to display columns listing the artist and piece contained by each file.

A column provider is a global object that is called every time Windows Explorer displays the Details view. Windows Explorer queries all registered column providers for their column characteristics. If the user has selected one of the column provider's columns, Windows Explorer queries the column provider for the associated data for each file in the folder. It then displays all the selected columns.

Typically, column providers are used to display one or more custom columns for a particular file class. When a column provider receives a request for data, it provides it if the file is a member of its supported class. Otherwise, it ignores the request by returning S_FALSE.

Columns are identified by an SHCOLUMNID structure that contains an FMTID/PID pair. If possible, use existing FMTIDs and PIDs. If a folder contains files from more than one file class, the data from different classes can be merged into the same column. For instance, the Author PID from the summary information property set can be used for a wide variety of purposes. If you use a custom SHCOLUMNID structure, the column will display data only for those files that are members of the supported class. If the folder contains other files, their entries will be blank.

When to Implement

Implement an object that exports this interface when you want to have one or more custom columns displayed in the Windows Explorer Details view. Windows Explorer calls the interface methods to request the information it needs to display the column. The procedure used by Windows Explorer is:

  1. Call IColumnProvider::Initialize to specify the folder to be displayed.
  2. Call IColumnProvider::GetColumnInfo to retrieve the column's characteristics.
  3. If the column has been selected by the user, call IColumnProvider::GetItemData for each file in the folder to retrieve the data that belongs in the file's column entry.

In addition to normal COM registration, the column provider object must also be registered with Windows Explorer. To do so, add a subkey named with the string form of the object's GUID to the HKEY_CLASSES_ROOT\Folder\shellex\ColumnHandlers key.

When to Use

This interface is called by Windows Explorer. It is not normally used by applications.

IColumnProvider exposes the following methods in addition to IUnknown.

Methods | Description
GetColumnInfo | Requests information about a column.
GetItemData | Requests column data for a specified file.
Initialize | Initializes the interface.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IColumnProvider::GetColumnInfo

Requests information about a column.

HRESULT GetColumnInfo(
    DWORD dwIndex,
    SHCOLUMNINFO *psci
);

Parameters

dwIndex
[in] Column's zero-based index. It is an arbitrary value that is used to enumerate columns.
psci
[out] Pointer to an SHCOLUMNINFO structure to hold the column information.

Return Values

Returns one of the following values.

Return Value | Description
S_OK | Request successful
S_FALSE | Column index out of range
OLE error value | Request unsuccessful

Remarks

This method is called to assign an index to the column and to ask for details on what kind of information the column will contain.

See Also

IColumnProvider

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IColumnProvider::GetItemData

Requests column data for a specified file.

HRESULT GetItemData(
    LPCSHCOLUMNID pscid,
    LPCSHCOLUMNDATA pscd,
    VARIANT *pvarData
);

Parameters

pscid
[in] SHCOLUMNID structure that identifies the column.
pscd
[in] SHCOLUMNDATA structure that specifies the file.
pvarData
[out] Pointer to a VARIANT with the data for the file specified by pscd that belongs in the column specified by pscid. Set this value if the file is a member of the class supported by the column provider.

Return Values

Returns S_OK if file data is returned, S_FALSE if the file is not supported by the column provider and no data is returned, or an OLE error value otherwise.

Remarks

This method is called to retrieve the data for a file to be displayed in the specified column. It should be threadsafe.

This method is called for every file that Microsoft® Windows® Explorer displays, even though many of them will not be supported by a particular column provider. To improve performance, first check the pwszExt member of the structure pointed to by pscd to see if it has a file name extension that is supported by the column provider. If not, avoid unnecessary processing by immediately returning S_FALSE.

See Also

IColumnProvider

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IColumnProvider::Initialize

Initializes an IColumnProvider interface.

HRESULT Initialize(
    LPCSHCOLUMNINIT psci
);

Parameters

psci
[in] SHCOLUMNINIT structure with initialization information, including the folder whose contents are to be displayed.

Return Value

Returns S_OK if successful, or an OLE error value otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


ICommDlgBrowser

The ICommDlgBrowser interface is exposed by the common file dialog boxes to be used when they host a Shell browser. If supported, ICommDlgBrowser allows a Shell view to handle several cases that need to behave differently in a dialog box than in a normal Shell view. You obtain an ICommDlgBrowser interface pointer by calling QueryInterface on the IShellBrowser object.

When to Implement

This interface is implemented only by the common file dialog boxes.

When to Use

Use ICommDlgBrowser when you need to provide special behavior while hosted inside the common dialog boxes.

ICommDlgBrowser Methods | Description
IncludeObject | Allows the common dialog to filter objects that the view displays.
OnDefaultCommand | Called when a user double-clicks in the view or presses the ENTER key.
OnStateChange | Called after a change of state has occurred in a common dialog box.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


ICommDlgBrowser::IncludeObject

Allows the common dialog box to filter objects that the view displays.

HRESULT IncludeObject(
    IShellView *ppshv,
    LPCITEMIDLIST pidl
   );

Parameters

ppshv
A pointer to the view's IShellView interface.
pidl
Pointer to an item identifier list (PIDL) that is relative to the folder.

Return Values

The browser should return S_OK to include the object in the view, or S_FALSE to hide it.

Remarks

This method is called by the IEnumIDList implementation when hosted in the file dialog boxes. The enumerator should call this method to let the common dialog box filter out objects that should not be displayed. Typically, the file dialog boxes will get the display text of the item, and filter by the extension.

Notes to Callers

Call before returning an object in the Shell folder's IDLIST enumerator.

See Also

ICommDlgBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


ICommDlgBrowser::OnDefaultCommand

Called when a user double-clicks in the view or presses the ENTER key.

HRESULT OnDefaultCommand(
    IShellView *ppshv
   );

Parameters

ppshv
A pointer to the view's IShellView interface.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

The browser should return S_OK if it has processed the action or S_FALSE to let the view perform the default action.

Note to Callers

This method allows the default command to be handled by the common dialog box instead of the view.

See Also

ICommDlgBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


ICommDlgBrowser::OnStateChange

Called after a state, identified by the uChange parameter, has changed in the IShellView interface.

HRESULT OnStateChange(
    IShellView *ppshv,
    ULONG uChange
   );

Parameters

ppshv
A pointer to the view's IShellView interface.
uChange
Change in the selection state. This parameter can be one of the following values:
Value | Description
CDBOSC_SETFOCUS | The focus has been set to the view.
CDBOSC_KILLFOCUS | The view has lost the focus.
CDBOSC_SELCHANGE | The selection has changed.
CDBOSC_RENAME | An item has been renamed.

Remarks

This method is used to let the common file dialog boxes track the state of the view and change its user interface as needed.

Note to Callers

When items in the view are selected, or when the view loses the focus, it needs to call this method to notify the common dialog that either the view state or selection state is changing.

See Also

ICommDlgBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


ICommDlgBrowser2

The ICommDlgBrowser2 interface extends the capabilities of ICommDlgBrowser. It is used by the common file dialog boxes when they host a Shell browser. A pointer to ICommDlgBrowser2 can be obtained by calling QueryInterface on the IShellBrowser object.

When to Implement

This interface is implemented only by common file dialog boxes.

When to Use

Use ICommDlgBrowser2 when your Shell view is hosted inside a common dialog box.

ICommDlgBrowser2 implements all the ICommDlgBrowser methods, as well as IUnknown. The following methods are specific to ICommDlgBrowser2.

Method | Description
GetDefaultMenuText | Called by the Shell view to get the default shortcut menu text.
GetViewFlags | Called by the Shell view to ask the common dialog box hosting it if all files, including system and hidden files, should be displayed.
Notify | Called by a Shell view to notify the common dialog box hosting it that an event has occurred.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


ICommDlgBrowser2::GetDefaultMenuText

Called by the Shell view to get the default shortcut menu text.

HRESULT GetDefaultMenuText(
    IShellView *pshv,
    WCHAR pszText,
    int cchMax
);

Parameters

pshv
Pointer to the IShellView interface of the hosted view.
pszText
Buffer that is used by the Shell browser to return the default shortcut menu text.
cchMax
Size of the pszText buffer. It should be at least the maximum allowable path length (MAX_PATH) in size.

Return Values

Returns S_OK if a new default shortcut menu text was returned in pshv. If S_FALSE is returned, use the normal default text. Otherwise, returns a standard COM error value.

See Also

ICommDlgBrowser2

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


ICommDlgBrowser2::GetViewFlags

Called by the Shell view to ask the common dialog box hosting it if all files, including system and hidden files, should be displayed.

HRESULT GetViewFlags(
    DWORD *pdwFlags
);

Parameters

pdwFlags
Pointer to a flag value that indicates which files should be shown. If it is set to CDB2GVF_SHOWALLFILES, all files, including hidden and system files, should be shown. Otherwise, it is set to NULL.

Return Values

Returns S_OK if successful, or a standard COM error value otherwise.

See Also

ICommDlgBrowser2

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


ICommDlgBrowser2::Notify

Called by a Shell view to notify the common dialog box hosting it that an event has occurred.

HRESULT Notify(
    IShellView *pshv,
    DWORD dwNotifyType
);

Parameters

pshv
Pointer to the IShellView interface of the hosted view.
dwNotifyType
Flag that can can take one of two values:
CDB2N_CONTEXTMENU_START | Indicates that the shortcut menu is about to be displayed.
CDB2N_CONTEXTMENU_DONE | Indicates that the shortcut menu is no longer displayed.

Return Values

Returns S_OK if successful, or a standard COM error value otherwise.

See Also

ICommDlgBrowser2

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IContextMenu

The IContextMenu interface is called by the Shell to either create or merge a shortcut menu associated with a Shell object.

When to Implement

Implement IContextMenu in the following situations:

  • Shell Extension Handlers implement this interface to dynamically add items to a Shell object's shortcut menu.
  • Namespace extensions implement this interface to specify their object's shortcut menus.

For a detailed discussion of how to implement IContextMenu, see Creating Shortcut Menu Handlers.

When to Use

Applications use IContextMenu to retrieve information about the items in an object's shortcut menu and to invoke the associated commands. To retrieve an object's IContextMenu interface, an application must call the object's IShellFolder::GetUIObjectOf method.

Methods

GetCommandString | Retrieves a command's language-independent name or its Help text. The language-independent name is also referred to as a verb.
InvokeCommand | Carries out the command associated with a shortcut menu item.
QueryContextMenu | Adds commands to a shortcut menu.

Remarks

Shell extension handlers that export this interface must also export IShellExtInit. For details, see Creating Shell Extension Handlers.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IContextMenu::GetCommandString

Retrieves information about a shortcut menu command, including the Help string and the language-independent, or canonical, name for the command.

HRESULT GetCommandString(
    UINT idCmd,
    UINT uFlags,
    UINT *pwReserved,
    LPSTR pszName,
    UINT cchMax
   );

Parameters

idCmd
Menu command identifier offset.
uFlags
Flags specifying the information to return. This parameter can have one of the following values.
GCS_HELPTEXTA | Sets pszName to an ANSI string containing the Help text for the command.
GCS_HELPTEXTW | Sets pszName to a Unicode string containing the Help text for the command.
GCS_VALIDATEA | Returns S_OK if the menu item exists, or S_FALSE otherwise.
GCS_VALIDATEW | Returns S_OK if the menu item exists, or S_FALSE otherwise.
GCS_VERBA | Sets pszName to an ANSI string containing the language-independent command name for the menu item.
GCS_VERBW | Sets pszName to a Unicode string containing the language-independent command name for the menu item.
pwReserved
Reserved. Applications must specify NULL when calling this method, and handlers must ignore this parameter when called.
pszName
Address of the buffer to receive the null-terminated string being retrieved.
cchMax
Size of the buffer to receive the null-terminated string.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The language-independent command name, or verb, is a name that can be passed to the IContextMenu::InvokeCommand method to activate a command by an application. The Help text is a description of the command that Microsoft® Windows® Explorer displays in its status bar. It should be reasonably short (under 40 characters).

Several common verbs can be identified by their canonical name, for instance, open, print, delete, and rename. Clients can compare the string pointed to by pszName against these canonical names to check for their presence on the shortcut menu.

Even though pszName is declared as an LPSTR, you must cast it to LPWSTR and return a Unicode string if uFlags is set to either GCS_HELPTEXTW or GCS_VERBW.

See Also

IContextMenu

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IContextMenu::InvokeCommand

Carries out the command associated with a shortcut menu item.

HRESULT InvokeCommand(
    LPCMINVOKECOMMANDINFO pici
   );

Parameters

pici
Pointer to a CMINVOKECOMMANDINFO or CMINVOKECOMMANDINFOEX structure containing information about the command. For further details, see the Remarks section.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The IContextMenu interface is exported by several Shell extension handlers and namespace extensions to add commands to shortcut menus. When the user selects one of the commands that the handler or namespace extension added to a shortcut menu, the Shell calls its InvokeCommand method. The command can be specified by its menu identifier offset, defined when IContextMenu::QueryContextMenu was called, or by its associated verb. An application can invoke this method directly by obtaining a pointer to an object's IContextMenu interface. An application can also invoke this method indirectly by calling ShellExecute or ShellExecuteEx and specifying a verb that is supported by the namespace extension or handler.

Although the pici parameter is declared in Shlobj.h as a CMINVOKECOMMANDINFO structure, in practice it often points to a CMINVOKECOMMANDINFOEX structure. This structure is an extended version of CMINVOKECOMMANDINFO and has several additional members that allow Unicode strings to be passed.

Note to Users

You can pass either structure to IContextMenu::InvokeCommand. Either will work for ANSI strings, but you must use a CMINVOKECOMMANDINFOEX structure for Unicode strings.

Note to Implementers

Check the cbSize member of pici to determine which structure was passed in. If it is a CMINVOKECOMMANDINFOEX structure and the fMask member has the CMIC_MASK_UNICODE flag set, you must cast pici to CMINVOKECOMMANDINFOEX to use the Unicode information contained in the last five members of the structure.

See Also

IContextMenu

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IContextMenu::QueryContextMenu

Adds commands to a shortcut menu.

HRESULT QueryContextMenu(
    HMENU hmenu,
    UINT indexMenu,
    UINT idCmdFirst,
    UINT idCmdLast,
    UINT uFlags
);

Parameters

hmenu
Handle to the menu. The handler should specify this handle when adding menu items.
indexMenu
Zero-based position at which to insert the first menu item.
idCmdFirst
Minimum value that the handler can specify for a menu item identifier.
idCmdLast
Maximum value that the handler can specify for a menu item identifier.
uFlags
Optional flags specifying how the shortcut menu can be changed. This parameter can be set to any combination of the following values.
CMF_CANRENAME | This flag is set if the calling application supports renaming of items. A shortcut menu extension or drag-and-drop handler should ignore this flag. A namespace extension should add a rename item to the menu if applicable.
CMF_DEFAULTONLY | This flag is set when the user is activating the default action, typically by double-clicking. This flag provides a hint for the shortcut menu extension to add nothing if it does not modify the default item in the menu. A shortcut menu extension or drag-and-drop handler should not add any menu items if this value is specified. A namespace extension should add only the default item (if any).
CMF_EXPLORE | This flag is set when the Microsoft® Windows® Explorer tree window is present.
CMF_EXTENDEDVERBS | This flag is set when the calling application wants extended verbs. Normal verbs are displayed when the user right-clicks an object. To display extended verbs, the user must right-click while pressing the SHIFT key.
CMF_INCLUDESTATIC | This flag is set when a static menu is being constructed. Only the browser should use this flag. All other shortcut menu extensions should ignore this flag.
CMF_NODEFAULT | This flag is set if no item in the menu should be the default item. A drag-and-drop handler should ignore this flag. A namespace extension should not set any of the menu items to the default.
CMF_NORMAL | Indicates normal operation. A shortcut menu extension, namespace extension, or drag-and-drop handler can add all menu items.
CMF_NOVERBS | This flag is set for items displayed in the Send To menu. Shortcut menu handlers should ignore this value.
CMF_VERBSONLY | This flag is set if the shortcut menu is for a shortcut object. Shortcut menu handlers should ignore this value.

The remaining bits of the low-order word are reserved by the system. The high-order word can be used for context-specific communications. The CMF_RESERVED value can be used to mask out the low-order word.

Return Values

If successful, returns an HRESULT value that has its severity value set to SEVERITY_SUCCESS and its code value set to the offset of the largest command identifier that was assigned, plus one. For example, assume that idCmdFirst is set to 5 and you add three items to the menu with command identifiers of 5, 7, and 8. The return value should be MAKE_HRESULT(SEVERITY_SUCCESS, 0, 8 - 5 + 1). Otherwise, it returns an OLE error value.

Remarks

This method should call either InsertMenu or InsertMenuItem to insert its menu items into the menu specified by hMenu. The indexMenu parameter holds the index that should be used for the first menu item. The identifier of each menu item must fall within the range defined by idCmdFirst and idCmdLast.

A common practice is to set the first command identifier to idCmdFirst (an offset of zero) and increment the offset for each additional command by one. This practice ensures that you do not exceed idCmdLast and preserves the range of identifiers that are available for use by other handlers. Store the offsets for future reference because they can be used to identify the command in subsequent calls to IContextMenu::GetCommandString and IContextMenu::InvokeCommand.

If the Shell subsequently calls another shortcut menu handler, it will use the code value of the returned HRESULT to set idCmdFirst when it calls that handler's QueryContextMenu method.

See Also

IContextMenu

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IContextMenu2

The IContextMenu2 interface is used to either create or merge a shortcut menu associated with a certain object when the menu involves owner-drawn menu items.

When to Implement

Implement IContextMenu2 if your namespace extension or shortcut menu handler needs to process one or more of the following messages:

  • WM_INITMENUPOPUP
  • WM_DRAWITEM
  • WM_MEASUREITEM

These messages are forwarded to IContextMenu2—through the HandleMenuMsg method—only if a QueryInterface call for an IContextMenu2 interface pointer is successful, indicating that the object supports this interface.

When to Use

Applications do not normally call this interface directly.

Methods

IContextMenu2 is derived from IContextMenu. The following method is specific to IContextMenu2.

HandleMenuMsg Handles messages related to drawing owner-drawn menu items.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IContextMenu2::HandleMenuMsg

Allows client objects of the IContextMenu interface to handle messages associated with owner-drawn menu items.

HRESULT HandleMenuMsg(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam
   );

Parameters

uMsg
Message to be processed. If it is WM_INITPOPUP, WM_DRAWITEM, WM_MENUCHAR,or WM_MEASUREITEM, the client object being called may provide owner-drawn menu items.
wParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.
lParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

HandleMenuMsg is called when a client of IContextMenu determines that the IContextMenu2 interface is supported and receives one of the messages specified in the description of the uMsg parameter.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IContextMenu3

The IContextMenu3 interface is used to create or merge a shortcut menu associated with a certain object when the menu implementation needs to process the WM_MENUCHAR message.

When to Implement

Implement IContextMenu3 if your shortcut menu extension needs to process the WM_MENUCHAR message.

These messages are forwarded to IContextMenu3—through the HandleMenuMsg2 method—only if a QueryInterface call for an IContextMenu3 interface pointer is successful, indicating that the object supports this interface.

When to Use

You do not call this interface directly. IContextMenu3 is used by the operating system only when it has confirmed that your application is aware of this interface.

IContextMenu3 is derived from IContextMenu2. The following method is specific to IContextMenu3:
IContextMenu3 Method | Description
HandleMenuMsg2 | Called when the window that owns the menu receives a WM_MENUCHAR message.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IContextMenu3::HandleMenuMsg2

Allows shortcut menu handlers to process the WM_MENUCHAR message.

HRESULT HandleMenuMsg2(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT *plResult
);

Parameters

uMsg
Message to be processed. At the present time, this method is only called for WM_MENUCHAR.
wParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.
lParam
Additional message information. The value of this parameter depends on the value of the uMsg parameter.
plResult
Address of an LRESULT value that the owner of the menu will return from the message.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

HandleMenuMsg2 is called when a client of IContextMenu determines that the IContextMenu3 interface is supported and receives one of the messages specified in the description of the uMsg parameter.

See Also

IContextMenu2

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ICopyHook

ICopyHook is a COM-based interface used to create a copy hook handler. A copy hook handler is a Shell extension that determines if a Shell folder or printer object can be moved, copied, renamed, or deleted. The Shell calls the ICopyHook::CopyCallback method prior to performing one of these operations.

The copy hook handler, which is an OLE in-process server (a DLL), does not perform the task itself, but it does approve or disapprove the action. If the Shell receives approval from the copy hook handler, it performs the file system operation. Copy hook handlers are not informed about the success of an operation, so they cannot monitor actions taken on folder objects unless FindFirstChangeNotification is used.

A folder object can have multiple copy hook handlers. For example, even if the Shell already has a copy hook handler registered for a particular folder object, you can still register one of your own. If two or more copy hook handlers are registered for an object, the Shell simply calls each of them before performing one of the specified file system operations.

The Shell initializes ICopyHook directly, without using the IShellExtInit interface first.

CopyCallback returns an integer value that indicates whether or not the Shell should perform the operation. The Shell will call each copy hook handler registered for a folder object until all the handlers have been called or until one of them has returned a value other than IDYES. The handler returns IDYES to specify that the operation should be performed, or IDNO or IDCANCEL to specify that the operation should be discontinued.

When to Implement

Implement a copy hook handler when you want to be able to control when, or if, these file system operations are performed on a given object. You might want to use a copy hook handler on shared folders, for example.

When to Use

You do not call this Shell extension directly. ICopyHook::CopyCallback is called by the Shell prior to moving, copying, deleting, or renaming a Shell folder object.

Method | Description
CopyCallback | Determines whether a move, copy, delete, or rename operation on a folder object should be allowed or disallowed.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


ICopyHook::CopyCallback

Determines whether the Shell will be allowed to move, copy, delete, or rename a folder or printer object.

UINT CopyCallback(
    HWND hwnd,
    UINT wFunc,
    UINT wFlags,
    LPCSTR pszSrcFile,
    DWORD dwSrcAttribs,
    LPCSTR pszDestFile,
    DWORD dwDestAttribs
   );

Parameters

hwnd
Handle to the window that the copy hook handler should use as the parent for any user interface elements the handler may need to display. If FOF_SILENT is specified, the method should ignore this parameter.
wFunc
Operation to perform. This parameter can be one of the values listed under the wFunc member of the SHFILEOPSTRUCT structure.
wFlags
Flags that control the operation. This parameter can be one or more of the values listed under the fFlags member of the SHFILEOPSTRUCT structure.
pszSrcFile
Address of a string that contains the name of the source folder.
dwSrcAttribs
Attributes of the source folder. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Microsoft® Windows® header files.
pszDestFile
Address of a string that contains the name of the destination folder.
dwDestAttribs
Attributes of the destination folder. This parameter can be a combination of any of the file attribute flags (FILE_ATTRIBUTE_*) defined in the Windows header files.

Return Values

Returns an integer value that indicates whether or not the Shell should perform the operation. It can be one of the following:

Value | Description
IDYES | Allows the operation.
IDNO | Prevents the operation on this folder but continues with any other operations that have been approved (for example, a batch copy operation).
IDCANCEL | Prevents the current operation and cancels any pending operations.

Remarks

The Shell calls each copy hook handler registered for a folder or printer object until all the handlers have been called or until one of them returns IDNO or IDCANCEL.

Copy hook handlers for folders are registered under HKEY_CLASSES_ROOT\Directory\Shellex\CopyHookHandlers\your_copyhook\{copyhook CLSID value}. Copy hook handlers for printers are registered under HKEY_CLASSES_ROOT\Printers\Shellex\CopyHookHandlers\your_copyhook\{copyhook CLSID value}

When this method is called, the Shell initializes the ICopyHook interface directly without using an IShellExtInit interface first.

See Also

SHFileOperation

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


ICurrentWorkingDirectory

The ICurrentWorkingDirectory interface allows a client to retrieve or set an object's current working directory.

When to Implement

Implement this interface if your object allows clients to retrieve or set the current working directory.

When to Use

Use this interface to retrieve or set the working directory of the object that exports it.

Methods

ICurrentWorkingDirectory exposes the following methods in addition to IUnknown.

GetDirectory | Retrieves the current working directory.
SetDirectory | Sets the current working directory.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


ICurrentWorkingDirectory::GetDirectory

Retrieves the current working directory.

HRESULT GetDirectory(
    LPWSTR pwzPath,
    DWORD cchSize
);

Parameters

pwzPath
[out] Address of a buffer. On return, it will hold a NULL-terminated Unicode string with the current working directory's fully qualified path.
cchSize
[in] Size of the buffer in Unicode characters, including the terminating NULL character.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

ICurrentWorkingDirectory

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


ICurrentWorkingDirectory::SetDirectory

Sets the current working directory.

HRESULT SetDirectory(
    LPCWSTR pwzPath
);

Parameters

pwzPath
[in] Address of a NULL-terminated Unicode string with the fully qualified path of the new working directory.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

ICurrentWorkingDirectory

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDeskBand

IDeskBand is used to obtain information about a band object. See Band Objects for more information about band objects.

When to Implement

Implement IDeskBand if you are implementing a band object.

When to Use

You do not call this interface directly. IDeskBand is used by the Shell or the browser to obtain display information for a band object.

IDeskBand is derived from IDockingWindow. The following method is specific to IDeskBand.
IDeskBand Method | Description
GetBandInfo | Retrieves the information for a band object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDeskBand::GetBandInfo

Retrieves the information for a band object.

HRESULT GetBandInfo(
    DWORD dwBandID,
    DWORD dwViewMode,
    DESKBANDINFO* pdbi
);

Parameters

dwBandID
Identifier of the band. The container assigns this identifier. The band object can keep this value if it is required.
dwViewMode
View mode of the band object. This will be one of the following values:
DBIF_VIEWMODE_NORMAL | The band object is being displayed in a horizontal band.
DBIF_VIEWMODE_VERTICAL | The band object is being displayed in a vertical band.
DBIF_VIEWMODE_FLOATING | The band object is being displayed in a floating band.
DBIF_VIEWMODE_TRANSPARENT | The band object is being displayed in a transparent band.
pdbi
Address of a DESKBANDINFO structure that receives the band information for the object. The dwMask member of this structure indicates what information is being requested.

Return Value

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindow

The IDockingWindow interface is implemented by window objects that can be docked within the border space of a Windows Explorer window.

When to Implement

You implement IDockingWindow when you want to display a window inside a browser frame. This is normally used for user interface windows, such as toolbars.

When to Use

You do not normally use the IDockingWindow interface. The Shell browser uses this interface to support docked windows inside the browser frame.

IDockingWindow is derived from IOleWindow. The following are the methods specific to IDockingWindow.
IDockingWindow Method | Description
CloseDW | Notifies the docking window object that it is about to be removed.
ResizeBorderDW | Notifies the docking window object that the frame's border space has changed.
ShowDW | Instructs the docking window object to show or hide itself.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindow::CloseDW

Notifies the docking window object that it is about to be removed from the frame. The docking window object should save any persistent information at this time.

HRESULT CloseDW(
    DWORD dwReserved
);

Parameters

dwReserved
Reserved. This parameter should always be zero.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IDockingWindow, IDockingWindowFrame, IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindow::ResizeBorderDW

Notifies the docking window object that the frame's border space has changed. In response to this method, the IDockingWindow implementation must call IDockingWindowSite::SetBorderSpaceDW, even if no border space is required or a change is not necessary.

HRESULT ResizeBorderDW(
    LPCRECT prcBorder,
    IUnknown* punkToolbarSite,
    BOOL fReserved
);

Parameters

prcBorder
Address of a RECT structure that contains the frame's available border space.
punkToolbarSite
Address of the site's IUnknown interface. The docking window object should call the QueryInterface method for this interface, requesting IID_IShellToolbarSite, and use that interface to negotiate its border space. It is the docking window object's responsibility to release this interface when it is no longer needed.
fReserved
Reserved. This parameter should always be zero.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The prcBorder parameter will contain the frame's entire available border space. The docking window object should negotiate its border space and then use this information to position itself.

For example, if the docking window object requires 25 pixels at the top of the border space, it should negotiate for this by allocating a BORDERWIDTHS structure, setting the top member to 25, calling IDockingWindowSite::RequestBorderSpaceDW, and then calling IDockingWindowSite::SetBorderSpaceDW. The docking window object can then position its window at prcBorder->left and prcBorder->top. The width of the docking window object's window is determined from prcBorder->right - prcBorder->left, and its height is contained in the top member of the BORDERWIDTHS structure.

See Also

IDockingWindow, IDockingWindowFrame, IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindow::ShowDW

Instructs the docking window object to show or hide itself.

HRESULT ShowDW(
    BOOL bShow
);

Parameters

bShow
Boolean value indicating whether the docking window object should show or hide itself. If this parameter is nonzero, the docking window object should show its window. If it is zero, the docking window object should hide its window and return its border space by calling IDockingWindowSite::SetBorderSpaceDW with all zeros.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IDockingWindow, IDockingWindowFrame, IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowFrame

The IDockingWindowFrame interface is implemented by the browser to support adding IDockingWindow objects to a frame.

When to Implement

You do not normally implement the IDockingWindowFrame interface. The Shell browser implements this interface to support docked windows inside the browser frame.

When to Use

You use IDockingWindowFrame to add, find, and remove docking window objects in a browser frame.

IDockingWindowFrame is derived from IOleWindow. The following are the methods specific to IDockingWindowFrame.
IDockingWindowFrame Methods | Description
AddToolbar | Adds an IDockingWindow object to a frame.
FindToolbar | Finds an IDockingWindow object in a frame.
RemoveToolbar | Removes an IDockingWindow object from a frame.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowFrame::AddToolbar

Adds the specified IDockingWindow object to the frame.

HRESULT AddToolbar(
    IUnknown* punkSrc,
    LPCWSTR pwszItem,
    DWORD dwAddFlags
);

Parameters

punkSrc
Address of the IDockingWindow object to be added.
pwszItem
Address of a null-terminated UNICODE string. This is an application-defined string used for identifying the docking window object.
dwAddFlags
Flags for the docking window object being added. This can be one or more of the following values:
0 | The docking window is a regular, visible docking window.
DWFAF_HIDDEN | The docking window is added but is not shown. To show it at a later time, call its IDockingWindow::ShowDW method.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

IDockingWindowFrame, IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowFrame::FindToolbar

Finds the specified IDockingWindow object in the toolbar frame and returns an interface pointer to it.

HRESULT FindToolbar(
    LPCWSTR pwszItem,
    REFIID riid,
    LPVOID* ppvObj
);

Parameters

pwszItem
Address of a null-terminated UNICODE string. This is the same string that was passed to the AddToolbar method.
riid
Identifier of the desired COM interface.
ppvObj
Address to receive the interface pointer. If an error occurs, a NULL pointer is placed in this address.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

IDockingWindowFrame, IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowFrame::RemoveToolbar

Removes the specified IDockingWindow from the toolbar frame.

HRESULT RemoveToolbar(
    IUnknown* punkSrc,
    DWORD dwRemoveFlags
);

Parameters

punkSrc
Address of the IDockingWindow object to be removed. The IDockingWindowFrame implementation will call the IDockingWindow::CloseDW and Release methods.
dwRemoveFlags
Option flags for removing the docking window object. This parameter can be one or more of the following values:
DWFRF_NORMAL | The default delete processing is performed.
DWFRF_DELETECONFIGDATA | In addition to deleting the toolbar, any configuration data is removed as well.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowSite

The IDockingWindowSite interface is implemented by the browser to manage the border space for one or more IDockingWindow objects. This interface is similar to the IOleInPlaceUIWindow interface.

When to Implement

You do not normally implement the IDockingWindowSite interface. The Shell browser implements this interface to support docked windows inside the browser frame.

When to Use

You use IDockingWindowSite to negotiate the space for a docking window object in a browser frame.

IDockingWindowSite is derived from IOleWindow. The following are the methods specific to IDockingWindowSite.
IDockingWindowSite Methods | Description
GetBorderDW | Retrieves the allocated border space for a particular IDockingWindow object.
RequestBorderSpaceDW | Processes border space requests for an IDockingWindow object.
SetBorderSpaceDW | Allocates border space for an IDockingWindow object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowSite::GetBorderDW

Retrieves the border space allocated for the specified IDockingWindow object.

HRESULT GetBorderDW(
    IUnknown* punkSrc,
    LPRECT prcBorder
);

Parameters

punkSrc
Address of the IDockingWindow object for which the border space is being requested.
prcBorder
Address of a RECT structure to receive the entire available border space for the browser. The docking window object should use this information to determine where to place itself. See the IDockingWindow::ResizeBorderDW method for more information.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

IDockingWindowFrame, IDockingWindowSite

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowSite::RequestBorderSpaceDW

Approves, modifies, or refuses a request for an IDockingWindow object's border space. The border space is not allocated until the SetBorderSpaceDW method is called.

HRESULT RequestBorderSpaceDW(
    IUnknown* punkSrc,
    LPCBORDERWIDTHS pbw
);

Parameters

punkSrc
Address of the IDockingWindow object for which the border space is being requested.
pbw
Address of a BORDERWIDTHS structure. Before calling this method, the structure must be filled with the desired border space. After the method's successful completion, the structure will contain the approved border space. The IDockingWindowSite object may change these values. If border space is critical, it is the caller's responsibility to determine if the returned border space is sufficient.

Return Values

Returns NOERROR if the border space request is approved or modified, or an OLE-defined error code otherwise.

See Also

IDockingWindowFrame

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDockingWindowSite::SetBorderSpaceDW

Allocates and reserves border space for an IDockingWindow object.

HRESULT SetBorderSpaceDW(
    IUnknown* punkSrc,
    LPCBORDERWIDTHS pbw
);

Parameters

punkSrc
Address of the IDockingWindow object for which the border space is being set.
pbw
Address of a BORDERWIDTHS structure that contains the IDockingWindow object's border space. The border space should have been approved by IDockingWindowSite through a successful call to the RequestBorderSpaceDW method.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

IDockingWindowFrame

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IDragSourceHelper

This interface is exposed by the Shell to allow an application to specify the image that will be displayed during a Shell drag-and-drop operation.

When to Implement

This interface is exposed by the Shell's drag-image manager. It is not implemented by applications.

When to Use

Use this interface when you want to specify the image that will be displayed during a Shell drag-and-drop operation. The IDragSourceHelper and IDropTargetHelper interfaces are exposed by the drag-image manager object to allow the IDropTarget interface to use custom drag images. To use either of these interfaces, you must create an in-process server drag-image manager object by calling CoCreateInstance with a CLSID of CLSID_DragDropHelper. Get interface pointers using standard COM procedures.

The IDragSourceHelper interface provides two alternative ways to specify the bitmap to be used as a drag image:

  • Controls that have a window can register a DI_GETDRAGIMAGE window message for it and initialize the drag-image manager with IDragSourceHelper::InitializeFromWindow. When the DI_GETDRAGIMAGE message is received, the handler puts the drag image bitmap information in the SHDRAGIMAGE structure that is passed as the message's lParam value.
  • Windowless controls can initialize the drag-image manager with IDragSourceHelper::InitializeFromBitmap. This method allows an application to simply specify the bitmap.

Note: The drag-and-drop helper object calls IDataObject::SetData to load private formats—used for cross-process support—into the data object. It later retrieves these formats by calling IDataObject::GetData. To support the drag-and-drop helper object, the data object's SetData and GetData implementations must be able to accept and return arbitrary private formats.

For further discussion of Shell drag-and-drop operations, see Transferring Shell Data Using Drag-and-Drop or the Clipboard.

Methods

IDragSourceHelper exposes the following methods in addition to IUnknown.

InitializeFromBitmap | Initializes the drag-image manager for a windowless control.
InitializeFromWindow | Initializes the drag-image manager for a control with a window.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDragSourceHelper::InitializeFromBitmap

Initializes the drag-image manager for a windowless control.

HRESULT InitializeFromBitmap(
    LPSHDRAGIMAGE pshdi,
    IDataObject *pDataObject
);

Parameters

pshdi
[in] SHDRAGIMAGE structure that contains information about the bitmap.
pDataObject
[in] Pointer to the data object's IDataObject interface.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IDragSourceHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDragSourceHelper::InitializeFromWindow

Initializes the drag-image manager for a control with a window.

HRESULT InitializeFromWindow(
    HWND hwnd,
    POINT *ppt,
    IDataObject *pDataObject
);

Parameters

hwnd
[in] Handle to the window that will receive the DI_GETDRAGIMAGE message.
ppt
[in] Pointer to a POINT structure that specifies the location of the cursor within the drag image. The structure should contain the offset from the upper-left corner of the drag image to the location of the cursor.
pDataObject
[in] Pointer to the data object's IDataObject interface.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

The DI_GETDRAGIMAGE message allows you to source a drag image from a custom control. It is defined in Shlobj.h and must be registered with RegisterWindowMessage. When the window specified by hwnd receives the DI_GETDRAGIMAGE message, the lParam value will hold a pointer to an SHDRAGIMAGE structure. The handler should fill the structure with the drag image bitmap information.

See Also

IDragSourceHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDropTargetHelper

This interface allows drop targets to display a drag image while the image is over the target window.

When to Implement

This interface is exposed by the Shell's drag-image manager. It is not implemented by applications.

When to Use

This interface is used by drop targets to have the drag-image manager display the drag image while the image is over the target window. The IDragSourceHelper and IDropTargetHelper interfaces are exposed by the drag-image manager object to allow the IDropTarget interface to use custom drag images. To use either of these interfaces, you must create an in-process server drag-image manager object by calling CoCreateInstance with a CLSID of CLSID_DragDropHelper. Get interface pointers using standard COM procedures.

Four of the IDropTargetHelper methods correspond to the four IDropTarget methods. When you implement IDropTarget, each of its methods should call the corresponding IDropTargetHelper method to pass the information to the drag-image manager. The fifth IDropTargetHelper method notifies the drag-image manager to show or hide the drag image. This method is used when dragging over a target window in a low color-depth video mode. It allows the target to hide the drag image while it is painting the window.

Note: The drag-and-drop helper object calls IDataObject::SetData to load private formats—used for cross-process support—into the data object. It later retrieves these formats by calling IDataObject::GetData. To support the drag-and-drop helper object, the data object's SetData and GetData implementations must be able to accept and return arbitrary private formats.

For further discussion of Shell drag-and-drop operations, see Transferring Shell Data Using Drag-and-Drop or the Clipboard.

Methods

IDropTargetHelper exposes the following methods in addition to IUnknown.

DragEnter | Notifies the drag-image manager that the drop target's IDropTarget::DragEnter method has been called.
DragLeave | Notifies the drag-image manager that the drop target's IDropTarget::DragLeave method has been called.
DragOver | Notifies the drag-image manager that the drop target's IDropTarget::DragOver method has been called.
Drop | Notifies the drag-image manager that the drop target's IDropTarget::Drop method has been called.
Show | Notifies the drag-image manager to show or hide the drag image.

See Also

IDragSourceHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDropTargetHelper::DragEnter

Notifies the drag-image manager that the drop target's IDropTarget::DragEnter method has been called.

HRESULT DragEnter(
    HWND hwndTarget,
    IDataObject *pDataObject,
    POINT *ppt,
    DWORD dwEffect
);

Parameters

hwndTarget
[in] Target's window handle.
pDataObject
[in] Pointer to the data object's IDataObject interface.
ppt
[in] POINT structure pointer that was received in the IDropTarget::DragEnter method's ppt parameter.
dwEffect
[in] Value pointed to by the IDropTarget::DragEnter method's pdwEffect parameter.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method is called by a drop target when its IDropTarget::DragEnter method is called. It notifies the drag-image manager that the drop target has been entered, and provides it with the information needed to display the drag image.

See Also

IDropTargetHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDropTargetHelper::DragLeave

Notifies the drag-image manager that the drop target's IDropTarget::DragLeave method has been called.

HRESULT DragLeave( VOID );

Parameters

None.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method is called by a drop target when its IDropTarget::DragLeave method is called. It notifies the drag-image manager that the cursor has left the drop target.

See Also

IDropTargetHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDropTargetHelper::DragOver

Notifies the drag-image manager that the drop target's IDropTarget::DragOver method has been called.

HRESULT DragOver(
    POINT *ppt,
    DWORD dwEffect
);

Parameters

ppt
[in] POINT structure pointer that was received in the IDropTarget::DragOver method's pt parameter.
dwEffect
[in] Value pointed to by the IDropTarget::DragOver method's pdwEffect parameter.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method is called by a drop target when its IDropTarget::DragOver method is called. It notifies the drag-image manager that the cursor position has changed, and provides it with the information needed to display the drag image.

See Also

IDropTargetHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDropTargetHelper::Drop

Notifies the drag-image manager that the drop target's IDropTarget::Drop method has been called.

HRESULT Drop(
    IDataObject *pDataObject,
    POINT *ppt,
    DWORD dwEffect
);

Parameters

pDataObject
[in] Pointer to the data object's IDataObject interface.
ppt
[in] POINT structure pointer that was received in the IDropTarget::Drop method's pt parameter.
dwEffect
[in] Value pointed to by the IDropTarget::Drop method's pdwEffect parameter.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method is called by a drop target when its IDropTarget::Drop method is called. It notifies the drag-image manager that the object has been dropped, and provides it with the information needed to display the drag image.

See Also

IDropTargetHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IDropTargetHelper::Show

Notifies the drag-image manager to show or hide the drag image.

HRESULT Show(
    BOOL fShow
);

Parameters

fShow
[in] Boolean value that is set to TRUE to show the drag image, and FALSE to hide it.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method is used when dragging over a target window in a low color-depth video mode. It allows the target to have the drag-image manager hide the drag image while it is painting the window. While you are painting a window that is currently being dragged over, hide the drag image by calling Show with fShow set to FALSE. Once the window has been painted, display the drag image again by calling Show with fShow set to TRUE.

See Also

IDropTargetHelper

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IEmptyVolumeCache

This interface is used by the disk cleanup manager to communicate with a disk cleanup handler. Its methods allow the manager to request information from a handler, and notify it of events such as the start of a scan or purge.

When to Implement

This interface must be implemented by disk cleanup handlers running on Microsoft® Windows® 98. Handlers running on Microsoft® Windows 2000 should also expose IEmptyVolumeCache2.

Methods

Method | Description
Deactivate | Notifies the handler that the disk cleanup manager is shutting down.
GetSpaceUsed | Asks for the amount of disk space that the handler can free.
Initialize | Initializes the disk cleaner handler.
Purge | Notifies the handler to clean up its unessential files.
ShowProperties | Asks the handler to display its user interface (UI).

See Also

IEmptyVolumeCacheCallBack

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache::Deactivate

This method is used to notify the handler that the disk cleanup manager is shutting down.

HRESULT Deactivate(
  DWORD *pdwFlags
);

Parameters

dwFlags
[out] Flag that can be set to return information to the disk cleanup manager. It can have the following value:
EVCF_REMOVEFROMLIST
If this flag is set, the disk cleanup manager will delete the handler's registry subkey.

Return Values

S_OK This value should always be returned.

Remarks

If the EVCF_REMOVEFROMLIST flag is set, the handler will not be run again unless the registry entries are reestablished. This flag is typically used for a handler that will only run once.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache::GetSpaceUsed

This method requests the amount of disk space that the disk cleanup handler can free.

HRESULT GetSpaceUsed(
  DWORDLONG *pdwlSpaceUsed,
  IEmptyVolumeCacheCallback *picb
);

Parameters

pdwSpaceUsed
[out] Amount of disk space, in bytes, that the handler can free. This value will be displayed in the disk cleanup manager's list, to the right of the handler's check box. To indicate that you do not know how much disk space can be freed, set this parameter to -1, and "???MB" will be displayed. If you set the EVCF_DONTSHOWIFZERO flag when Initialize was called, setting pdwSpaceUsed to zero will notify the disk cleanup manager to omit the handler from its list.
picb
[in] Pointer to the disk cleanup manager's IEmptyVolumeCacheCallback interface. This pointer can be used to call that interface's ScanProgress method to report on the progress of the operation.

Return Values

S_OK | Success.
S_FALSE | An error occurred when the handler tried to calculate the amount of disk space that could be freed.
E_ABORT | The scan operation was ended prematurely. This value is usually returned when a call to IEmptyVolumeCache::ScanProgress returns E_ABORT. This return value indicates that the user cancelled the operation by clicking the disk cleanup manager's Cancel button.

Remarks

When this method is called by the disk cleanup manager, the handler should start scanning its files to determine which of them can be deleted, and how much disk space will be freed. Handlers should call IEmptyVolumeCache::ScanProgress periodically to keep the user informed of the progress of the scan, especially if it will take a long time. Calling this method frequently also allows the handler to determine whether the user has cancelled the operation. If ScanProgress returns E_ABORT, the user has cancelled the scan. The handler should immediately stop scanning and return E_ABORT.

You should only set the pdwSpaceUsed parameter to -1 as a last resort. The handler is of limited value to a user if they don't know how much space will be freed.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache::Initialize

This method is used to initialize the disk cleanup handler, based on the information stored under the specified registry key.

HRESULT Initialize(
  HKEY hkRegKey,
  LPCWSTR pcwszVolume,
  LPWSTR *ppwszDisplayName,
  LPWSTR *ppwszDescription,
  DWORD *pdwFlags
);

Parameters

hkRegKey
[in] Handle to the registry key that holds the information about the handler object.
pcwszVolume
[in] Pointer to a null-terminated Unicode string with the volume root—for example, "C:\".
ppwszDisplayName
[out] Pointer to a null-terminated Unicode string with the name that will be displayed in the disk cleanup manager's list of handlers. If no value is assigned, the registry value will be used.
ppwszDescription
[out] Pointer to a null-terminated Unicode string that will be displayed when this object is selected from the disk cleanup manager's list of available disk cleanup handlers. If no value is assigned, the registry value will be used.
pdwFlags
[in/out] Flags that are used to pass information to the handler, and back to the disk cleanup manager.

These flags can be passed in to the object:
EVCF_OUTOFDISKSPACE
If this flag is set, the user is out of disk space on the drive. When this flag is received, the handler should be aggressive about freeing disk space, even if it results in a performance loss. The handler, however, should not delete files that would cause an application to fail, or the user to lose data.
EVCF_SETTINGSMODE
If the disk cleanup manager is being run on a schedule, it will set this flag. You must assign values to the ppwszDisplayName and ppwszDescription parameters. If this flag is set, the disk cleanup manager will not call GetSpaceUsed, Purge, or ShowProperties. Because Purge will not be called, cleanup must be handled by Initialize. The handler should ignore the pcwszVolume parameter and clean up any unneeded files regardless of what drive they are on. Because there is no opportunity for user feedback, only those files that are extremely safe to clean up should be touched.

These flags can be passed by the handler back to the disk cleanup manager:
EVCF_DONTSHOWIFZERO
Set this flag when there are no files to delete. When IEmptyVolumeCache::GetSpaceUsed is called, set the pdwSpaceUsed parameter to zero, and the disk cleanup manager will omit the handler from its list.
EVCF_ENABLEBYDEFAULT
Set this flag to have the handler checked by default in the cleanup manager's list. It will run every time the Disk Cleanup utility runs, unless the user clears the handler's check box. Once the check box has been cleared, the handler will not be run until the user selects it again.
EVCF_ENABLEBYDEFAULT_AUTO
Set this flag to have the handler run automatically during scheduled cleanup. This flag should only be set when deletion of the files is low-risk. As with EVCF_ENABLEBYDEFAULT, the user can choose not to run the handler by clearing its check box in the disk cleanup manager's list.
EVCF_HASSETTINGS
Set this flag to indicate that the handler can display a user interface (UI). An example of a simple UI is a list box that displays the deletable files and allows the user to select which ones to delete. The disk cleanup manager will then display a button below the cleanup handler's description. The user clicks this button to request the UI. The default button text is "Settings", but the handler can specify a different text by setting the AdvancedButtonText value in its registry key.
EVCF_REMOVEFROMLIST
Set this flag to remove the handler from the disk cleanup manager's list. All registry information will be deleted, and the handler cannot be run again until the key and its values are restored. This flag is used primarily for one-time cleanup operations.

Return Values

S_OK | Success.
S_FALSE | There are no files to delete.
E_ABORT | The cleanup operation was ended prematurely.
E_FAIL | The cleanup operation failed.

Remarks

This method is used by the Microsoft® Windows® 98 disk cleanup manager. Microsoft® Windows 2000 uses the InitializeEx method exported by IEmptyVolumeCache2.

Use CoTaskMemAlloc to allocate memory for the strings returned through ppwszDisplayName and ppwszDescription. The disk cleanup manager will free the memory when it is no longer needed.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache::Purge

This method notifies the handler to start deleting its unneeded files.

HRESULT Purge(
  DWORDLONG dwlSpaceToFree,
  IEmptyVolumeCacheCallback *picb
);

Parameters

dwSpaceToFree
[in] Amount of disk space that the handler should free. If this parameter is set to -1, the handler should delete all its files.
picb
[in] Pointer to the disk cleanup manager's IEmptyVolumeCacheCallBack interface. This pointer can be used to call the interface's PurgeProgress method to report on the progress of the operation.

Return Values

S_OK | Success.
E_ABORT | The operation was ended prematurely. This value is usually returned when IEmptyVolumeCache::PurgeProgress returns E_ABORT. This typically happens when the user cancels the operation by clicking the disk cleanup manager's Cancel button.

Remarks

For Microsoft® Windows® 98, the dwSpaceToFree parameter is always set to the value specified by the handler when IEmptyVolumeCache::GetSpaceUsed was called.

In general, handlers should be kept simple and delete all their files when this function is called. If there are significant performance advantages to only deleting a portion of the files, the handler should implement the ShowProperties method. When called, this method displays a user interface (UI) that allows the user to select the files to be deleted.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache::ShowProperties

This method is used to notify the handler to display its user interface (UI).

HRESULT ShowProperties(
  HWND hwnd
);

Parameters

hwnd
[in] Parent window to be used when displaying the UI.

Return Values

S_OK | The user changed one or more settings.
S_FALSE | No settings were changed.

Remarks

A handler can display a UI, which is typically used to allow the user to select which files are to be cleaned up and how. To do so, the handler sets the EVCF_HASSETTINGS flag in the pdwFlags parameter when Initialize is called. The disk cleanup manager will then display a Settings button. When that button is clicked, the disk cleanup manager calls ShowProperties to notify the handler to display its UI.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache2

This interface extends IEmptyVolumeCache. It defines one additional method, InitializeEx, that provides better localization support than IEmptyVolumeCache::Initialize

When to Implement

This interface should be exported by disk cleanup handlers running on Microsoft® Windows NT® 5. Handlers running on Microsoft® Windows® 98 must export IEmptyVolumeCache.

Methods

In addition to the methods exported by IEmptyVolumeCache, IEmptyVolumeCache2 exports:

Method | Description
InitializeEx | Initializes the disk cleanup handler.

See Also

IEmptyVolumeCacheCallBack

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCache2::InitializeEx

This method is used to initialize the disk cleanup handler. It provides better support for localization than IEmptyVolumeCache::Initialize.

HRESULT InitializeEx(
  HKEY hkRegKey,
  LPCWSTR pcwszVolume,
  LPCWSTR pcwszKeyName,
  LPWSTR *ppwszDisplayName,
  LPWSTR *ppwszDescription,
  LPWSTR *ppwszBtnText,
  DWORD *pdwFlags
);

Parameters

hkRegKey
[in] Handle to the registry key that holds the information about the handler object.
pcwszVolume
[in] Pointer to a null-terminated Unicode string with the volume root—for example, "C:\".
pcwszKeyName
[in] Pointer to a null-terminated Unicode string with the name of the handler's registry key.
ppwszDisplayName
[out] Pointer to a null-terminated Unicode string with the name that will be displayed in the disk cleanup manager's list of handlers. You must assign a value to this parameter.
ppwszDescription
[out] Pointer to a null-terminated Unicode string that will be displayed when this object is selected from the disk cleanup manager's list of available disk cleaners. You must assign a value to this parameter.
ppwszBtnText
[out] Pointer to a null-terminated Unicode string with the text that will be displayed on the disk cleanup manager's Settings button. If the EVCF_HASSETTINGS flag is set, you must assign a value to ppwszBtnText. Otherwise, you can set it to NULL.
pdwFlags
[in/out] Flags that are used to pass information to the handler, and back to the disk cleanup manager.

These flags can be passed in to the object:
EVCF_OUTOFDISKSPACE
If this flag is set, the user is out of disk space on the drive. When this flag is received, the handler should be aggressive about freeing disk space, even if it results in a performance loss. The handler, however, should not delete files that would cause an application to fail or the user to lose data.
EVCF_SETTINGSMODE
If the disk cleanup manager is being run on a schedule, it will set the EVCF_SETTINGSMODE flag. You must assign values to the ppwszDisplayName and ppwszDescription parameters. If this flag is set, the disk cleanup manager will not call GetSpaceUsed, Purge, or ShowProperties . Because Purge will not be called, cleanup must be handled by InitializeEx. The handler should ignore the pcwszVolume parameter and clean up any unneeded files regardless of what drive they are on. Because there is no opportunity for user feedback, only those files that are extremely safe to clean up should be touched.

These flags can be passed by the handler back to the disk cleanup manager:
EVCF_DONTSHOWIFZERO
Set this flag when there are no files to delete. When IEmptyVolumeCache2::GetSpaceUsed is called, set the pdwSpaceUsed parameter to zero, and the disk cleanup
EVCF_ENABLEBYDEFAULT
Set this flag to have the handler checked by default in the disk cleanup manager's list. The handler will be run every time the disk cleanup utility runs, unless the user clears the handler's check box. Once the check box has been cleared, the handler will not be run until the user selects it again.
EVCF_ENABLEBYDEFAULT_AUTO
Set this flag to have the handler run automatically during scheduled cleanup. This flag should only be set when deletion of the files is low-risk. As with EVCF_ENABLEBYDEFAULT, the user can choose not to run the handler by clearing its check box in the disk cleanup manager's list.
EVCF_HASSETTINGS
Set this flag to indicate that the handler can display a user interface (UI). An example of a simple UI is a list box that displays the deletable files and allows the user to select which ones to delete. The disk cleanup manager will then display a button below the cleanup handler's description. The user clicks this button to request the UI. Use the ppwszBtnText parameter to specify the button's text.
EVCF_REMOVEFROMLIST
Set this flag to remove the handler from the disk cleanup manager's list. All registry information will be deleted, and the handler cannot be run again until the key and its values are restored. This flag is used primarily for one-time cleanup operations.

Return Values

S_OK | Success.
S_FALSE | There are no files to delete.
E_ABORT | The cleanup operation was ended prematurely.
E_FAIL | The cleanup operation failed.

Remarks

The Microsoft® Windows NT® 5 disk cleanup manager will first call IEmptyVolumeCache2::InitializeEx to initialize a disk cleanup handler. It will only call IEmptyVolumeCache::Initialize if the IEmptyVolumeCache2 interface is not implemented. The Microsoft® Windows® 98 disk cleanup manager only supports IEmptyVolumeCache::Initialize.

InitializeEx is intended to provide better localization support than Initialize. When InitializeEx is called, the handler application must assign appropriately localized values to the ppwszDisplayName and ppwszDescription parameters. If the Settings button is enabled, you must also assign a value to the ppwszBtnText parameter. Unlike Initialize, if you set these strings to NULL to notify the disk cleanup manager to retrieve the default values from the registry, InitializeEx will fail.

Use CoTaskMemAlloc to allocate memory for the strings returned through ppwszDisplayName, ppwszDescription, and ppwszBtnText. The disk cleanup manager will free the memory when it is no longer needed.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCacheCallBack

This interface is used by a disk cleanup handler to communicate with the disk cleanup manager.

When to Use

A disk cleanup handler uses this interface to report to the disk cleanup manager on the progress either of deleting files or of scanning for deletable files. It also provides a way to query the manager, to find out if the user has cancelled the operation. The handler receives a pointer to this interface when the manager calls the IEmptyVolumeCache::GetSpaceUsed or IEmptyVolumeCache::Purge methods.

Methods

Method | Description
PurgeProgress | Reports the progress of a purge of deletable files.
ScanProgress | Reports the progress of a scan of the file system for deletable files.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCacheCallback::PurgeProgress

This method is called periodically by a disk cleanup handler to update the disk cleanup manager on the progress of a purge of deletable files.

HRESULT PurgeProgress(
  DWORDLONG dwlSpaceFreed,
  DWORDLONG dwlSpaceToFree,
  DWORD dwFlags,
  LPCWSTR pcwszReserved
);

Parameters

dwSpaceFreed
[in] Amount of disk space, in bytes, that has been freed at this point in the purge. The disk cleanup manager uses this value to update its progress bar.
dwSpaceToFree
[in] Amount of disk space, in bytes, that remains to be freed at this point in the purge.
dwFlags
[in] Flag that can be sent to the disk cleanup manager. It can can have the following value:
EVCCBF_LASTNOTIFICATION
This flag should be set if the handler will not call this method again. It is typically set when the purge is near completion.
pwszReserved
[in] Reserved.

Return Values

S_OK | The handler should continue purging deletable files.
E_ABORT | This value is returned when the user clicks the Cancel button on the disk cleanup manager's dialog box while a scan is in progress. The handler should stop purging files and shut down.

Remarks

This method is typically called by the handler's IEmptyVolumeCache::Purge method while the handler is purging deletable files. Handlers should call PurgeProgress periodically to keep the user informed of progress, especially if the purge will take a long time. Calling this method frequently also allows the handler to shut down promptly if a user cancels a purge.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEmptyVolumeCacheCallback::ScanProgress

This method is called by a disk cleanup handler to update the disk cleanup manager on the progress of a scan for deletable files.

HRESULT ScanProgress(
  DWORDLONG dwlSpaceUsed,
  DWORD dwFlags,
  LPCWSTR pwszReserved
);

Parameters

dwSpaceUsed
[in] Amount of disk space that, at this point in the scan, the handler can free.
dwFlags
[in] Flag that can be sent to the disk cleanup manager. This flag can have the following value:
EVCCBF_LASTNOTIFICATION
This flag should be set if the handler will not call this method again. It is typically set when the scan is near completion.
pwszReserved
[in] Reserved.

Return Values

S_OK | The handler should continue scanning for deletable files.
E_ABORT | This value is returned when the user clicks the Cancel button on the disk cleanup manager's dialog box while a scan is in progress. The handler should stop scanning and shut down.

Remarks

This method is typically called by the handler's IEmptyVolumeCache::GetSpaceUsed method while the handler is scanning for deletable files.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Requires Windows 98.
Header: Declared in emptyvc.h.


IEnumExtraSearch

The IEnumExtraSearch interface is a standard OLE enumerator that is used by a client to determine the available search objects for a folder.

When to Implement

Implement IEnumExtraSearch if your namespace extension supports one or more search objects.

When to Use

You do not call this interface directly. An IEnumExtraSearch interface is requested by a client only after it has determined that the IShellFolder2 interface is exposed. Clients retrieve a pointer to this interface by calling IShellFolder2::EnumSearches.

IEnumExtraSearch implements IUnknown and the standard OLE enumeration methods.
IEnumExtraSearch Methods | Description
Clone | Used to save the enumeration state by creating a duplicate of the current enumerator.
Next | Used to request one or more items.
Reset | Resets the enumerator to the first item.
Skip | Skips one or more items.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IEnumExtraSearch::Clone

Used to request a duplicate of the enumerator object to preserve its current state.

HRESULT Clone(
    IEnumExtraSearch **ppEnum,
);

Parameters

ppEnum
Pointer to the IEnumExtraSearch interface of a new enumerator object.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

The new enumerator should be created with the same state as the current one. Use the Skip method to advance the enumeration index to the appropriate value before returning.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IEnumExtraSearch::Next

Used to request information on one or more search objects.

HRESULT Next(
    ULONG celt,
    EXTRASEARCH *rgelt,
    ULONG *pceltFetched
);

Parameters

celt
[in] Number of search objects to be enumerated, starting from the current object. If celt is too large, the method should stop and return the actual number of search objects in pceltFetched.
rgelt
[out] Pointer to an array of pceltFetched EXTRASEARCH structures containing information on the enumerated objects.
pceltFetched
[out] Number of objects actually enumerated. This may be less than celt.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IEnumExtraSearch::Reset

Used to reset the enumeration index to zero.

HRESULT Reset(void);

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IEnumExtraSearch::Skip

Skip past a specified number of objects.

HRESULT Skip(
    ULONG celt,
);

Parameters

celt
Number of objects to skip.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IEnumIDList

The IEnumIDList interface provides a standard set of methods that can be used to enumerate the item identifier lists (PIDLs) of the items in a Shell folder. When a folder's IShellFolder::EnumObjects method is called, it creates an enumeration object and passes a pointer to the object's IEnumIDList interface back to the caller.

When to Implement

All Shell folder objects must be able to respond to a call to their IShellFolder::EnumObjects method by creating an enumeration object that exports IEnumIDList. The Shell, in particular, uses these objects to enumerate the items in a folder.

When to Use

Use this interface to enumerate the contents of a Shell folder object. Call the folder's IShellFolder::EnumObjects method and use the returned IEnumIDList pointer to enumerate the PIDLs of the items in the folder.

IEnumIDList Methods | Description
Clone | Creates a new item enumeration object identical to the current one.
Next | Retrieves the specified number of item identifiers.
Reset | Returns to the beginning of the enumeration.
Skip | Skips over the specified number of items.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IEnumIDList::Clone

Creates a new item enumeration object with the same contents and state as the current one.

HRESULT Clone(
    IEnumIDList **ppenum
   );

Parameters

ppenum
Address of a pointer to the new enumeration object. The calling application must eventually free the new object by calling its Release member function.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method makes it possible to record a particular point in the enumeration sequence and then return to that point at a later time.

See Also

IEnumIDList

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IEnumIDList::Next

Retrieves the specified number of item identifiers in the enumeration sequence and advances the current position by the number of items retrieved.

HRESULT Next(
    ULONG celt,
    LPITEMIDLIST *rgelt,
    ULONG *pceltFetched
   );

Parameters

celt
Number of elements in the array pointed to by the rgelt parameter.
rgelt
Address of an array of ITEMIDLIST pointers that receives the item identifiers. The implementation must allocate these item identifiers using the Shell's allocator (retrieved by the SHGetMalloc function). The calling application is responsible for freeing the item identifiers using the Shell's allocator.

Note The ITEMIDLIST returned in the rgelt array are relative to the IShellFolder being enumerated.

pceltFetched
Address of a value that receives a count of the item identifiers actually returned in rgelt. The count can be smaller than the value specified in the celt parameter. This parameter can be NULL only if celt is one.

Return Values

Returns NOERROR if successful, S_FALSE if there are no more items in the enumeration sequence, or an OLE-defined error value otherwise.

Remarks

If this method returns a COM error code (as determined by the FAILED macro), then no entries in the rgelt array are valid on exit. If this method returns a success code (such as NOERROR or S_FALSE), then the ULONG pointed to by the pceltFetched parameter determines how many entries in the rgelt array are valid on exit.

The distinction is important in the case where celt > 1. For example, if you pass celt=10 and there are only 3 elements left, *pceltFetched will be 3 and the method will return S_FALSE meaning that you reached the end of the file. The three fetched elements will indeed be stored into rgelt and are valid.

See Also

IEnumIDList

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IEnumIDList::Reset

Returns to the beginning of the enumeration sequence.

HRESULT Reset(void);

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IEnumIDList

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IEnumIDList::Skip

Skips over the specified number of elements in the enumeration sequence.

HRESULT Skip(
    ULONG celt
   );

Parameters

celt
Number of item identifiers to skip.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IEnumIDList

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IEnumPublishedApps Interface

This is preliminary documentation and is subject to change.

This interface enumerates published applications to Add/Remove Programs in the Control Panel. The object exposing this interface is requested through IAppPublisher::EnumApps.

IEnumPublishedApps Members

Next | Retrieves the next IPublishedApp object in the enumeration.
Reset | Resets the enumeration of IPublishedApp objects to the first item.

Remarks

To publish applications to Add/Remove Programs in the Control Panel, you must support IEnumPublishedApps, IAppPublisher and IPublishedApp.

Interface Information

Stock Implementation | None
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IAppPublisher, IPublishedApp


IEnumPublishedApps::Reset Method

This is preliminary documentation and is subject to change.

Resets the enumeration of IPublishedApp objects to the first item.

Syntax

HRESULT Reset(VOID);

Return Value

Returns the following value:

S_OK This method only returns S_OK.

Remarks

Note IEnumPublishedApps is not a standard enumeration interface.
It does not support a Skip method nor does its Next method support retrieval of multiple items.

See Also

IAppPublisher, IPublishedApp


IEnumPublishedApps::Next Method

This is preliminary documentation and is subject to change.

Retrieves the next IPublishedApp object in the enumeration.

Syntax

HRESULT Next(
    IPublishedApp **ppApp
);

Parameters

ppApp
[out] Pointer to an IPublishedApp interface reference variable that returns the next application object. Note that the category of the application object returned must match that passed into IAppPublisher::EnumApps.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Note IEnumPublishedApps is not a standard enumeration interface. It does not support a Skip method, nor does its Next method support retrieval of multiple items.

See Also

IAppPublisher, IPublishedApp


IExtractIcon

This interface allows a client to retrieve the icon that is associated with one of the objects in a folder.

There are two ways to retrieve an object's icon. The simplest way is to call SHGetFileInfo. However, this approach is inflexible and may be rather slow. A more flexible and efficient way to retrieve an item's icon is to use IExtractIcon. The Shell uses IExtractIcon to retrieve icons when it displays the contents of a folder. To use IExtractIcon to retrieve an object's icon:

  1. Get a pointer to the IShellFolder interface of the folder that contains the object.
  2. Call IShellFolder::GetUIObjectOf with the PIDL of the object and the interface ID of IExtractIcon (IID_IExtractIcon). The folder creates an object to handle the icon extraction, and returns the object's IExtractIcon interface pointer.
  3. Call IExtractIcon::GetIconLocation to retrieve the icon's location.
  4. Call IExtractIcon::Extract to retrieve the icon's handle.

It may also be possible to extract icons asynchronously on a background thread. This approach is useful when extraction is a time-consuming operation. For details, see IExtractIcon::GetIconLocation.

When to Implement

Namespace extensions implement IExtractIcon to provide icons for their objects. A client obtains an IExtractIcon interface pointer for an object in a folder by calling the folder's IShellFolder::GetUIObjectOf method. The GetUIObjectOf implementation must create an object to handle the icon extraction and return a pointer to the object's IExtractIcon interface.

Icon handlers also implement IExtractIcon. An icon handler is a type of Shell extension handler that allows you to dynamically assign icons to the members of a file class.

When to Use

Call this interface if your application needs a more flexible way to retrieve an object's icon than SHGetFileInfo.

Methods

Extract | Extracts an icon from the specified location.
GetIconLocation | Retrieves the icon location for an object.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IExtractIcon::Extract

Extracts an icon image from the specified location.

HRESULT Extract(
    LPCSTR pszFile,
    UINT nIconIndex,
    HICON *phiconLarge,
    HICON *phiconSmall,
    UINT nIconSize
   );

Parameters

pszFile
[in] Pointer to a null-terminated string specifying the icon location.
nIconIndex
[in] The index of the icon in the file pointed to by pszFile.
phiconLarge
[out] Pointer to an HICON value that receives the handle to the large icon.
phiconSmall
[out] Pointer to an HICON value that receives the handle to the small icon.
nIconSize
[in] Desired size of the icon, in pixels. The low word contains the size of the large icon, and the high word contains the size of the small icon. The size specified can be the width or height. The width of an icon always equals its height.

Return Values

Returns NOERROR if the function extracted the icon, or S_FALSE if the calling application should extract the icon.

Remarks

The icon location and index are the same values returned by the GetIconLocation method. If this function returns S_FALSE, these values must specify an icon file name and index that form legal parameters for a call to Extract. If Extract does not return S_FALSE, no assumptions should be made about the meanings of the pszFile and nIconIndex parameters.

See Also

IExtractIcon

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IExtractIcon::GetIconLocation

Retrieves the location and index of an icon.

HRESULT GetIconLocation(
    UINT uFlags,
    LPSTR szIconFile,
    INT cchMax,
    LPINT piIndex,
    UINT *pwFlags
   );

Parameters

uFlags
[in] Flags. This parameter can be zero or one or more of the following values:
GIL_ASYNC | A client sets this flag to discover whether or not the icon should be extracted asynchronously. If the icon can be rapidly extracted, this flag is usually ignored. If extraction will be time-consuming, GetIconLocation should return E_PENDING. See the Remarks for further discussion.
GIL_FORSHELL | The icon is to be displayed in a Shell folder.
GIL_OPENICON | The icon should be in the open state if both open- and closed-state images are available. If this flag is not specified, the icon should be in the normal or closed state. This flag is typically used for folder objects.
szIconFile
[out] Pointer to a buffer that receives the icon location. The icon location is a null-terminated string that identifies the file that contains the icon.
cchMax
[in] Size of the buffer pointed to by szIconFile.
piIndex
[out] Pointer to an INT that receives the index of the icon in the file pointed to by szIconFile.
pwFlags
[out] Pointer to a UINT value that receives zero or a combination of the following values:
GIL_DONTCACHE | The physical image bits for this icon should not be cached by the caller. This distinction is important to consider because a GIL_DONTCACHELOCATION flag may be introduced in future versions of the Shell.
GIL_NOTFILENAME | The location is not a file name/index pair. Callers that decide to extract the icon from the location must call this object's IExtractIcon::Extract method to obtain the desired icon images.
GIL_PERCLASS | All objects of this class have the same icon. This flag is used internally by the Shell. Typical implementations of IExtractIcon do not require this flag because the flag implies that an icon handler is not required to resolve the icon on a per-object basis. The recommended method for implementing per-class icons is to register a DefaultIcon for the class.
GIL_PERINSTANCE | Each object of this class has its own icon. This flag is used internally by the Shell to handle cases like Setup.exe, where objects with identical names can have different icons. Typical implementations of IExtractIcon do not require this flag.
GIL_SIMULATEDOC | The caller should create a document icon using the specified icon.

Return Values

Returns S_OK if the function returned a valid location, or S_FALSE if the Shell should use a default icon. If the GIL_ASYNC flag is set in uFlags, the method can return E_PENDING to indicate that icon extraction will be time consuming.

Remarks

When a client sets the GIL_ASYNC flag in uFlags and receives E_PENDING as a return value, it typically creates a background thread to extract the icon. It calls GetIconLocation from that thread, without the GIL_ASYNC flag, to retrieve the icon location. It then calls IExtractIcon::Extract to extract the icon. Returning E_PENDING implies that the object is free threaded. In other words, it can safely be called concurrently by multiple threads.

See Also

IExtractIcon::Extract

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IExtractImage

The IExtractImage interface is used to request a thumbnail image from a Shell folder. There are two steps to the process. First, use GetLocation to request the path description of an image and specify how the image should be rendered Then call Extract to extract the image.

If the object is free-threaded it must also expose an IRunnableTask interface, so it can be stopped and started as needed. This feature can be particularly useful when extraction may be slow.

When to Implement

Implement IExtractImage if your namespace extension needs to provide thumbnail images to be displayed in a Shellview.

When to Use

Use IExtractImage if you are implementing a view of namespace objects, and want to display thumbnail images. You can use a Shell folder's IShellFolder::GetUIObjectOf method to bind to its IExtractImage interface.

IExtractImage implements IUnknown and the following methods:
IExtractImage Methods | Description
GetLocation | Used to request location of the file containing the image.
Extract | Used to request the image itself.

Requirements

Version 4.70 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IExtractImage::Extract

Used to request an image from an object, such as an item in a Shell folder.

HRESULT Extract(
    HBITMAP *phBmpImage
);

Parameters

phBmpImage
[out] Buffer to hold the bitmapped image.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

You must call IExtractImage::GetLocation prior to calling Extract.

Requirements

Version 4.70 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IExtractImage::GetLocation

Used to request the path description of an image and specify how the image should be rendered.

HRESULT GetLocation(
    LPWSTR pszPathBuffer,
    DWORD cchMax,
    DWORD *pdwPriority
    const SIZE *prgSize
    DWORD dwRecClrDepth
    DWORD *pdwFlags
);

Parameters

pszPathBuffer
[out] Buffer used to return the path description. This value to identifies the image so you can can avoid loading the same one more than once.
cchMax
[in] Size of pszPathBuffer in bytes.
pdwPriority
[out] Pointer used to return the priority of the item when the IEIFLAG_ASYNC flag is set in pdwFlags. This parameter is normally used to indicate the amount of time needed to extract the image. There are three standard priority levels:
Level | Description
IEI_PRIORITY_MAX | Maximum priority.
IEI_PRIORITY_MIN | Minimum priority.
IEI_PRIORITY_NORMAL | Normal priority.

If you want more control over the order in which thumbnails are extracted, you can define as many priority levels as you wish (up to 32 bits). As long as the integer values assigned to the different levels increase from low to high priority, the actual numbers you use aren't important. They are only used to determine the order in which the images will be extracted.

prgSize
[in] Pointer to a SIZE structure with the desired width and height of the image.
dwRecClrDepth
[in] Recommended color depth in units of bits per pixel.
pdwFlags
[in] Flags that specify how the image is to be handled. It can be a combination of the following:
Flag | Description
IEIFLAG_ASYNC | Used to ask the object if it supports asynchronous (free-threaded) extraction. If this flag is set, and GetLocation returns E_PENDING, the priority of the item should be returned in pdwPriority.
IEIFLAG_CACHE | Returned by the object to indicate that it will not cache the image. If this flag is returned, the Shell will cache a copy of the image.
IEIFLAG_ASPECT | Used to ask the object to use the supplied aspect ratio. If this flag is set, a rectangle with the desired aspect ratio will be passed in prgSize. This flag cannot be used with IEIFLAG_SCREEN.
IEIFLAG_OFFLINE | Used to tell the object to use only local content for rendering.
IEIFLAG_GLEAM | Used to ask the object if it has a gleam. If so, this flag should be set when the method returns.
IEIFLAG_SCREEN | Used to tell the object to render as if for the screen. This flag cannot be used with IEIFLAG_ASPECT.
IEIFLAG_ORIGSIZE | Version 5.0. Used to tell the object to render the image to the approximate size passed in prgSize, but crop it if necessary.

Return Values

Value | Description
NOERROR | Success.
E_PENDING | If the IEIFLAG_ASYNC flag is set, this return value is used to indicate to the Shell that the object is free-threaded.

It may also return an OLE-defined error code.

Remarks

If GetLocation is free-threaded, it can be placed in a background thread. The object must also expose an IRunnableTask interface, so the caller can start and stop the extraction process as needed.

You should return images that fit within the boundaries defined by prgSize. With Windows 2000 and later systems, you can set IEIFLAG_ORIGSIZE to use objects that do not have a standard aspect ratio, and they will be displayed properly. You do not need to fill in the unused part of the rectangle. If you try to use a nonstandard aspect ratio image with earlier versions of the Shell, it will be stretched to fit the prgSize rectangle. Depending on how much the aspect ratio differs from what is specified, the image may be badly distorted.

Requirements

Version 4.70 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IExtractImage2

The IExtractImage2 interface extends the capabilities of IExtractImage.

When to Implement

Implement IExtractImage2 to provide date stamps for your thumbnail images.

When to Use

You do not call this interface directly. IExtractImage2 is used by the operating system only when it has confirmed that your application is aware of this interface.

IExtractImage2 implements all the IExtractImage methods as well as IUnknown. The following method is specific to IExtractImage2.
IExtractImage2 Methods | Description
GetDateStamp | Used to request the date the thumbnail was last modified.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IExtractImage2::GetDateStamp

Used to request the date the image was last modified. This method allows the Shell to determine whether or not cached images are out-of-date.

HRESULT GetDateStamp(
    FILETIME *pDateStamp
);

Parameters

pDateStamp
Pointer to a FILETIME structure used to return the last time the image was modified.

Return Values

Return NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IFileSystemBindData Interface

This interface stores file system information for optimizing calls to IShellFolder::ParseDisplayName. This information is stored in a WIN32_FIND_DATA structure. The implementing object is then stored in a bind context that is passed to IShellFolder::ParseDisplayName.

Implement IFileSystemBindData when you want to optimize calls to IShellFolder::ParseDisplayName and you already have the WIN32_FIND_DATA structure's file information available to you.

IFileSystemBindData Members

GetFindData | Retrieves the file system information stored in the WIN32_FIND_DATA structure.
SetFindData | Stores file system information in a WIN32_FIND_DATA structure. This information is used by IShellFolder::ParseDisplayName.

Remarks

To store the WIN32_FIND_DATA information prior to calling IShellFolder::ParseDisplayName, the client would use the following procedure:

  1. Create an instance of the object that exposes the IFileSystemBindData interface.
  2. Use IFileSystemBindData::SetFindData to store the data in the object.
  3. Store the object in a bind context by using the IBindCtx::RegisterObjectParam method. Set the pszKey parameter to the string L"File System Bind Data" and the punk parameter to the address of the IFileSystemBindData interface.

The bind context would then be passed with the call to IShellFolder::ParseDisplayName.

For an example of how to implement this interface, see Simple ID Lists.

Interface Information

Stock Implementation | shell32.dll version 5.00 or later
Custom Implementation | No
Inherits from | IUnknown
Header | shlobj.h
Minimum operating systems | Windows 2000


IFileSystemBindData::GetFindData Method

Retrieves the file system information stored in the WIN32_FIND_DATA structure.

Syntax

HRESULT GetFindData(
    WIN32_FIND_DATA *pfd
);

Parameters

pfd
[out] Pointer to the WIN32_FIND_DATA structure that receives the data.

Return Value

Returns S_OK.

Remarks

This method provides bind context information to IShellFolder::ParseDisplayName. The client accesses the object by calling IBindCtx::GetObjectParam with the pszKey parameter set to the string "File System Bind Data".


IFileSystemBindData::SetFindData Method

Stores file system information in a WIN32_FIND_DATA structure. This information is used by IShellFolder::ParseDisplayName.

Syntax

HRESULT SetFindData(
    const WIN32_FIND_DATA *pfd
);

Parameters

pfd
[in] Pointer to the WIN32_FIND_DATA structure that specifies the data you want to store.

Return Value

Returns S_OK.

Remarks

After the client stores the file information, the instance of the object itself must be stored in a bind context by using the IBindCtx::RegisterObjectParam method with the pszKey parameter set to L"File System Bind Data".


IFileViewer

The IFileViewer interface designates an interface that allows a registered file viewer to be notified when it must show or print a file.

Note: File viewers are not supported by Microsoft® Windows 2000® and later systems.

When to Implement

You implement this interface to provide a means for your registered file types to be viewed and/or printed.

When to Use

You do not normally use this interface. The Shell calls the interface when the user chooses the Quick View command from a file's shortcut menu and the file is a type that the file viewer recognizes.
IFileViewer Methods | Description
PrintTo | Prints a file.
Show | Displays a file.
ShowInitialize | Prepares to display a file.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFileViewer::PrintTo

Prints a file. The Shell specifies the name of the file to print by calling the file viewer's IPersistFile::Load method.

HRESULT PrintTo(
    LPSTR pszDriver,
    BOOL fSuppressUI
   );

Parameters

pszDriver
Address of a buffer that contains the name of the printer device driver that should print the file. If this parameter is NULL, the file viewer determines which device driver to use.
fSuppressUI
User interface suppression flag. If this parameter is TRUE, the file viewer should not display any user interface, including error messages, during the print operation. If this parameter is FALSE, the file viewer can show dialog boxes, as needed.

Return Values

Returns the NOERROR value if successful, or an OLE-defined error value otherwise.

See Also

IFileViewer

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFileViewer::Show

Displays a file. The Shell specifies the name of the file to display by calling the file viewer's IPersistFile::Load method.

HRESULT Show(
    LPFVSHOWINFO pvsi
   );

Parameters

pvsi
Address of an FVSHOWINFO structure to contain information that the file viewer uses to display the file. A file viewer can return information to the Shell by modifying the members of the structure.

Return Values

Returns NOERROR if successful, or E_UNEXPECTED if the IFileViewer::ShowInitialize method was not called before IFileViewer::Show.

See Also

IFileViewer

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFileViewer::ShowInitialize

Allows a file viewer to determine whether it can display a file and, if it can, to perform initialization operations before showing the file.

HRESULT ShowInitialize(
    LPFILEVIEWERSITE lpfsi
   );

Parameters

lpfsi
Address of an IFileViewerSite interface. A file viewer uses this interface to retrieve the handle to the current pinned window or to specify a new pinned window.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The Shell calls this method before the IFileViewer::Show method. The Shell specifies the name of the file to display by calling the file viewer's IPersistFile::Load method.

ShowInitialize must perform all operations that are prone to failure so that if it succeeds, IFileViewer::Show will not fail.

See Also

IFileViewer

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFileViewerSite

The IFileViewerSite interface designates an interface that allows a file viewer to retrieve the handle to the current pinned window or to set a new pinned window. The pinned window is the window in which the current file viewer displays a file. When the user selects a new file to view, the Shell directs the file viewer to display the new file in the pinned window rather than create a new window.

Note: File viewers are not supported by Microsoft® Windows 2000® and later systems.

When to Implement

You do not normally implement this interface. The Shell implements this interface to provide a pinned window for the file viewer.

When to Use

You use this interface to obtain or set the window for a file viewer.
IFileViewerSite Methods | Description
GetPinnedWindow | Retrieves the handle to the current pinned window.
SetPinnedWindow | Sets a new pinned window.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFileViewerSite::GetPinnedWindow

Retrieves the handle to the current pinned window, if one exists.

HRESULT GetPinnedWindow(
    HWND *phwnd
   );

Parameters

phwnd
Address of the handle to the current pinned window or NULL if no pinned window exists.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IFileViewerSite

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFileViewerSite::SetPinnedWindow

Sets the pinned window. When the user selects a new file to view, the Shell directs the file viewer to display the new file in the pinned window instead of creating a new window.

HRESULT SetPinnedWindow(
    HWND *hwnd
   );

Parameters

hwnd
Handle to the new pinned window or NULL if there is to be no pinned window.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IFileViewerSite

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IFolderView Interface

This is preliminary documentation and is subject to change.

Retrieves information about a folder's view.

IFolderView Members

GetAutoArrange | Retrieves the current state of the folder's Auto Arrange mode.
GetCurrentViewMode | Retrieves an address containing a value representing the folder's current view mode.
GetDefaultSpacing | Retrieves a pointer to a POINT structure containing the default width (x) and height (y) measurements of an item, including the surrounding 'white space'.
GetFolder | Retrieves the folder object.
GetItemPosition | Retrieves the position of an item in the folder's view.
GetSelectionMarkedItem | Retrieves the index of an item in the folder's view which has been marked by using the SVSI_SELECTIONMARK in IFolderView::SelectItem.
GetSpacing | Retrieves a POINT structure containing the width (x) and height (y) dimensions, including the surrounding 'white space', of an item.
Item | Retrieves the identifier of a specific item in the folder view, by index.
ItemCount | Retrieves a pointer to the number of items in the folder.
Items | Retrieves the address of an identifier enumeration object based on the collection of items in the folder view.
SelectAndPositionItems | Allows the selection and positioning of items visible in the folder's view.
SelectedItemCount | Retrieves a pointer to the number of items (files and folders) currently selected in the folder's view.
SelectedItems | Retrieves the address of a pointer to an IEnumIDList interface that enumerates the selected items in the folder.
SelectItem | Selects an item in the folder's view.
SetCurrentViewMode | Sets the selected folder's view mode.

Interface Information

Stock Implementation | shell32.dll
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


IFolderView::GetAutoArrange Method

This is preliminary documentation and is subject to change.

Retrieves the current state of the folder's Auto Arrange mode.

Syntax

HRESULT GetAutoArrange(VOID);

Return Value

Returns S_OK if the folder is in Auto Arrange mode.

See Also

IFolderView::GetSpacing


IFolderView::GetCurrentViewMode Method

This is preliminary documentation and is subject to change.

Retrieves an address containing a value representing the folder's current view mode.

Syntax

HRESULT GetCurrentViewMode(
    UINT *pViewMode
);

Parameters

pViewMode
[out]

Pointer to a memory location at which to store the folder's current view mode. The value at that address is one of the following FOLDERVIEWMODE values.

FVM_ICON
Large icons
FVM_SMALLICON
Small icons
FVM_LIST
List view without details
FVM_DETAILS
Show details (size, type, last modification date)
FVM_THUMBNAIL
Thumbnail view
FVM_TILE
Tile view
FVM_THUMBSTRIP
Filmstrip view

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::SetCurrentViewMode, IShellView::GetCurrentInfo


IFolderView::GetDefaultSpacing Method

This is preliminary documentation and is subject to change.

Retrieves a pointer to a POINT structure containing the default width (x) and height (y) measurements of an item, including the surrounding 'white space'.

Syntax

HRESULT GetDefaultSpacing(
    POINT *ppt
);

Parameters

ppt
[in, out] Pointer to an existing POINT structure to be filled with the default sizing dimensions of the items in the folder's view.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::GetSpacing


IFolderView::GetFolder Method

This is preliminary documentation and is subject to change.

Retrieves the folder object.

Syntax

HRESULT GetFolder(
    REFIID riid,
    VOID **ppv
);

Parameters

riid
[in] Interface ID by which to refer to the folder object.
ppv
[out] Address of a pointer to the folder object interface.

Return Value

Returns S_OK if successful, or an error value otherwise.


IFolderView::GetItemPosition Method

This is preliminary documentation and is subject to change.

Retrieves the position of an item in the folder's view.

Syntax

HRESULT GetItemPosition(
    LPCITEMIDLIST pidl,
    POINT *ppt
);

Parameters

pidl
[in] Pointer to an ITEMIDLIST interface.
ppt
[out] Pointer to a POINT structure that receives the position of the item's upper-left corner.

Return Value

Returns S_OK if successful, or an error value otherwise.


IFolderView::GetSelectionMarkedItem Method

This is preliminary documentation and is subject to change.

Retrieves the index of an item in the folder's view which has been marked by using the SVSI_SELECTIONMARK in IFolderView::SelectItem.

Syntax

HRESULT GetSelectionMarkedItem(
    int *piItem
);

Parameters

piItem
[out] Pointer to the index of the marked item.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::SelectItem


IFolderView::GetSpacing Method

This is preliminary documentation and is subject to change.

Retrieves a POINT structure containing the width (x) and height (y) dimensions, including the surrounding 'white space', of an item.

Syntax

HRESULT GetSpacing(
    POINT *ppt
);

Parameters

ppt
[in, out] Pointer to an existing POINT structure to be filled with the current sizing dimensions of the items in the folder's view.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

As an example, consider an icon measuring 75 pixels by 70 pixels, with its upper-left corner located at pixel (0,0). Note that this measurement includes both the visible graphic and its surrounding buffer area. IFolderView::GetSpacing would return a pointer to a POINT structure containing an x value of 75 and a y value of 70. If you were using this information to avoid overlap, the next icon in line to the right would be placed with its upper-left corner at pixel (75,0). Similarly, the next icon below would be placed at pixel (0,70).

See Also

IFolderView::GetDefaultSpacing


IFolderView::ItemCount Method

This is preliminary documentation and is subject to change.

Retrieves a pointer to the number of items in the folder.

Syntax

HRESULT ItemCount(
    int pcItems
);

Parameters

pcItems
[out] Pointer to an the number of items (files and folders) displayed in the folder view.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::SelectedItemCount


IFolderView::Item Method

This is preliminary documentation and is subject to change.

Retrieves the identifier of a specific item in the folder view, by index.

Syntax

HRESULT Item(
    int iItemIndex,
    LPITEMIDLIST *ppidl
);

Parameters

iItemIndex
[in] Index of the item in the view.
ppidl
[out] Address of a pointer to a PIDL containing the item's identifier information.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

When no longer needed, the PIDL should be freed by calling CoTaskMemFree

See Also

IFolderView::Items


IFolderView::Items Method

This is preliminary documentation and is subject to change.

Retrieves the address of an identifier enumeration object based on the collection of items in the folder view.

Syntax

HRESULT Items(
    IEnumIDList **ppenum
);

Parameters

ppenum
[out] Address of a pointer to an IEnumIDList interface. Methods of this interface may be used to walk the enumeration.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::Item


IFolderView::SelectAndPositionItems Method

This is preliminary documentation and is subject to change.

Allows the selection and positioning of items visible in the folder's view.

Syntax

HRESULT SelectAndPositionItems(
    UINT cidl,
    LPCITEMIDLIST *apidl,
    POINT *apt,
    DWORD dwFlags
);

Parameters

cidl
[in] The number of items to select.
apidl
[in] Pointer to an array of cidl items.
apt
[in] Pointer to an array of cidl POINT structures containing the locations each corresponding element in apidl should be positioned.
dwFlags
[in]

Flag specifying the type of selection to apply. This value can be one of the following.

SVSI_DESELECT
Deselect the item.
SVSI_DESELECTOTHERS
Deselect all but the selected item. If iItem is NULL, deselect all items.
SVSI_EDIT
Put the name of the item at index iItem into rename mode.
SVSI_ENSUREVISIBLE
Ensure, in the case of a folder which cannot display all of its contents on one screen, to display the portion containing the item in question.
SVSI_FOCUSED
The item should be given the focus when multiple items are selected, placing the item first in any list of the collection returned by a method.
SVSI_TRANSLATEPT
The input point is in screen coordinates and should be converted to the list-view client coordinates.
SVSI_SELECTIONMARK
Mark the item so that it can be queried using IFolderView::GetSelectionMarkedItem.
SVSI_SELECT
Select the item.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::SelectItem, IFolderView::SelectedItems, IShellView::SelectItem


IFolderView::SelectedItemCount Method

This is preliminary documentation and is subject to change.

Retrieves a pointer to the number of items (files and folders) currently selected in the folder's view.

Syntax

HRESULT SelectedItemCount(
    int pcItems
);

Parameters

pcItems
[out] Pointer to the number of items currently selected.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::ItemCount


IFolderView::SelectedItems Method

This is preliminary documentation and is subject to change.

Retrieves the address of a pointer to an IEnumIDList interface that enumerates the selected items in the folder.

Syntax

HRESULT SelectedItems(
    IEnumIDList **ppenum
);

Parameters

ppenum
[out] Address of a pointer to the IEnumIDList interface.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::SelectedItemsAsDataObject


IFolderView::SelectItem Method

This is preliminary documentation and is subject to change.

Selects an item in the folder's view.

Syntax

HRESULT SelectItem(
    int iItem,
    DWORD dwFlags
);

Parameters

iItem
[in] The index of the item to select in the folder's view.
dwFlags
[in]

Flag specifying the type of selection to apply. This value can be one of the following:

SVSI_DESELECT
Deselect the item.
SVSI_DESELECTOTHERS
Deselect all but the selected item. If iItem is NULL, deselect all items.
SVSI_EDIT
Put the name of the item at index iItem into rename mode.
SVSI_ENSUREVISIBLE
If a folder cannot display all of its contents on one screen, ensure that the portion containing the item in question is displayed.
SVSI_FOCUSED
When multiple items are selected, the item is given the focus and is placed first in any list of the collection returned by a method.
SVSI_TRANSLATEPT
The input point is in screen coordinates and should be converted to the list-view client coordinates.
SVSI_SELECTIONMARK
Mark the item so that it can be queried using IFolderView::GetSelectionMarkedItem.
SVSI_SELECT
Select the item.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::GetSelectionMarkedItem, IFolderView::SelectAndPositionItems, IShellView::SelectItem


IFolderView::SetCurrentViewMode Method

This is preliminary documentation and is subject to change.

Sets the selected folder's view mode.

Syntax

HRESULT SetCurrentViewMode(
    UINT ViewMode
);

Parameters

ViewMode
[in]

One of the following values from the FOLDERVIEWMODE enumeration.

FVM_ICON
Large icons
FVM_SMALLICON
Small icons
FVM_LIST
List view without details
FVM_DETAILS
Show details (size, type, last modification date)
FVM_THUMBNAIL
Thumbnail view
FVM_TILE
Tile view
FVM_THUMBSTRIP
Filmstrip view

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IFolderView::GetCurrentViewMode, IShellView::CreateViewWindow


IHWEventHandler Interface

This is preliminary documentation and is subject to change.

This interface is called by AutoPlay to implement the handling of registered media types.

IHWEventHandler Members

HandleEvent | Handles AutoPlay device events for which there is no content of the type the application is registered to handle.
HandleEventWithContent | Handles AutoPlay device events for registered applications' content.
Initialize | This method initializes an object that contains an implementation of the IHWEventHandler interface.

Remarks

Developers supporting this interface must expose it in a Component Object Model (COM) server.

All applications registered as AutoPlay media handlers must implement this interface.

Interface Information

Stock Implementation | Shell32.dll version 5.5 or later
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


IHWEventHandler::Initialize Method

This is preliminary documentation and is subject to change.

This method initializes an object that contains an implementation of the IHWEventHandler interface.

Syntax

HRESULT Initialize(
    LPCWSTR pszParams
);

Parameters

pszParams
[in] Pointer to a string buffer that contains the string from the registry key located at AutoPlayHandlers\Handlers\InitCmdLine.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

This method receives the registry string located at AutoPlayHandlers\Handlers\InitCmdLine. Applications that have registered with AutoPlay as event handlers place this string into the registry as part of the registration process.


IHWEventHandler::HandleEventWithContent Method

This is preliminary documentation and is subject to change.

Handles AutoPlay device events for registered applications' content.

Syntax

HRESULT HandleEventWithContent(
    LPCWSTR pszDeviceID,
    LPCWSTR pszAltDeviceID,
    LPCWSTR pszEventType,
    LPCWSTR pszContentTypeHandler,
    IDataObject *pdata
);

Parameters

pszDeviceID
[in] Pointer to a string buffer that contains the device identifier (ID).
pszAltDeviceID
[in] Pointer to a string buffer that contains the alternate device ID. The alternate device ID is more human-readable than the primary device ID.
pszEventType
[in] Pointer to a string buffer that contains the event type. The event types include DeviceArrival, DeviceRemoval, MediaArrival, and MediaRemoval.
pszContentTypeHandler
[in] Pointer to a string buffer that contains the AutoPlay content type handler. The handler types include PicturesContentHandler, MusicFilesContentHandler, and others.
pdata
[in] Pointer to an object that implements the IDataObject interface. The object contains all the files that match this event handler's registered content.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The event types and content handler types are not C/C++ language constants; they are literal text strings.

See Also

IHWEventHandler::HandleEvent


IHWEventHandler::HandleEvent Method

This is preliminary documentation and is subject to change.

Handles AutoPlay device events for which there is no content of the type the application is registered to handle.

Syntax

HRESULT HandleEvent(
    LPCWSTR pszDeviceID,
    LPCWSTR pszAltDeviceID,
    LPCWSTR pszEventType
);

Parameters

pszDeviceID
[in] Pointer to a string buffer that contains the device identifier (ID).
pszAltDeviceID
[in] Pointer to a string buffer that contains the alternate device ID. The alternate device ID is more human-readable than the primary device ID.
pszEventType
[in] Pointer to a string buffer that contains the event type. The event types include DeviceArrival, DeviceRemoval, MediaArrival, and MediaRemoval.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The event types are not C/C++ language constants; they are literal text strings.

See Also

IHWEventHandler::HandleEventWithContent


IInputObject

The IInputObject interface is used to change UI activation and process accelerators for a user input object contained in the Shell.

When to Implement

Implement IInputObject if you are implementing a Shell object that takes user input.

When to Use

You do not call this interface directly. IInputObject is used by the Shell or the browser to notify the object of UI activation changes and to translate keyboard accelerators.

IInputObject is derived from IUnknown. The following methods are specific to IInputObject.
IInputObject Methods | Description
HasFocusIO | Determines if one of the object's windows has the keyboard focus.
TranslateAcceleratorIO | Passes keyboard accelerators to the object.
UIActivateIO | Activates or deactivates the object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IInputObject::HasFocusIO

Determines if one of the object's windows has the keyboard focus.

HRESULT HasFocusIO(void);

Return Values

Returns S_OK if one of the object's windows has the keyboard focus, or S_FALSE otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IInputObject::TranslateAcceleratorIO

Allows the object to process keyboard accelerators.

HRESULT TranslateAcceleratorIO(
    LPMSG lpMsg
);

Parameters

lpMsg
Address of an MSG structure that contains the keyboard message that is being translated.

Return Values

Returns S_OK if the accelerator was translated, or S_FALSE otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IInputObject::UIActivateIO

UI-activates or deactivates the object.

HRESULT UIActivateIO(
    BOOL fActivate,
    LPMSG lpMsg
);

Parameters

fActivate
Indicates if the object is being activated or deactivated. If this value is nonzero, the object is being activated. If this value is zero, the object is being deactivated.
lpMsg
Address of an MSG structure that contains the message that caused the activation change. This value may be NULL.

Return Values

Returns S_OK if the activation change was successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IInputObjectSite

The IInputObjectSite interface is used to communicate focus changes for a user input object contained in the Shell.

When to Implement

You do not normally implement this interface. IInputObjectSite is implemented by the Shell or the browser to properly maintain the input focus.

When to Use

You use IInputObjectSite if you are implementing a Shell object that takes user input.

IInputObjectSite is derived from IUnknown. The following method is specific to IInputObjectSite.
IInputObjectSite Method | Description
OnFocusChangeIS | Informs the browser that the focus has changed.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IInputObjectSite::OnFocusChangeIS

Informs the browser that the focus has changed.

HRESULT OnFocusChangeIS(
    IUnknown *punkObj,
    BOOL fSetFocus
);

Parameters

punkObj
Address of the IUnknown interface of the object gaining or losing the focus.
fSetFocus
Indicates if the object has gained or lost the focus. If this value is nonzero, the object has gained the focus. If this value is zero, the object has lost the focus.

Return Values

Returns S_OK if the method was successful, or an OLE-defined error code otherwise.

Remarks

The calling object should call this method whenever one of its windows gains or loses the input focus.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


INewShortcutHook

The INewShortcutHook interface is used when creating a new Internet shortcut.

When to Implement

You do not normally implement INewShortcutHook. It is implemented by the Shell for Internet shortcuts.

When to Use

You use INewShortcutHook when creating a new Internet shortcut. The methods provided by this interface are supplied as a convenience.

INewShortcutHook is derived from IUnknown. The following methods are specific to INewShortcutHook.
INewShortcutHook Methods | Description
GetExtension | Retrieves the file extension for the shortcut object.
GetFolder | Retrieves the folder name for the shortcut object.
GetName | Retrieves the file name of the shortcut object, without the extension.
GetReferent | Retrieves the referent of the shortcut object.
SetFolder | Sets the folder name for the shortcut object.
SetReferent | Sets the referent of the shortcut object.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INewShortcutHook::GetExtension

Retrieves the file extension for the shortcut object.

HRESULT GetExtension(
    LPTSTR pszExtension,
    int cchExtension
);

Parameters

pszExtension
Address of a character buffer that receives the extension.
cchExtension
Size of the buffer at pszExtension, in characters.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

INewShortcutHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INewShortcutHook::GetFolder

Retrieves the folder name for the shortcut object.

HRESULT GetFolder(
    LPTSTR pszFolder,
    int cchFolder
);

Parameters

pszFolder
Address of a character buffer that receives the folder name.
cchFolder
Size of the buffer at pszFolder, in characters.

Return Values

Returns S_OK if successful, S_FALSE if no folder has been assigned, or an OLE-defined error code otherwise.

See Also

INewShortcutHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INewShortcutHook::GetName

Retrieves the file name of the shortcut object, without the extension.

HRESULT GetName(
    LPTSTR pszName,
    int cchName
);

Parameters

pszName
Address of a character buffer that receives the name.
cchName
Size of the buffer at pszName, in characters.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

INewShortcutHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INewShortcutHook::GetReferent

Retrieves the referent of the shortcut object.

HRESULT GetReferent(
    LPTSTR pszReferent,
    int cchReferent
);

Parameters

pszReferent
Address of a character buffer that receives the referent.
cchReferent
Size of the buffer at pszReferent, in characters.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

For Internet shortcut objects, this method is the same as IUniformResourceLocator::GetURL.

See Also

INewShortcutHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INewShortcutHook::SetFolder

Sets the folder name for the shortcut object.

HRESULT SetFolder(
    LPTSTR pszFolder
);

Parameters

pszFolder
Address of a character buffer that contains the folder name.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

See Also

INewShortcutHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INewShortcutHook::SetReferent

Sets the referent of the shortcut object.

HRESULT SetReferent(
    LPCTSTR pszReferent,
    HWND hWnd
);

Parameters

pszReferent
Address of a character buffer that contains the referent.
hWnd
Handle to the window that will be used as the parent if the object needs to display a message box or dialog box.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

For Internet shortcut objects, this method is the same as IUniformResourceLocator::SetURL.

See Also

INewShortcutHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


INotifyReplica

The INotifyReplica interface provides the object's creator with the means to notify an object that it may be subject to subsequent reconciliation. The briefcase reconciler is responsible for implementing this interface.
INotifyReplica Method | Description
YouAreAReplica | Notifies an object that it may be subject to reconciliation.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


INotifyReplica::YouAreAReplica

Notifies an object that it may be subject to subsequent reconciliation through the IReconcilableObject::Reconcile method.

HRESULT INotifyReplica::YouAreAReplica(
   ULONG ulcOtherReplicas,
   IMoniker ** rgpmkOtherReplicas
   );

Parameters

ulcOtherReplicas
Number of other replicas of the object. This parameter must not be zero.
rgpmkOtherReplicas
Address of an array that contains the addresses of the monikers to use to access the other replicas.

Return Values

Returns S_OK if successful, or E_UNEXPECTED otherwise.

Remarks

An object may be notified that it is a replica more than once. Briefcase reconcilers are not required to implement this interface. Initiators are not required to call this interface if it is implemented. However, an object's implementation of IReconcilableObject::Reconcile may fail if that object has not previously been notified through INotifyReplica::YouAreAReplica that it may be subject to reconciliation.

The briefcase calls the INotifyReplica interface when objects are added to it.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IObjMgr

The IObjMgr interface allows a client to append or remove an object from a collection of objects managed by a server object.

When to Implement

This interface is implemented by objects that manage a collection of other objects. It is exported to allow clients of the object to request that objects be added to or removed from the collection.

When to Use

Use this interface to add or delete an object from the server object's collection of managed objects.

Methods

IObjMgr exposes the following methods in addition to IUnknown.

Append | Appends an object to the server object's collection of managed objects.
Remove | Removes an object from the server object's collection of managed objects.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IObjMgr::Append

Appends an object to the collection of managed objects.

HRESULT Append(
    IUnknown *punk
);

Parameters

punk
[in] Address of the IUnknown interface of the object to be added to the list.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IObjMgr, IObjMgr::Remove

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IObjMgr::Remove

Removes an object from the collection of managed objects.

HRESULT Remove(
    IUnknown *punk
);

Parameters

punk
[in] Address of the IUnknown interface of the object to be removed from the list.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IObjMgr, IObjMgr::Append

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IPersistFolder

The IPersistFolder interface is used to initialize Shell folder objects.

When to Implement

When implementing a Shell namespace extension, specifically the IShellFolder interface, you need to implement this interface so the folder object can be initialized. Implementation of this interface is how the folder is told where it is in the Shell namespace.

When to Use

You do not use this interface directly. It is used by the file system implementation of the IShellFolder::BindToObject interface when it is initializing a Shell folder object.

IPersistFolder is derived from IPersist. The following method is specific to IPersistFolder.
IPersistFolder Method | Description
Initialize | Instructs a Shell folder object to initialize itself based on the information passed.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IPersistFolder::Initialize

Instructs a Shell folder object to initialize itself based on the information passed.

HRESULT Initialize(
    LPCITEMIDLIST pidl,
   );

Parameters

pidl
Address of the ITEMIDLIST (item identifier list) structure that specifies the absolute location of the folder.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

All objects that implement the IShellFolder interface for use in the Shell's namespace must implement this method. When a folder's location in the namespace is not a relevant consideration, this method can simply return NOERROR. When the location is relevant to the folder, you should store the fully qualified IDLIST passed in for future reference.

For example, if the folder implementation needs to construct a fully qualified PIDL to elements that it contains, the PIDL passed to this method should be used to construct the fully qualified PIDLs.

See Also

IPersistFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IPersistFolder2

The IPersistFolder2 interface is used to obtain information from Shell folder objects.

When implementing a Shell namespace extension, specifically the IShellFolder interface, you need to implement this interface so that the Shell folder object's ITEMIDLIST can be retrieved.

IPersistFolder2 is derived from IPersistFolder. The following method is specific to IPersistFolder2.

Methods
GetCurFolder Retrieves the ITEMIDLIST for the folder object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlobj.h.


IPersistFolder2::GetCurFolder

Retrieves the ITEMIDLIST for the folder object.

HRESULT GetCurFolder(
    LPITEMIDLIST *ppidl,
);

Parameters

ppidl
Address of an ITEMIDLIST pointer that receives a copy of the PIDL that represents the absolute location of the folder. This PIDL must be relative to the desktop. This will normally be a copy of the PIDL that was passed to IPersistFolder::Initialize.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IPersistFolder2

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlobj.h.


IPersistFolder3

The IPersistFolder3 interface allows a folder object to implement nondefault handling of folder shortcuts. It is an extension of the IPersistFolder2 interface.

When to Implement

Namespace extensions implement this interface if they need to perform nondefault handling of folder shortcuts.

When to Use

Applications do not normally use this interface directly.

Methods

This interface extends the IPersistFolder and IPersistFolder2 interfaces. The following methods are specific to IPersistFolder3.

GetFolderTargetInfo | Provides the location and attributes of a folder shortcut's target folder.
InitializeEx | Initializes a folder, and specifies its location in the namespace. If the folder is a shortcut, the method also specifies the location of the target folder.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IPersistFolder3::GetFolderTargetInfo

Provides the location and attributes of a folder shortcut's target folder.

HRESULT GetFolderTargetInfo(
    PERSIST_FILESYSTEM_FOLDER_INFO *pfsfi
);

Parameters

pfsfi
[out] Address of a PERSIST_FOLDER_TARGET_INFO structure that is used to return the target folder's location and attributes.

Return Values

Returns NOERROR if successful, or an OLE error code otherwise.

Remarks

The PERSIST_FOLDER_TARGET_INFO structure might not be initialized by the caller. GetFolderTargetInfo should assign values to all members of the structure before returning it to the caller.

See Also

IPersistFolder3

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IPersistFolder3::InitializeEx

Initializes a folder, and specifies its location in the namespace. If the folder is a shortcut, the method also specifies the location of the target folder.

HRESULT InitializeEx(
  IBindCtx *pbc,
  LPCITEMIDLIST pidlRoot,
  const PERSIST_FOLDER_TARGET_INFO *ppfti
);

Parameters

pbc
[in] Address of an IBindCtx interface that provides the bind context. This parameter is set to NULL if not used.
pidlRoot
[in] Address of a fully qualified PIDL that specifies the absolute location of a folder or folder shortcut. The caller allocates and frees this PIDL.
ppfti
[in] Address of a PERSIST_FOLDER_TARGET_INFO structure that specifies the location of the target folder and its attributes. If ppfti points to a valid structure, pidlRoot represents a folder shortcut. If ppfti is set to NULL, pidlRoot represents a normal folder. In that case, InitializeEx should behave as if IPersistFolder::Initialize had been called.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

This function is an extended version of IPersistFolder::Initialize. It allows the Shell to initialize folder shortcuts as well as normal folders.

See Also

IPersistFolder3

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IPersistIDList Interface

This is preliminary documentation and is subject to change.

This interface provides methods that are used to persist item identifier lists.

IPersistIDList Members

LoadIDList | Loads a persisted item identifier list.
SaveIDList | Saves an item identifier list.

Interface Information

Stock Implementation | Shell32.dll
Custom Implementation | No
Inherits from | IPersist
Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


IPersistIDList::SaveIDList Method

This is preliminary documentation and is subject to change.

Saves an item identifier list.

Syntax

HRESULT SaveIDList(
    LPITEMIDLIST *ppidl
);

Parameters

ppidl
[out] Address of a pointer to the item identifier list to save.

Return Value

Returns S_OK if successful, or an error value otherwise.


IPersistIDList::LoadIDList Method

This is preliminary documentation and is subject to change.

Loads a persisted item identifier list.

Syntax

HRESULT LoadIDList(
    LPCITEMIDLIST pidl
);

Parameters

pidl
[in] Pointer to the item identifier list to load.

Return Value

Returns S_OK if successful, or an error value otherwise.


IProfferService Interface

This is preliminary documentation and is subject to change.

This interface provides a general mechanism for objects to offer services to other objects cited on the same host.

IProfferService Members

ProfferService | Makes a service available to other objects cited on the same host.
QueryService | Queries a specified service for a specified interface.
RevokeService | Makes a service unavailable that was previously available to other objects using IProfferService::ProfferService

Remarks

Objects expose a service call IQueryInterface on their host for this interface, then execute IProfferService::ProfferService.

Interface Information

Stock Implementation | None
Custom Implementation | No
Inherits from | IUnknown
Header | shobjidl.h
Minimum operating systems | Whistler

See Also

IObjectWithSite, IServiceProvider


IProfferService::RevokeService Method

This is preliminary documentation and is subject to change.

Makes a service unavailable that was previously available to other objects using IProfferService::ProfferService

Syntax

HRESULT RevokeService(
    DWORD dwCookie
);

Parameters

dwCookie
[in] Value of type DWORD that specifies an implementation-defined value used for identification purposes. The calling application receives this value from IProfferService::ProfferService.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IProfferService, IProfferService::ProfferService, IProfferService::QueryService


IProfferService::QueryService Method

This is preliminary documentation and is subject to change.

Queries a specified service for a specified interface.

Syntax

HRESULT QueryService(
    REFGUID guidService,
    REFIID riid,
    void **ppv
);

Parameters

guidService
[in] Value of type GUID that specifies the service being queried.
riid
[in] Value of type REFIID the specifies the interface being queried.
ppv
[in] Pointer to an interface pointer.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IProfferService, IProfferService::RevokeService


IProfferService::ProfferService Method

This is preliminary documentation and is subject to change.

Makes a service available to other objects cited on the same host.

Syntax

HRESULT ProfferService(
    REFGUID rguidService,
    IServiceProvider *psp,
    DWORD *pdwCookie
);

Parameters

rguidService
[in] Value of type GUID that specifies the service being offered.
psp
[in] Pointer to an IServiceProvider interface.
pdwCookie
[in] Pointer to a variable of type DWORD that receives an implementation-defined value used for identification purposes. The calling application must keep track of this value in the event it needs to execute IProfferService::RevokeService.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IProfferService, IProfferService::RevokeService


IProgressDialog

The IProgressDialog interface is exported by the progress dialog box object (CLSID_ProgressDialog). This object is a generic way to show a user how an operation is progressing. It is typically used when deleting, uploading, copying, moving, or downloading large numbers of files.

The progress dialog box object creates a modeless dialog box and allows the client to set its title, animation, text lines, and progress bar. The object then handles updating on a background thread and allows the user to cancel the operation. Optionally, it estimates the time remaining until the operation is complete and displays the information as a line of text.

When to Implement

Applications normally do not implement this interface. It is exported by the progress dialog box object for use by applications.

When to Use

Use this interface when your application needs to display a progress dialog box. To initialize the object:

  1. Create an in-process progress dialog box object (CLSID_ProgressDialog) with CoCreateInstance. Request a pointer to its IProgressDialog interface (IID_IProgressDialog).
  2. Call IProgressDialog::SetTitle to specify the dialog box title.
  3. Call IProgressDialog::SetAnimation to specify an AVI clip to be played while the operation progresses.
  4. Call IProgressDialog::SetCancelMsg to specify the message that will be displayed if the user cancels the operation.

To display the progress of the operation:

  1. Call IProgressDialog::StartProgressDialog to display the dialog box.
  2. Assign a numerical value to the total amount of work the operation will perform. Use any number that allows you to conveniently define the progress of the operation. For example, set this value to 100 if you want to specify the progress of the operation in terms of the percent that has been completed.
  3. Call IProgressDialog::Timer to reset the timer. This method sets the starting point that the progress dialog object uses to estimate the time remaining in the operation. If you do not call this method, the starting point will be the call to StartProgressDialog.
  4. As the operation progresses, periodically call IProgressDialog::SetProgress to update the dialog box as to how much of the operation has been completed. The progress dialog object will update its progress bar and recalculate its estimate of the remaining time. You can use any numerical measure of progress that is convenient. However, if you want to use values larger than 4GB, you must call IProgressDialog::SetProgress64 instead of IProgressDialog::SetProgress.
  5. Your application does not receive a notification if the user clicks the Cancel button to cancel the operation. As the operation progresses, periodically call IProgressDialog::HasUserCancelled to see if the user has clicked the Cancel button. Applications typically call this method each time they call IProgressDialog::SetProgress or IProgressDialog::SetProgress64.
  6. The dialog box displays three lines of text. An application can periodically call IProgressDialog::SetLine to display a message on one of these lines. This method is normally used to provide information on the current status of the operation. A typical message is something like: "Currently processing item XXX...". Messages are normally displayed on lines 1 and 2. You can display messages on line 3 only if you have not instructed the progress dialog object to estimate the remaining time by setting the PROGDLG_AUTOTIME flag in the dwFlags parameter of IProgressDialog::StartProgressDialog. In that case, the third text line is used to display the estimated time.

When the operation is complete:

  1. Call IProgressDialog::StopProgressDialog to close the dialog box.
  2. Release the progress dialog box object.

IProgressDialog exposes the following methods in addition to IUnknown.

Methods | Description
HasUserCancelled | Checks whether the user has canceled the operation.
SetAnimation | Specifies an AVI clip that will run in the dialog box.
SetCancelMsg | Sets a message to be displayed if the user cancels the operation.
SetLine | Displays a message.
SetProgress | Updates the progress dialog box with the current state of the operation.
SetProgress64 | Updates the progress dialog box with the current state of the operation.
SetTitle | Sets the title of the progress dialog box.
StartProgressDialog | Starts the progress dialog box.
StopProgressDialog | Stops the progress dialog box.
Timer | Resets the timer.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::HasUserCancelled

Checks whether the user has canceled the operation.

BOOL HasUserCancelled(VOID);

Parameters

None.

Remarks

The system does not send a message to the application when the user clicks the Cancel button. You must periodically use this function to poll the progress dialog box object to determine whether the operation has been canceled.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::SetAnimation

Specifies an AVI clip that will run in the dialog box.

HRESULT SetAnimation(
    HINSTANCE hInstAnimation,
    UINT idAnimation
);

Parameters

hInstAnimation
[in] Instance handle to the module from which the AVI resource should be loaded.
idAnimation
[in] AVI resource identifier. To create this value, use the MAKEINTRESOURCE macro. The control loads the AVI resource from the module specified by hInstAnimation.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method takes the instance handle specified by hInstAnimation and uses the common control's animation control to open and run a silent AVI clip. There are several restrictions as to what types of AVI clips can be used:

  • Clips cannot include sound.
  • The size of the AVI clip cannot exceed 272 by 60 pixels. Smaller rectangles can be used, but they might not be properly centered.
  • AVI clips must either be uncompressed or compressed with run-length (BI_RLE8) encoding. If you attempt to use an unsupported compression type, no animation will be displayed.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::SetCancelMsg

Sets a message to be displayed if the user cancels the operation.

HRESULT SetCancelMsg(
    LPCWSTR pwzCancelMsg,
    LPCVOID pvReserved
);

Parameters

pwzCancelMsg
[in] Pointer to a NULL-terminated Unicode string that contains the message to be displayed.
pvReserved
Reserved.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

Even though the user clicks Cancel, the application cannot immediately call IProgressDialog::StopProgressDialog to close the dialog box. The application must wait until the next time it calls IProgressDialog::HasUserCancelled to discover that the user has canceled the operation. Since this delay might be significant, the progress dialog box provides the user with immediate feedback by clearing text lines 1 and 2 and displaying the cancel message on line 3. The message is intended to let the user know that the delay is normal and that the progress dialog box will be closed shortly. It is typically is set to something like "Please wait while ...".

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::SetLine

Displays a message.

HRESULT SetLine(
    DWORD dwLineNum,
    LPCWSTR pwzString,
    BOOL fCompactPath,
    LPCVOID pvReserved
);

Parameters

dwLineNum
[in] Line number on which the text is to be displayed. Currently there are three lines—1, 2, and 3. If the PROGDLG_AUTOTIME flag was included in the dwFlags parameter when IProgressDialog::StartProgressDialog was called, only lines 1 and 2 can be used. The estimated time will be displayed on line 3.
pwzString
[in] NULL-terminated Unicode string that contains the text.
fCompactPath
[in] Value that is set to TRUE to have path strings compacted if they are too large to fit on a line. The paths are compacted with PathCompactPath.
pvReserved
[in] Reserved.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This function is typically used to display a message such as "Item XXX is now being processed." Normally, messages are displayed on lines 1 and 2, with line 3 reserved for the estimated time.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::SetProgress

Updates the progress dialog box with the current state of the operation.

HRESULT SetProgress(
    DWORD dwCompleted,
    DWORD dwTotal
);

Parameters

dwCompleted
[in] Application-defined value that indicates what proportion of the operation has been completed at the time the method was called.
dwTotal
[in] Application-defined value that specifies what value dwCompleted will have when the operation is complete.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

Use any convenient numerical measure of the progress of the operation. To use values larger than 4GB, you can instead call IProgressDialog::SetProgress64.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::SetProgress64

Updates the progress dialog box with the current state of the operation.

HRESULT SetProgress64(
    ULONGLONG ullCompleted,
    ULONGLONG ullTotal
);

Parameters

ullCompleted
[in] Application-defined value that indicates what proportion of the operation has been completed at the time the method was called.
ullTotal
[in] Application-defined value that specifies what value ullCompleted will have when the operation is complete.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method has exactly the same function as IProgressDialog::SetProgress but allows you to use values larger than one DWORD (4GB).

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::SetTitle

Sets the title of the progress dialog box.

HRESULT SetTitle(
    LPCWSTR pwzTitle
);

Parameters

pwzTitle
[in] Pointer to a NULL-terminated Unicode string that contains the dialog box title.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::StartProgressDialog

Starts the progress dialog box.

HRESULT StartProgressDialog(
    HWND hwndParent,
    IUnknown *punkEnableModless,
    DWORD dwFlags,
    LPCVOID pvReserved
);

Parameters

hwndParent
[in] Handle to the dialog box's parent window.
punkEnableModless
Reserved.
dwFlags
Flags that control the operation of the progress dialog box. This can be a combination of the following values.
Flag | Description
PROGDLG_NORMAL | Normal progress dialog box behavior.
PROGDLG_MODAL | The progress dialog box will be modal to the window specified by hwndParent. By default, a progress dialog box is modeless.
PROGDLG_AUTOTIME | Automatically estimate the remaining time and display the estimate on line 3. If this flag is set, IProgressDialog::SetLine can be used only to display text on lines 1 and 2.
PROGDLG_NOTIME | Do not show the "time remaining" text.
PROGDLG_NOMINIMIZE | Do not display a minimize button on the dialog box's caption bar.
PROGDLG_NOPROGRESSBAR | Do not display a progress bar. Normally, an application can quantitatively determine how much of the operation remains and periodically pass that value to IProgressDialog::SetProgress. The progress dialog box uses this information to update its progress bar. This flag is typically set when the calling application needs to wait for an operation to finish but does not have any quantitative information it can use to update the dialog box.
pvReserved
Reserved.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::StopProgressDialog

Stops the progress dialog box and removes it from the screen.

HRESULT StopProgressDialog(VOID);

Parameters

None.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IProgressDialog, IProgressDialog::HasUserCancelled

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IProgressDialog::Timer

Resets the progress dialog box timer to zero.

HRESULT Timer(
    DWORD dwTimerAction,
    LPCVOID pvReserved
);

Parameters

dwTimerAction
[in] Flags that indicate the action that should be taken by the timer. Currently there is only one value.
Flag | Description
PDTIMER_RESET | Resets the timer to zero. Progress will be calculated from the time this method is called.
pvReserved
Reserved.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

The timer is used to estimate the remaining time. It is started when your application calls IProgressDialog::StartProgressDialog. Unless your application will start immediately, it should call Timer just before starting the operation. This practice ensures that the time estimates will be as accurate as possible. This method should not be called after the first call to IProgressDialog::SetProgress.

See Also

IProgressDialog

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IPublishedApp Interface

This is preliminary documentation and is subject to change.

This interface represents an application to Add/Remove Programs in Control Panel.

IPublishedApp Members

GetPublishedAppInfo | Retrieves publishing-related information about an application published by an application publisher.
Install | Installs an application published by an application publisher. This method is invoked when the user selects Add or Add Later in Add/Remove Programs in Control Panel.
Unschedule | Cancels the installation of an application published by an application publisher. This method is called in each of the following circumstances: 1. The user selected the Do not add program option in the Add Later dialog box in Add/Remove Programs in Control Panel. 2. The user has selected an installation time later than either the expiration time or the assigned time as specified in the published application information (cf. IPublishedApp::GetPublishedAppInfo. In these circumstances, implementations are expected to cancel any scheduled installation for the application.

Remarks

To publish applications to Add/Remove Programs in Control Panel, you must support IEnumPublishedApps, IAppPublisher and IPublishedApp.

Interface Information

Stock Implementation | None
Custom Implementation | No
Inherits from | IShellApp
Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IEnumPublishedApps, IAppPublisher


IPublishedApp::Unschedule Method

This is preliminary documentation and is subject to change.

Cancels the installation of an application published by an application publisher. This method is called in each of the following circumstances: 1. The user selected the Do not add program option in the Add Later dialog box in Add/Remove Programs in Control Panel. 2. The user has selected an installation time later than either the expiration time or the assigned time as specified in the published application information (cf. IPublishedApp::GetPublishedAppInfo. In these circumstances, implementations are expected to cancel any scheduled installation for the application.

Syntax

HRESULT Unschedule(VOID);

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IAppPublisher, IShellApp, IPublishedApp


IPublishedApp::Install Method

This is preliminary documentation and is subject to change.

Installs an application published by an application publisher. This method is invoked when the user selects Add or Add Later in Add/Remove Programs in Control Panel.

Syntax

HRESULT Install(
    SYSTEMTIME *pInstallTime
);

Parameters

pInstallTime
[in] Pointer to a SYSTEMTIME structure that contains the time the user elected to schedule installation via the Add Later button in Add/Remove Programs. This option is only available if the application supports scheduled installation (cf. IShellApp::GetPossibleActions). If this parameter is NULL, the application should be installed immediately.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IAppPublisher, IPublishedApp, IShellApp::GetPossibleActions


IPublishedApp::GetPublishedAppInfo Method

This is preliminary documentation and is subject to change.

Retrieves publishing-related information about an application published by an application publisher.

Syntax

HRESULT GetPublishedAppInfo(
    PUBAPPINFO *pInfo
);

Parameters

pInfo
[out] Pointer to an PUBAPPINFO structure that returns the application information.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The dwMask member of the PUBAPPINFO structure indicates which members have been requested. Note that Add/Remove Programs will not set the PAI_SCHEDULEDTIME and PAI_EXPIREDTIME bits. However, the corresponding values stScheduled and stExpired will be used when applicable if the implementation provides them. A publisher should provide this data if it is available.

Example

The example shows a sample implementation:

HRESULT CPubApp::GetPublishedAppInfo(PUBAPPINFO *pInfo)
{
    if (sizeof(PUBAPPINFO) != pInfo->cbSize)
        return E_FAIL;

    // Add/Remove Programs will use these items but will not ask for them.

    pInfo->dwMask |= (PAI_EXPIRETIME | PAI_SCHEDULEDTIME);

    // First save off the mask of requested data items.

    const DWORD dwMask = pInfo->dwMask;

    // Zero-out the mask.  We?ll set bits as we get items.

    pInfo->dwMask = 0;

    // Call an internal function that obtains data and sets
    // bits in pInfo->dwMask for each item obtained.

    return get_pub_app_info(pInfo, dwMask);
}

See Also

PUBAPPINFO, IEnumPublishedApps, IAppPublisher


IQueryAssociations

When you create a file association by defining a file class and associating it with an application, a variety of related information can be stored in the registry. This interface is a utility exposed by the Shell that simplifies the process of retrieving this information from HKEY_CLASSES_ROOT and HKEY_CURRENT_USER. A complete registry path or HKEY value is not required. Instead, you can retrieve information based on criteria such as the file name extension or executable name. For a discussion of file associations, see Creating a File Association.

When to Implement

This interface is exposed by the Shell or by namespace extensions to simplify handling file associations.

When to Use

Use this interface if you need information from the registry related to file associations. For example, you can use this interface to retrieve information associated with a file name extension such as the command string of one of its verbs.

To use this interface, you must first retrieve a pointer to it. Typically, you retrieve an IQueryInterface pointer by calling a Shell object's IShellFolder::GetUIObjectOf method. You can also retrieve an interface pointer by calling AssocCreate. Then, initialize it with IQueryAssociations::Init. This method sets the root key that will be used when you call any of the remaining three methods to retrieve information from the registry. They will look only below the root key. You must release the interface when you no longer need it.

The IQueryAssociations interface is useful if you need to repeatedly query the registry for information. Once the interface is initialized, the overhead of calling the various methods is relatively small. There are also several related functions, listed in the See Also section, that allow you to retrieve the same information from the registry with a single function call. While they are simpler to use, they incur the overhead of creating and initializing IQueryAssociations each time they are called. Because of this, they are best suited for single use.

IQueryAssociations exposes the following methods.

Method | Description
GetData | Retrieves binary data associated with a specified value.
GetEnum | Not implemented.
GetKey | Retrieves the HKEY value associated with a specified key.
GetString | Retrieves the string associated with a specified value.
Init | Initializes the interface and sets the root key.

See Also

AssocQueryKey, AssocQueryString, AssocQueryStringByKey

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IQueryAssociations::GetData

Searches for and retrieves file association-related binary data from the registry.

HRESULT GetData(
    ASSOCF flags,
    ASSOCDATA data,
    LPCWSTR pwszExtra,
    LPVOID pvOut,
    DWORD *pcbOut
);

Parameters

flags
[in] ASSOCF value that can be used to control the search.
data
[in] ASSOCDATA value that specifies the type of data that is to be returned.
pwszExtra
[in] Pointer to an optional NULL-terminated Unicode string with information about the location of the data. It is normally set to a Shell verb such as open. Set this parameter to NULL if it is not used.
pvOut
[out] Pointer used to return the data value.
pcbOut
[out] Pointer to a value that will hold the size of pvOut, in bytes.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IQueryAssociations

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IQueryAssociations::GetEnum

This method is not currently implemented.

See Also

IQueryAssociations

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IQueryAssociations::GetKey

Searches for and retrieves a file association-related key from the registry.

HRESULT GetKey(
    ASSOCF flags,
    ASSOCKEY key,
    LPCWSTR pwszExtra,
    HKEY *phkeyOut
);

Parameters

flags
[in] ASSOCF value that can be used to control the search.
key
[in] ASSOCKEY value that specifies the type of key that is to be returned.
pwszExtra
[in] Pointer to an optional NULL-terminated Unicode string with information about the location of the key. It is normally set to a Shell verb such as open. Set this parameter to NULL if it is not used.
phkeyOut
[out] Pointer to the key's HKEY value.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

See Also

IQueryAssociations

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IQueryAssociations::GetString

Searches for and retrieves a file association-related string from the registry.

HRESULT GetString(
    ASSOCF flags,
    ASSOCSTR str,
    LPCWSTR pwszExtra,
    LPWSTR pwszOut,
    DWORD *pcchOut
);

Parameters

flags
[in] Flag that can be used to control the search. It can be any combination of the following ASSOCF values:
  • ASSOCF_IGNOREBASECLASS
  • ASSOCF_NOFIXUPS
  • ASSOCF_NOTRUNCATE
  • ASSOCF_NOUSERSETTINGS
  • ASSOCF_REMAPRUNDLL
  • ASSOCF_VERIFY
str
[in] ASSOCSTR value that specifies the type of string that is to be returned.
pwszExtra
[in] Pointer to an optional NULL-terminated Unicode string with information about the location of the string. It is normally set to a Shell verb such as open. Set this parameter to NULL if it is not used.
pwszOut
[out] Pointer to a NULL-terminated Unicode string used to return the requested string.
pcchOut
[in/out] Pointer to a value that is set to the number of characters in the pszOut buffer. It returns the number of characters actually placed in the buffer. If the ASSOCF_NOTRUNCATE flag is set in flags and the buffer specified in pcchOut is too small, the function will return E_POINTER and pcchOut will point to the required size of the buffer.

Return Values

Returns S_OK if successful, E_POINTER if the buffer is too small, or an OLE error value otherwise.

See Also

IQueryAssociations

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IQueryAssociations::Init

Initializes the IQueryAssociations interface and sets the root key to the appropriate ProgID.

HRESULT Init(
    ASSOCF flags,
    LPCWSTR pwszAssoc,
    HKEY hkProgid,
    HWND hwnd
);

Parameters

flags
[in] Flag that specifies how the search is to be initialized. It is normally set to NULL, but it can also take one of the following ASSOCF values:
  • ASSOCF_INIT_BYEXENAME
  • ASSOCF_INIT_DEFAULTTOFOLDER
  • ASSOCF_INIT_DEFAULTTOSTAR
pwszAssoc
[in] Unicode string that is used to determine the root key. If a value is specified for hkProgid, set this parameter to NULL. Four types of string can be used.
String type | Description
File name extension | A file name extension, such as .txt.
CLSID | A CLSID GUID in the standard "{GUID}" format.
ProgID | An application's ProgID, such as Word.Document.8.
Executable name | The name of an application's .exe file. The ASSOCF_OPEN_BYEXENAME flag must be set in flags.
hkProgid
[in] HKEY value of the key that will be used as a root key. The search will look only below this key. If a value is specified for pwszAssoc, set this parameter to NULL.
hwnd
Reserved. Set to NULL.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This method initializes the interface, and is also called each time you need to specify a new root key. You can use pwszAssoc to specify a string, such as a file name extension or its associated ProgID, that identifies the root key. You can also specify the root key's HKEY value. Init will then use this information to locate the root key in the registry. Subsequent calls to the other IQueryAssociations methods will use it as their starting point and search for the information in the root key's subkeys.

See Also

IQueryAssociations

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IQueryContinue Interface

This is preliminary documentation and is subject to change.

This interface provides a simple, standard mechanism for objects to query a client for permission to continue an operation. Clients of UserNotification, for example, must pass an implementation of IQueryContinue to the Show method.

IQueryContinue Members

QueryContinue Returns TRUE if the operation associated with the current instance of this interface should continue.

Interface Information

Stock Implementation | None
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IUserNotification, UserNotification


IQueryContinue::QueryContinue Method

This is preliminary documentation and is subject to change.

Returns TRUE if the operation associated with the current instance of this interface should continue.

Syntax

HRESULT QueryContinue(VOID);

Return Value

Returns S_OK if the caller should continue, S_FALSE if not.

Remarks

In typical usage, a pointer to an IQueryContinue interface is passed to a method of another object. That object, in turn, runs this method periodically to determine whether to continue its actions.

See Also

IUserNotification, UserNotification


IQueryInfo

The Shell uses the IQueryInfo interface to retrieve flags and info tip information for an item that resides in an IShellFolder implementation. Info tips are usually displayed inside of a ToolTip control.

When to Implement

Implement IQueryInfo to provide flags and text information that differs from the normal text that is displayed for an item in a folder. For example, if your folder contained file objects, you could use the info tip to provide the entire path and file name for the item rather than just the file name.

This interface is obtained by calling IShellFolder::GetUIObjectOf and passing IID_IQueryInfo for the interface identifier. The item for which info tip information is being requested is contained in the apidl argument of the IShellFolder::GetUIObjectOf call. If IQueryInfo is not supplied by the folder, the Shell will use the standard display text in the info tip.

When to Use

In most cases, you do not use this interface directly. The Shell will use this interface when it requires additional information to display inside of an info tip. However, you can use IQueryInfo directly if you want to obtain info tip information from another object.

IQueryInfo Methods | Description
GetInfoFlags | Retrieves the information flags for an item.
GetInfoTip | Retrieves the info tip text for an item.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IQueryInfo::GetInfoFlags

Retrieves the information flags for an item. This method is not currently used.

HRESULT GetInfoFlags(
    DWORD *pdwFlags
);

Parameters

pdwFlags
[out] Pointer to a value that receives the flags for the item. If no flags are to be returned, this value should be set to zero.

Return Values

Returns S_OK if pdwFlags returns any flag values, or an OLE-defined error value otherwise.

See Also

IQueryInfo

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IQueryInfo::GetInfoTip

Retrieves the info tip text for an item.

HRESULT GetInfoTip(
    DWORD dwFlags,
    LPWSTR *ppwszTip
);

Parameters

dwFlags
Not currently used.
ppwszTip
[out] Address of a Unicode string pointer that receives the tip string pointer. Applications that implement this method must allocate memory for ppwszTip by calling SHGetMalloc. Calling applications must call SHGetMalloc to free the memory when it is no longer needed.

Return Values

Returns S_OK if the function succeeds. If no info tip text is available, ppwszTip is set to NULL. Otherwise, returns an OLE-defined error value.

See Also

IQueryInfo

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IReconcilableObject

The IReconcilableObject interface carries out the reconciliation of a document. The briefcase reconciler is responsible for implementing this interface.
IReconcilableObject Methods | Description
GetProgressFeedbackMaxEstimate | Receives estimate of work required to complete a reconciliation.
Reconcile | Reconciles the state of an object with one or more other objects.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IReconcilableObject::GetProgressFeedbackMaxEstimate

Retrieves an estimated measurement of the amount of work required to complete a reconciliation. Reconcilers typically use this method to estimate the work needed to reconcile an embedded document. This value corresponds to a similar value that is passed with the IReconcileInitiator::SetProgressFeedback method during reconciliation.

HRESULT IReconcilableObject::GetProgressFeedbackMaxEstimate(
    IMoniker ** pulProgressMax
   );

Parameters

pulProgressMax
Address of the variable to receive the work estimate value.

Return Values

Returns S_OK if successful, or one of the following error values otherwise:
OLE_E_NOTRUNNING | The object is an OLE embedded document that must be run before this operation can be carried out. The object state is unchanged as a result of the call.
E_UNEXPECTED | Unspecified error.

See Also

IReconcilableObject

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IReconcilableObject::Reconcile

Reconciles the state of an object with one or more other objects. The reconciliation updates the internal state of the object by merging the states of all objects to form a combined state.

HRESULT IReconcilableObject::Reconcile(
    IReconcileInitiator *pInitiator,
    DWORD dwFlags,
    HWND hwndOwner,
    HWND hwndProgressFeedback,
    ULONG ulcInput,
    IMoniker **rgpmkOtherInput,
    LONG *plOutIndex,
    IStorage *pstgNewResidues,
    void *pvReserved
   );

Parameters

pInitiator
Address of the IReconcileInitiator interface for the initiator of the reconciliation process. This parameter must not be NULL.
dwFlags
Control flags for the reconciliation. This parameter may be zero or a combination of these values:
RECONCILEF_FEEDBACKWINDOWVALID | The hwndProgressFeedback parameter is valid.
RECONCILEF_MAYBOTHERUSER | The briefcase reconciler can prompt for user interaction if it is needed. Without this value, user interaction is not permitted. The hwndOwner parameter is valid.
RECONCILEF_NORESIDUESOK | The briefcase reconciler can ignore requests for residues and carry out reconciliation. Reconcilers that do not support residues should check for this value whenever an initiator requests residues. Without this value, a reconciler that does not support residues must immediately return REC_E_NORESIDUES.
RECONCILEF_OMITSELFRESIDUE | The briefcase reconciler can discard any residue associated with this object. Initiators typically use this value for reconciliations that loop from generation to generation.
RECONCILEF_ONLYYOUWERECHANGED The Reconcile method is being called to propagate changes in the changed object to other unchanged objects. This value will only be set if the following key exists in the registry.

HKEY_CLASSES_ROOT\
   CLSID\
      <clsid_of_reconciler>\
         SingleChangeHook

If this key is not present in the registry, the initiator carries out reconciliation by making the other unchanged objects binary identical copies of the changed object. The rgpmkOtherInput monikers identify the other objects. This value will only be set in dwFlags if RECONCILEF_YOUMAYDOTHEUPDATES is also set. If the briefcase reconciler completes the updates itself successfully, REC_S_IDIDTHEUPDATES should be returned and the variable pointed to by the plOutIndex parameter should be set to -1L. Note that S_OK should not be returned on success if this value is set in dwFlags. The initiator will not save the source object's storage if Reconcile returns REC_S_IDIDTHEUPDATES. If the reconciler wishes to fall back to the initiator's bit copy implementation, it may return S_FALSE.

RECONCILEF_RESUMEDRECONCILIATION | The briefcase reconciler should resume reconciliation, using the partial residues provided. Without this value, the reconciler should ignore any "considered but rejected" information in any of the input versions.
RECONCILEF_YOUMAYDOTHEUPDATES | The briefcase reconciler can perform the updates. Without this value, the reconciler cannot perform the updates. If reconciliation is completed successfully, the reconciler should return REC_S_IDIDTHEUPDATES if it performed the updates or S_OK if it did not perform the updates.
hwndOwner
Handle to the window to be used as the parent for any child windows that the briefcase reconciler creates. This parameter is valid only if RECONCILEF_MAYBOTHERUSER is specified in dwFlags.
hwndProgressFeedback
Handle to the progress feedback window to be displayed by the initiator. This parameter is valid only if RECONCILEF_FEEDBACKWINDOWVALID is specified in dwFlags. The briefcase reconciler may call the SetWindowText function using this window handle to display additional reconciliation status information to the user.
ulcInput
Number of versions or partial residues specified in dwFlags. This parameter must not be zero.
rgpmkOtherInput
Address of an array that contains the addresses of the monikers to use to access the versions or partial residues to be reconciled.
plOutIndex
Address of the variable that receives an index value indicating whether the result of the reconciliation is identical to one of the initial versions. The variable is set to -1L if the reconciliation result is a combination of two or more versions. Otherwise, it is a zero-based index, with 0 indicating this object, 1 indicating the first version, 2 indicating the second version, and so on.
pstgNewResidues
Address of the IStorage interface used to store the new residues. This parameter can be NULL to indicate that residues should not be saved.
pvReserved
Reserved; must be NULL.

Return Values

Returns one of the following values if successful:
S_OK | Reconciliation completed successfully, and the changes must be propagated to the other objects.
S_FALSE | No reconciliation actions were performed. The briefcase reconciler wishes to fall back to the initiator's bit copy implementation. This value may only be returned if RECONCILEF_ONLYYOUWERECHANGED is set in dwFlags.
REC_S_IDIDTHEUPDATES | Reconciliation was completed successfully, and all the objects involved (the object implementing the Reconcile method and all the other objects described by rgpmkOtherInput) have been updated appropriately. The initiator does not need, therefore, to do anything further to propagate the changes. The variable pointed to by plOutIndex should be set to -1L if Reconcile returns this value. The initiator will not save the source object's storage if Reconcile returns this value. This value may only be returned if RECONCILEF_YOUMAYDOTHEUPDATES was set in dwFlags.
REC_S_NOTCOMPLETE | The briefcase reconciler completed some, but not all, of the reconciliation. It may need user interaction. The changes will not be propagated to other objects.
REC_S_NOTCOMPLETEBUTPROPAGATE | The briefcase reconciler completed some, but not all, of the reconciliation. It may need user interaction. The changes will be propagated to the other objects.

Otherwise, this method returns one of the following error values:
REC_E_NORESIDUES | The briefcase reconciler does not support the generation of residues, so the request for residues is denied. The state of the object is unchanged.
REC_E_ABORTED | The briefcase reconciler stopped reconciliation in response to a termination request from the initiator (see IReconcileInitiator::SetAbortCallback for more information). The state of the object is unspecified.
REC_E_TOODIFFERENT | Reconciliation cannot be carried out because the provided document versions are too dissimilar.
REC_E_INEEDTODOTHEUPDATES | The RECONCILEF_YOUMAYDOTHEUPDATES flag was not set when the object's Reconcile implementation was called; this implementation requires that this value be set in the dwFlags parameter.
OLE_E_NOTRUNNING | The object is an OLE embedded object that must be run before this operation can be carried out. The state of the object is unchanged.
E_UNEXPECTED | Unspecified error.

See Also

IReconcilableObject

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IReconcileInitiator

The IReconcileInitiator interface provides the briefcase reconciler with the means to notify the initiator of its progress, to set a termination object, and to request a given version of a document. The initiator is responsible for implementing this interface.
IReconcileInitiator Methods | Description
SetAbortCallback | Sets the object through which the initiator can terminate a reconciliation.
SetProgressFeedback | Indicates the amount of progress in the reconciliation.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IReconcileInitiator::SetAbortCallback

Sets the object through which the initiator can asynchronously terminate a reconciliation. A briefcase reconciler typically sets this object for reconciliations that are lengthy or involve user interaction.

HRESULT IReconcileInitiator::SetAbortCallback(
    IUnknown *pUnkForAbort
   );

Parameters

pUnkForAbort
Address of the IUnknown interface for the object. The initiator signals a request to terminate the reconciliation by using the IUnknown::Release method to release the object. This parameter may be NULL to direct the initiator to remove the previously specified object.

Return Values

Returns the S_OK value if successful, or one of the following error values otherwise:
REC_E_NOCALLBACK | The initiator does not support termination of reconciliation operations and does not hold the specified object.
E_UNEXPECTED | Unspecified error.

Remarks

The initiator can accept or reject the object. If the initiator accepts the object, the briefcase reconciler must remove the object by calling this method with a NULL parameter when the reconciliation is complete. Because the reconciler removes the object after completing reconciliation, there may be times when the initiator releases the object after reconciliation is complete. In such cases, the reconciler ignores the request to terminate.

If the reconciliation is terminated, the IReconcilableObject::Reconcile method must return either the REC_E_ABORTED or REC_E_NOTCOMPLETE value.

See Also

IReconcileInitiator

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IReconcileInitiator::SetProgressFeedback

Indicates the amount of progress the briefcase reconciler has made toward completing the reconciliation. The amount is a fraction and is computed as the quotient of the ulProgress and ulProgressMax parameters. Reconcilers should call this method periodically during their reconciliation process.

HRESULT IReconcileInitiator::SetProgressFeedback(
    ULONG ulProgress,
    ULONG ulProgressMax
   );

Parameters

ulProgress
Numerator of the progress fraction.
ulProgressMax
Denominator of the progress fraction.

Return Values

Returns the S_OK value if successful, or the E_UNEXPECTED value if an unspecified error occurred.

Remarks

The initiator typically uses this measure of progress to update a thermometer gauge or some other form of visual feedback for the user. The briefcase reconciler can change the value of ulProgressMax from call to call. This means successive calls to this method do not necessarily indicate steady forward progress. Backward progress is legal, although not desirable. It is the responsibility of the initiator to determine whether backward progress should be revealed to the user.

See Also

IReconcileInitiator

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in reconcil.h.


IRemoteComputer

The IRemoteComputer interface is used to enumerate or initialize a namespace extension when it is invoked on a remote object. This interface is used, for example, to initialize the remote printers virtual folder.

When to Implement

Implement IRemoteComputer when your namespace extension may be invoked on a remote computer.

When to Use

You do not call this interface directly. IRemoteComputer is used by the operating system only when it has confirmed that your application is aware of this interface.

IRemoteComputer implements IUnknown and the following methods:
RemoteComputer Methods | Description
Initialize | Used by the explorer to initialize or enumerate a namespace extension invoked on a remote object.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRemoteComputer::Initialize

Used by Windows Explorer or Microsoft® Internet Explorer when it is initializing or enumerating a namespace extension invoked on a remote computer.

HRESULT Initialize(
    WCHAR *pszMachine,
    BOOL bEnumerating
);

Parameters

pszMachine
Machine name of the remote computer.
bEnumerating
Value that is set to TRUE if Windows Explorer is enumerating the namespace extension, or FALSE if it is initializing it.

Return Values

Returns S_OK if successful, or standard OLE error values otherwise.

Remarks

If failure is returned, the extension won't appear for the specified computer. Otherwise, the extension will appear and target the remote computer.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IResolveShellLink

The IResolveShellLink interface allows an application to request that a Shell folder object resolve a link for one of its items. With namespace extensions, shortcut objects (.lnk files) implement the essential functionality of IShellLink::Resolve by calling IResolveShellLink::ResolveShellLink. IResolveShellLink is exported by a link resolution object that is created on request by the Shell folder. To retrieve a pointer to a link resolution object's IResolveShellLink interface:

  • For an object that is contained by a folder, call the folder's IShellFolder::GetUIObjectOf method and request an IResolveShellLink pointer (IID_IResolveShellLink).
  • For the folder object itself, call the folder's IShellFolder::CreateViewObject method and request an IResolveShellLink pointer (IID_IResolveShellLink).

When to Implement

Namespace extensions implement this object to support link resolution.

When to Use

This interface is not normally used by applications.

Methods

IResolveShellLink exposes the following method in addition to IUnknown.

ResolveShellLink Requests that a folder object resolve a Shell link.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IResolveShellLink::ResolveShellLink

Requests that a folder object resolve a Shell link.

HRESULT ResolveShellLink(
    IUnknown *punk,
    HWND hwnd,
    DWORD fFlags
);

Parameters

punk
[in] Address of the object's IShellLink interface. This interface can be queried to determine the contents of the link.
hwnd
[in] Handle to the window that the Shell will use as the parent for a dialog box. The Shell displays the dialog box if it needs to prompt the user for more information while resolving a Shell link.
fFlags
[in] Action flags. This parameter can be a combination of the following values.
SLR_INVOKE_MSI | Call the Microsoft® Windows® Installer.
SLR_NOLINKINFO | Disable distributed link tracking. By default, distributed link tracking tracks removable media across multiple devices based on the volume name. It also uses the UNC path to track remote file systems whose drive letter has changed. Setting SLR_NOLINKINFO disables both types of tracking.
SLR_NO_UI | Do not display a dialog box if the link cannot be resolved. When SLR_NO_UI is set, the high-order word of fFlags specifies a time-out duration, in milliseconds. The function returns if the link cannot be resolved within the time-out duration. If the high-order word is set to zero, the time-out duration defaults to 3000 milliseconds (3 seconds).
SLR_NOUPDATE | Do not update the link information.
SLR_NOSEARCH | Do not execute the search heuristics.
SLR_NOTRACK | Do not use distributed link tracking.
SLR_UPDATE | If the link object has changed, update its path and list of identifiers. If SLR_UPDATE is set, you do not need to call IPersistFile::IsDirty to determine whether the link object has changed.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

This method should attempt to find the target of a Shell link, even if the target has been moved or renamed.

See Also

IResolveShellLink

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRunnableTask

The IRunnableTask interface is a free-threaded interface that can be exposed by an object to allow operations to be performed on a background thread. For example, if the IExtractImage::GetLocation method returns E_PENDING, the caller is permitted to extract the image on a background thread.

When to Implement

Implement IRunnableTask if your namespace extension is free-threaded, and you want to allow a task such as icon extraction to be managed by a scheduler. Only the Run and IsRunning methods must be implemented. If you do not want to implement Kill, Resume, and Suspend, simply have them return E_NOTIMPL.

If you are using IRunnableTask to extract an image on a background thread, that is, if the object exposes IExtractImage, then Run is not necessary, as the system will use IExtractImage::Extract to manage the task. The other methods (Kill, Resume, and Suspend) are optional in this case, but will be used by the system if they are implemented.

When to Use

You do not call this interface directly. IRunnableTask is used by the operating system only when it has confirmed that your application is aware of this interface.

IRunnableTask implements IUnknown and the following five methods.
IRunnableTask Methods | Description
IsRunning | Used to determine the current state of the task.
Kill | Use to stop execution.
Resume | Use to resume execution.
Run | Use to start execution
Suspend | Use to suspend execution

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRunnableTask::IsRunning

Used to request information on the state of a task, such as thumbnail extraction.

LONG IsRunning( void );

Return Values

Returns one of the following values to indicate the current execution state.
IRTIR_TASK_NOT_RUNNING | Extraction has not yet started.
IRTIR_TASK_RUNNING | The task is running.
IRTIR_TASK_SUSPENDED | The task is suspended.
IRTIR_TASK_PENDING | The thread has been killed but has not completely shut down yet.
IRTIR_TASK_FINISHED | The task is finished.

Remarks

This method must be implemented.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRunnableTask::Kill

Used to request that a task be stopped.

HRESULT Kill(
    BOOL fUnused
);

Parameters

fUnused
Not currently used.

Return Values

Returns NOERROR if successful, or standard OLE-defined error codes otherwise.

Remarks

Implementation of this method is optional. If you do not wish to support this functionality, create a token implementation that simply returns E_NOTIMPL.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRunnableTask::Resume

Used to request that a task resume.

HRESULT Resume( void );

Return Values

Return NOERROR if successful, or standard OLE-defined error codes otherwise.

Remarks

Implementation of this method is optional. If you do not wish to support this functionality, create a token implementation that simply returns E_NOTIMPL.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRunnableTask::Run

Used to request that a task start.

HRESULT Run( void );

Return Values

Return NOERROR when execution is complete. If execution is suspended, Run should return E_PENDING. Return standard OLE-defined error codes otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IRunnableTask::Suspend

Used to request that a task be suspended.

HRESULT Suspend( void );

Return Values

Return NOERROR if successful, or standard OLE-defined error codes otherwise.

Remarks

Implementation of this method is optional. If you do not wish to support this functionality, create a token implementation that simply returns E_NOTIMPL.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellApp Interface

This is preliminary documentation and is subject to change.

This interface represents an application to the Shell and other clients. It provides general information about the application including a list of supported management actions and whether it is currently installed.

IShellApp Members

GetAppInfo | Retrieves general information about an application.
GetCachedSlowAppInfo | Retrieves information for the application that may be from a "slow" source.
GetPossibleActions | Retrieves a bit mask of management actions allowed for an application.
GetSlowAppInfo | Retrieves information for the application that may be from a "slow" source.
IsInstalled | Retrieves a value indicating whether the a specified application is currently installed.

Interface Information

Stock Implementation | None
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IPublishedApp


IShellApp::IsInstalled Method

This is preliminary documentation and is subject to change.

Retrieves a value indicating whether the a specified application is currently installed.

Syntax

HRESULT IsInstalled(VOID);

Return Value

Returns one of the following values:

S_OK | The application is installed.
S_FALSE | The appliation is not installed.

Remarks

Application publishers should determine if the application is currently installed and return S_OK if so, or S_FALSE if not.

See Also

IAppPublisher, IShellApp, IPublishedApp


IShellApp::GetSlowAppInfo Method

This is preliminary documentation and is subject to change.

Retrieves information for the application that may be from a "slow" source.

Syntax

HRESULT GetSlowAppInfo(
    SLOWAPPINFO *pInfo
);

Parameters

pInfo
[out] Pointer to a SLOWAPPINFO structure in which to return application information.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Implementations of IPublishedApp should return E_NOTIMPL. This method is used internally by Add/Remove Programs for installed applications.

See Also

IAppPublisher, IShellApp, IPublishedApp


IShellApp::GetPossibleActions Method

This is preliminary documentation and is subject to change.

Retrieves a bit mask of management actions allowed for an application.

Syntax

HRESULT GetPossibleActions(
    DWORD *pdwActions
);

Parameters

pdwActions
[out] Pointer to a variable of type DWORD that returns the bit mask of supported actions. The bit flags are described in APPACTIONFLAGS.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Of the set of APPACTIONFLAGS bit masks, Add/Remove Programs only recognizes APPACTION_INSTALL and APPACTION_ADDLATER.

See Also

IAppPublisher, IPublishedApp


IShellApp::GetCachedSlowAppInfo Method

This is preliminary documentation and is subject to change.

Retrieves information for the application that may be from a "slow" source.

Syntax

HRESULT GetCachedSlowAppInfo(
    SLOWAPPINFO *pInfo
);

Parameters

pInfo
[out] Pointer to a SLOWAPPINFO structure in which to return application information.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Implementations of IPublishedApp return E_NOTIMPL. This method is used internally by Add/Remove Programs for installed applications.

Unlike IShellApp::GetSlowAppInfo, this method can return information that has been cached.

See Also

IAppPublisher, IShellApp, IPublishedApp


IShellApp::GetAppInfo Method

This is preliminary documentation and is subject to change.

Retrieves general information about an application.

Syntax

HRESULT GetAppInfo(
    APPINFODATA *pInfo
);

Parameters

pInfo
[out] Pointer to an APPINFODATA structure that returns the application information.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Note The Add/Remove Programs control panel applet will set the cbSize and dwMask members of the APPINFODATA structure.
Your implementation should validate cbSize by comparing it with the size of APPINFODATA. If cbSize does not equal the size of APPINFODATA, this method should return an OLE error value like E_FAIL.

Add/Remove Programs in Control Panel will set the dwMask member of the APPINFODATA structure to indicate that you should return AIM_DISPLAYNAME and AIM_SUPPORTURL. For each value that you return in APPINFODATA, you must set the corresponding bit in dwMask. All other bits should be cleared.

Example

Here is a sample of how to use the dwMask bits::

HRESULT CPubApp::GetAppInfo(APPINFODATA *pData)
{
    if (sizeof(APPINFODATA) != pData->cbSize)
        return E_FAIL;

    // First save off the mask of requested data items.

    const DWORD dwMask = pData->dwMask;

    // Zero-out the mask.  We?ll set bits as we get items.

    pData->dwMask = 0;

    // Call an internal function that obtains data and sets
    // bits in pData->dwMask for each item obtained.

    return get_app_info_data(pData, dwMask);

}

See Also

APPINFODATA, IAppPublisher, IPublishedApp::GetPublishedAppInfo


IShellBrowser

The IShellBrowser interface is exposed by Windows Explorer and the Open File common dialog box to provide services for namespace extensions. It a companion to the IShellView interface exposed by extensions. IShellBrowser is similar to the site interfaces that are often found in OLE hosting situations, such as the IOleControl and IOleControlSite. Extensions use IShellBrowser to communicate with Windows Explorer for such purposes as customizing UI elements like menus, status text, and tool bars. This interface also provides the extension with a way to access storage to save its persistent view state.

IShellBrowser derives from the IOleWindow interface, and it represents the container's top-level window. Extensions that implement a custom folder view call the IOleWindow::GetWindow method to retrieve the folder view's window handle from Windows Explorer. They then create a child of this window to display information in folder view.

IShellBrowser also allows extensions to do a variety of other tasks, including:

  • Insert menus into the composite menu, install the composite menu into the appropriate window frame, and remove the container's menu elements from the composite menu.
  • Set and display status text.
  • Enable or disable the frame's modeless dialog boxes.
  • Translate accelerator keystrokes intended for the container's frame.

When to Implement

Applications do not implement this interface.

When to Use

When implementing a namespace extension use the IShellBrowser implementation that is passed to IShellView::CreateViewWindow to communicate with Windows Explorer.

Methods

IShellBrowser is derived from IOleWindow. The following methods are specific to IShellBrowser:
BrowseObject | Tells Windows Explorer to browse in another folder.
EnableModelessSB | Enables or disables modeless windows of Windows Explorer, such as a floating toolbar.
GetControlWindow | Retrieves the window handle to a Windows Explorer control.
GetViewStateStream | Returns a view-specific stream that can be used to read and write the persistent data for a view.
InsertMenusSB | Inserts Windows Explorer's menu items to an empty menu created by the view.
OnViewWindowActive | Informs Windows Explorer that the view was activated.
QueryActiveShellView | Returns the currently activated (displayed) Shell view object.
RemoveMenusSB | Instructs the container to remove its items from a composite menu. The tasks it performs are the opposite of InsertMenusSB tasks.
SendControlMsg | Sends messages to Windows Explorer controls.
SetMenuSB | Installs the composite menu in Windows Explorer.
SetStatusTextSB | Sets and displays status text in the Windows Explorer window.
SetToolbarItems | Adds toolbar items to Windows Explorer's toolbar.
TranslateAcceleratorSB | Translates accelerator keystrokes intended for the browser's frame while the view is active.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::BrowseObject

Tells Windows Explorer to browse to another folder.

HRESULT BrowseObject(
    LPCITEMIDLIST pidl,
    UINT wFlags
   );

Parameters

pidl
Address of an ITEMIDLIST (item identifier list) structure that specifies an object's location. This value is dependent on the flag or flags set in the wFlags parameter.
wFlags
Flags specifying the folder to be browsed. It can be zero or one or more of the following values. These first three flags specify whether another window is to be created.
SBSP_SAMEBROWSER | Browse to another folder with the same Windows Explorer window.
SBSP_NEWBROWSER | Creates another window for the specified folder.
SBSP_DEFBROWSER | The default behavior is to respect the view option (the user setting to create new windows or to browse in place). In most cases, callers should use this flag.

The following flags specify either the open, explore, or default mode. These values are ignored if SBSP_SAMEBROWSER is specified or if SBSP_DEFBROWSER is specified and the user has selected Browse In Place.
SBSP_OPENMODE | Use a normal folder window.
SBSP_EXPLOREMODE | Use a Windows Explorer window.
SBSP_DEFMODE | Use the current window.

The following flags specify the pidl parameter's category:
SBSP_ABSOLUTE | An absolute pidl (relative from the desktop).
SBSP_RELATIVE | A relative pidl (relative from the current folder).
SBSP_PARENT | Browse the parent folder (ignores the pidl).
SBSP_NAVIGATEBACK | Navigate back (ignores the pidl).
SBSP_NAVIGATEFORWARD | Navigate forward(ignores the pidl).

The following two flags control how history is manipulated as a result of navigation:
SBSP_WRITENOHISTORY | Write no history (Shell folder) entry.
SBSP_NOAUTOSELECT | Suppress selection in the history pane.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Views can use this method to force Windows Explorer to browse to a specific place in the namespace. Typically, these are folders contained in the view.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::EnableModelessSB

Tells Windows Explorer to enable or disable its modeless dialog boxes.

HRESULT EnableModelessSB(
    BOOL fEnable
   );

Parameters

fEnable
Specifies whether the modeless dialog boxes are to be enabled or disabled. If this parameter is nonzero, modeless dialog boxes are enabled. If this parameter is zero, modeless dialog boxes are disabled.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is similar to the IOleInPlaceFrame::EnableModeless method. Although the current version of Windows Explorer does not have any modeless dialog boxes, the view should call this method when it wants to disable or enable modeless dialog boxes associated with the Windows Explorer window.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::GetControlWindow

Retrieves the window handle to a browser control.

HRESULT GetControlWindow(
    UINT id,
    HWND *lphwnd
   );

Parameters

id
Control handle that is being requested. This parameter can be one of the following values:
FCW_TOOLBAR | Retrieves the window handle to the browser's toolbar.
FCW_STATUS | Retrieves the window handle to the browser's status bar.
FCW_TREE | Retrieves the window handle to the browser's tree view.
FCW_PROGRESS | Retrieves the window handle to the browser's progress bar.
lphwnd
Address of the window handle to the Windows Explorer control.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

GetControlWindow is used so views can directly manipulate the browser's controls. FCW_TREE should be used only to determine if the tree is present.

Notes to Callers

GetControlWindow is used to manipulate and test the state of the control windows. Do not send messages directly to these controls; instead, use IShellBrowser::SendControlMsg. Be prepared for this method to return NULL. Future versions of Windows Explorer may not include a toolbar, status bar, or tree window.

Notes to Implementers

GetControlWindow returns the window handle to these controls if they exist in your implementation.

See also IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::GetViewStateStream

Retrieves an IStream interface that can be used for storage of view-specific state information.

HRESULT GetViewStateStream(
    DWORD grfMode,
    LPSTREAM *ppStrm
   );

Parameters

grfMode
Read/write access of the IStream interface. This may be one of the following values:
STGM_READ | Requests an IStream suitable for reading.
STGM_WRITE | Requests an IStream suitable for writing.
STGM_READWRITE | Requests an IStream suitable for reading and writing.
ppStrm
Address that receives the IStream interface pointer.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is used to save and restore the persistent state for a view (the icon positions, the column widths, and the current scroll position, for example).

Notes to Callers

Use GetViewStateStream when the view is being created to read in the saved view state and also when the view is being closed to save any changes to the view state. Typically, the view calls this method with STGM_READ when creating a view window and with STGM_WRITE when the SaveViewState method of its IShellView interface is called.

Notes to Implementers

Each Shell view should have its own view stream. Windows Explorer implements a most recently used (MRU) list of view streams that are stored on a per-user basis in the registry.

See also IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::InsertMenusSB

Allows the container to insert its menu groups into the composite menu that is displayed when an extended namespace is being viewed or used.

HRESULT InsertMenusSB(
    HMENU hmenuShared,
    LPOLEMENUGROUPWIDTHS lpMenuWidths
   );

Parameters

hmenuShared
Handle to an empty menu.
lpMenuWidths
Address of an OLEMENUGROUPWIDTHS array of six LONG values. The container fills in elements 0, 2, and 4 to reflect the number of menu elements it provided in the File, View, and Window menu groups.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is similar to the IOleInPlaceFrame::InsertMenus method. Windows Explorer puts File and Edit drop-down menus in the File menu group, View and Tools menus in the Container menu group, and a Help menu in the Window menu group. Each drop-down menu will have a unique identifier, FCIDM_MENU_FILE/EDIT/VIEW/TOOLS/HELP. The view is allowed to insert menu items into those submenus by their identifiers, which is different from OLE's in-place activation mechanism. The command identifiers for menus that the view inserts into either Windows Explorer's submenus or its own submenus must be between FCIDM_SHVIEWFIRST and FCIDM_SHVIEWLAST.

Notes to Callers

This method is called by namespace extensions when they are first being activated so they can insert their menus into the frame-level user interface.

The object application asks the container to add its menus to the menu specified in the hmenuShared parameter and to set the group counts in the OLEMENUGROUPWIDTHS array pointed to by the lpMenuWidths parameter. The object application then adds its own menus and counts. Objects can call the IOleInPlaceFrame::InsertMenus method as many times as necessary to build up the composite menus. The container should use the initial menu handle associated with the composite menu for all items in the drop-down menus.

Notes to Implementers

For IShellBrowser implementations, the menu identifiers must be in the range of FCIDM_BROWSERFIRST to FCIDM_BROWSERLAST.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::OnViewWindowActive

Called by the Shell view when the view window or one of its child windows gets the focus or becomes active.

HRESULT OnViewWindowActive(
    IShellView *ppshv
   );

Parameters

ppshv
Address of the view object's IShellView pointer.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The view must pass its IShellView implementation to this routine, although the current version of Windows Explorer does not use this parameter.

Notes to Callers

The Shell view object must call this method before calling the IShellBrowser::InsertMenusSB method. This method will insert a different set of menu items depending on whether the view has the focus.

Notes to Implementers

This method informs the browser that the view is getting the focus (when the mouse is clicked on the view, for example).

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::QueryActiveShellView

Returns the currently active (displayed) Shell view object.

HRESULT QueryActiveShellView(
    IShellView **ppshv
   );

Parameters

ppshv
Address of the pointer to the currently active Shell view object.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Notes to Callers

Because the IShellBrowser interface can host several Shell views simultaneously, this method provides an easy way to determine the active Shell view object.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::RemoveMenusSB

Permits the container to remove any of its menu elements from the in-place composite menu and to free all associated resources.

HRESULT RemoveMenusSB(
    HMENU hmenuShared
   );

Parameters

hmenuShared
Handle to the in-place composite menu that was constructed by calls to IShellBrowser::InsertMenusSB and the Microsoft® Win32® InsertMenu function.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is similar to the IOleInPlaceFrame::RemoveMenus method.

The object should always permit the container to remove its menu elements from the composite menu before deactivating the shared user interface.

Notes to Callers

The method is called by the object application while it is being UI-deactivated so the browser can remove its menus.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::SendControlMsg

Sends control messages to either the toolbar or the status bar in an Explorer window.

HRESULT SendControlMsg(
    UINT id,
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT *pret
   );

Parameters

id
Identifier for either a toolbar (FCW_TOOLBAR) or for a status bar window (FCW_STATUS).
uMsg
Message to be sent to the control.
wParam
Value depends on the message specified in the uMsg parameter.
lParam
Value depends on the message specified in the uMsg parameter.
pret
Address of the return value of the SendMessage function.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Refer to the Common Controls documentation for more information on the messages that can be sent to the toolbar or status bar control.

Notes to Callers

Use of this call requires diligent attention, because leaving either the status bar or toolbar in an inappropriate state will affect the performance of Windows Explorer.

Notes to Implementers

If your Windows Explorer does not have these controls, you can return E_NOTIMPL.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::SetMenuSB

Installs the composite menu in the view window.

RESULT SetMenuSB(
    HMENU hmenuShared,
    HOLEMENU holemenuReserved,
    HWND hwndActiveObject
    );

Parameters

hmenuShared
Handle to the composite menu constructed by calls to IShellBrowser::InsertMenusSB and the InsertMenu function.
holemenuReserved
Reserved for future use.
hwndActiveObject
The view's window handle.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is similar to the IOleInPlaceFrame::SetMenu method. However, Windows Explorer performs menu dispatch based on the menu item identifier.

The availability of specific menu items depends on whether the view has the focus. Accordingly, it is necessary to call the IShellBrowser::OnViewWindowActive method whenever the view window (or one of its child windows) has the focus.

Notes to Callers

The object calls IShellBrowser_SetMenuSB to ask the container to install the composite menu structure set up by calls to IShellBrowser::InsertMenusSB.

Notes to Implementers

A container's implementation of this method should call the Windows SetMenu function.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::SetStatusTextSB

Sets and displays status text about the in-place object in the container's frame-window status bar.

HRESULT SetStatusTextSB(
    LPCOLESTR lpszStatusText
   );

Parameters

lpszStatusText
Address of a null-terminated character string to contain the message to display.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

It is also possible to send messages directly to the status window by using the IShellBrowser::SendControlMsg method.

Notes to Callers

Use this method to set the contents of the status bar.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::SetToolbarItems

Adds toolbar items to Windows Explorer's toolbar.

HRESULT SetToolbarItems(
    LPTBBUTTON lpButtons,
    UINT nButtons,
    UINT uFlags
   );

Parameters

lpButtons
Address of an array of TBBUTTON structures.
nButtons
Number of TBBUTTON structures in the lpButtons array.
uFlags
Flags specifying where the toolbar buttons should go. This parameter can be one or more of the following values:
FCT_ADDTOEND | Add at the right side of the toolbar.
FCT_CONFIGABLE | Not implemented.
FCT_MERGE | Merge the toolbar items instead of replacing all of the buttons with those provided by the view. This is the recommended choice.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellBrowser::TranslateAcceleratorSB

Translates accelerator keystrokes intended for the browser's frame while the view is active.

HRESULT TranslateAcceleratorSB(
    LPMSG lpmsg,
    WORD wID
   );

Parameters

lpmsg
Address of an MSG structure containing the keystroke message.
wID
Command identifier value corresponding to the keystroke in the container-provided accelerator table. Containers should use this value instead of translating again.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is similar to the IOleInPlaceFrame::TranslateAccelerator method.

See Also

IShellBrowser

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellChangeNotify

The IShellChangeNotify is used to notify a Shell namespace extension when the ID of an item has changed.

When to Implement

This interface is implemented by all namespace extensions.

When to Use

You do not call this interface directly. IShellChangeNotify is used by the operating system only when it has confirmed that your application is aware of this interface.

IShellChangeNotify implements IUnknown and one additional method:
IShellChangeNotify Methods | Description
OnChange | Called when an item in the namespace extension changes.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlobj.h.


IShellChangeNotify::OnChange

Called to inform a namespace extension that an event has taken place that affects its items.

HRESULT OnChange(
    LONG lEvent,
    LPCITEMIDLIST pidl1,
    LPCITEMIDLIST pidl2,
);

Parameters

lEvent
Value that describes the event that has occurred. Typically, only one event is specified at a time. If more than one event is specified, the values contained in the pidl1 and pidl2 parameters must be the same, respectively, for all specified events. The lEvent parameter may contain one or more be one or more of the following flags:
SHCNE_ALLEVENTS | All events have occurred.
SHCNE_ASSOCCHANGED | A file type association has changed. pidl1 and pidl2 are not used and must be NULL.
SHCNE_ATTRIBUTES | The attributes of an item or folder have changed. pidl1 contains the item or folder that has changed. pidl2 is not used and should be NULL.
SHCNE_CREATE | A nonfolder item has been created. pidl1 contains the item that was created. pidl2 is not used and should be NULL.
SHCNE_DELETE | A nonfolder item has been deleted. pidl1 contains the item that was deleted. pidl2 is not used and should be NULL.
SHCNE_DRIVEADD | A drive has been added. pidl1 contains the root of the drive that was added. pidl2 is not used and should be NULL.
SHCNE_DRIVEADDGUI | A drive has been added and the Shell should create a new window for the drive. pidl1 contains the root of the drive that was added. pidl2 is not used and should be NULL.
SHCNE_DRIVEREMOVED | A drive has been removed. pidl1 contains the root of the drive that was removed. pidl2 is not used and should be NULL.
SHCNE_FREESPACE | The amount of free space on a drive has changed. pidl1 contains the root of the drive on which the free space changed. pidl2 is not used and should be NULL.
SHCNE_MEDIAINSERTED | Storage media has been inserted into a drive. pidl1 contains the root of the drive that contains the new media. pidl2 is not used and should be NULL.
SHCNE_MEDIAREMOVED | Storage media has been removed from a drive. pidl1 contains the root of the drive from which the media was removed. pidl2 is not used and should be NULL.
SHCNE_MKDIR | A folder has been created. pidl1 contains the folder that was created. pidl2 is not used and should be NULL.
SHCNE_NETSHARE | A folder on the local computer is being shared through the network. pidl1 contains the folder that is being shared. pidl2 is not used and should be NULL.
SHCNE_NETUNSHARE | A folder on the local computer is no longer being shared through the network. pidl1 contains the folder that is no longer being shared. pidl2 is not used and should be NULL.
SHCNE_RENAMEFOLDER | The name of a folder has changed. pidl1 contains the previous PIDL or name of the folder. pidl2 contains the new PIDL or name of the folder.
SHCNE_RENAMEITEM | The name of a nonfolder item has changed. pidl1 contains the previous PIDL or name of the item. pidl2 contains the new PIDL or name of the item.
SHCNE_RMDIR | A folder has been removed. pidl1 contains the folder that was removed. pidl2 is not used and should be NULL.
SHCNE_SERVERDISCONNECT | The computer has disconnected from a server. pidl1 contains the server from which the computer was disconnected. pidl2 is not used and should be NULL.
SHCNE_UPDATEDIR | The contents of an existing folder have changed, but the folder still exists and has not been renamed. pidl1 contains the folder that has changed. pidl2 is not used and should be NULL. If a folder has been created, deleted, or renamed, use SHCNE_MKDIR, SHCNE_RMDIR, or SHCNE_RENAMEFOLDER, respectively, instead.
SHCNE_UPDATEITEM | An existing nonfolder item has changed, but the item still exists and has not been renamed. pidl1 contains the item that has changed. pidl2 is not used and should be NULL. If a nonfolder item has been created, deleted, or renamed, use SHCNE_CREATE, SHCNE_DELETE, or SHCNE_RENAMEITEM, respectively, instead.

The following values specify combinations of other events:
SHCNE_DISKEVENTS | Specifies a combination of all of the disk event identifiers.
SHCNE_GLOBALEVENT | Specifies a combination of all of the global event identifiers.

The following value modifies other event values and cannot be used alone:
SHCNE_INTERRUPT The specified event occurred as a result of a system interrupt.

pidl1
First event-dependent item identifier.
pidl2
Second event-dependent item identifier.

Return Values

Return S_OK if successful, or standard OLE error values otherwise.

Remarks

This method is similar in function and usage to SHChangeNotify.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlobj.h.


IShellDetails

The IShellDetails interface is exposed by Shell folders to provide detailed information about the items in a folder. This is the same information that is displayed by the Windows Explorer when the view of the folder is set to Details. For Windows 2000 and later systems, IShellDetails is superseded by IShellFolder2.

When to Implement

For Windows 2000 and later systems, folder objects should implement IShellFolder2 instead of this interface. However, if your application needs to function on earlier systems, IShellDetails should also be exposed.

When to Use

This interface is exposed by some folder objects, including file system folders, on Windows 95, Windows NT 4.0, and later systems. However, you will need to include the version 5.0 shlobj.h header file. With Windows 2000 and later systems, use the IShellFolder2 methods to retrieve detailed information from Shell folders.

Methods

Method | Description
IShellDetails::ColumnClick | Rearranges the column.
IShellDetails::GetDetailsOf | Retrieves specified information for an item.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellDetails::ColumnClick

Rearranges a column.

HRESULT ColumnClick(
  UINT iColumn,
);

Parameters

IColumn
The index of the column to be rearranged.

Return Values

Returns S_FALSE to tell the calling application to sort the selected column. Otherwise, returns S_OK if successful, a COM error code otherwise.

Remarks

This method is called when a client of a folder object wants to sort the object's items based on the contents of one of the Details columns. Folder objects typically return S_FALSE.

Note to Users

This interface is exposed by some folder objects, including file system folders, on Windows 95, Windows NT 4.0, and later systems. However, you will need to include the version 5.0 shlobj.h header file.

Note to Implementers
For Windows 2000 and later systems, folder objects should implement IShellFolder2 instead of this interface. However, if your application needs to function on earlier systems, it should also expose IShellDetails.

See Also

IShellDetails::GetDetailsOf

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellDetails::GetDetailsOf

Retrieves detailed information on an item in a Shell folder.

HRESULT GetDetailsOf(
  LPCITEMIDLIST pidl,
  UINT iColumn,
  LPSHELLDETAILS pDetails
);

Parameters

pidl
[in] The PIDL of the item that you are requesting information on. If this parameter is set to NULL, the title of the information field specified by iColumn will be returned in the SHELLDETAILS structure pointed to by pDetails.
iColumn
[in] The zero-based index of the desired information field. It is identical to column number of the information as it is displayed in a Windows Explorer Details view.
pDetails
[out] A pointer to a SHELLDETAILS structure with the information.

Return Values

Returns S_OK if successful. Returns E_FAIL if iColumn exceeds the number of columns supported by the folder. Otherwise, returns a standard COM error code.

Remarks

This method has been superseded by the IShellFolder2 methods for Shell version 5.0 and later.

The GetDetailsOf method provides access to the information that is displayed in the Windows Explorer Details view of a Shell folder. The column numbers, column titles, and item information that you see in the Details view are identical to those returned by GetDetailsOf.

The available information fields and their column numbers vary depending on the particular folder. To enumerate the available fields call GetDetailsOf with pidl set to NULL for increasing values of iColumn. This approach provides you with the title associated with each column index. When iColumn exceeds the number of columns supported by the folder, GetDetailsOf will return E_FAIL. Bear in mind that these titles are localizable, and may not be the same for all locales.

File system folders have a large standard set of information fields. The first five fields are standard for all file system folders:

Column Index | Column Title
0 | Name
1 | Size
2 | Type
3 | Modified
4 | Attributes

File system folders may support a number of additional fields. However, they are not required to do so and the column indexes assigned to these fields may vary.

Each virtual folder has its own unique set of information fields. Normally, the item's display name is in column zero, but the order and content of the available fields depend on the implementation of the particular folder object.

Note to Users

This interface is exposed by some folder objects, including file system folders, on Windows 95, Windows NT 4.0, and later systems. However, you will need to include the version 5.0 shlobj.h header file. With Windows 2000 and later systems, use the IShellFolder2 methods to retrieve detailed information from Shell folders.

Note to Implementers
For Windows 2000 and later systems, folder objects should implement IShellFolder2 instead of this interface. However, if your application needs to function on earlier systems, IShellDetails should also be exposed.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellExecuteHook

The IShellExecuteHook interface extends the behavior of the ShellExecute or ShellExecuteEx function. It is typically implemented by subsystems that expose the names of objects that the user can specify in the Run dialog box after clicking the Windows Start button.

When to Implement

You should implement IShellExecuteHook when you have named objects that the user would expect to be able to run from the Run dialog box after clicking the Windows Start button.

When to Use

You do not use this interface directly. It is generally used by the ShellExecuteEx function's code.
IShellExecuteHook Method | Description
Execute | Called when ShellExecute or ShellExecuteEx is called for an object that is registered.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellExecuteHook::Execute

Called when ShellExecute or ShellExecuteEx is called for an object that is registered.

HRESULT Execute(
    LPSHELLEXECUTEINFO pei
);

Parameters

pei
Address of a SHELLEXECUTEINFO structure that contains information about the object being executed. On successful completion of the hook, the hInstApp member will be filled in by the hook.

Return Values

Returns one of the following values or an OLE-defined error value.
S_OK | The hook processed the execution. ShellExecute or ShellExecuteEx should not perform any other processing.
S_FALSE | The hook is installed but did not process the execution. ShellExecute or ShellExecuteEx should perform the default processing.

Remarks

This method provides an opportunity for the application to hook the execution of an object and change the default execution or perform some other action before the object is executed.

If the item should not be executed, Execute can simply return S_OK. To prevent the Shell from generating an error message box, set the hInstApp member of SHELLEXECUTE to 32 or greater.

See also

IShellExecuteHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellExtInit

The IShellExtInit interface is used to initialize Shell extensions for property sheets, shortcut menus, and drag-and-drop handlers (extensions that add items to shortcut menus during nondefault drag-and-drop operations).

When to Implement

Implement IShellExtInit when you are writing a handler based on the IContextMenu or IShellPropSheetExt interface.

Note that Shell extensions based on other interfaces do not use this method of initialization.

When to Use

You do not use this interface directly. The Shell calls it to initialize the handler.

Methods

Initialize Initializes a property sheet extension, shortcut menu extension, or drag-and-drop handler.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellExtInit::Initialize

Initializes a property sheet extension, shortcut menu extension, or drag-and-drop handler.

HRESULT Initialize(
    LPCITEMIDLIST pidlFolder,
    LPDATAOBJECT lpdobj,
    HKEY hkeyProgID
   );

Parameters

pidlFolder
Address of an ITEMIDLIST structure that uniquely identifies a folder. For property sheet extensions, this parameter is NULL. For shortcut menu extensions, it is the item identifier list for the folder that contains the item whose shortcut menu is being displayed. For nondefault drag-and-drop menu extensions, this parameter specifies the target folder.
lpdobj
Address of an IDataObject interface object that can be used to retrieve the objects being acted upon.
hkeyProgID
Registry key for the file object or folder type.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The meanings of some parameters depend on the extension type. For drag-and-drop handlers, the pidlFolder parameter specifies the destination folder (the drop target), the lpdobj parameter identifies the items being dropped, and the hkeyProgID parameter specifies the file class of the destination folder.

For shortcut menu extensions, lpdobj identifies the selected file objects, hkeyProgID identifies the file class of the object with focus, and pidlFolder is either NULL (for file objects) or specifies the folder for which the shortcut menu is being requested (for folder background shortcut menus).

For property sheet extensions, pidlFolder is NULL, lpdobj identifies the selected file objects, and hkeyProgID specifies the file class of the file object that has the focus.

Notes to Implementers

This is the first method that the Shell calls after it creates an instance of a property sheet extension, shortcut menu extension, or drag-and-drop handler.

See Also

IShellExtInit

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder

The IShellFolder interface is used to manage folders. It is exposed by all Shell namespace folder objects.

When to Implement

Implement this interface for objects that extend the Shell's namespace. For example, implement this interface to create a separate namespace that requires a rooted Windows Explorer or to install a new namespace directly within the hierarchy of the system namespace. You are most familiar with the contents of your namespace, so you are responsible for implementing everything needed to access your data.

When to Use

Use this interface when you need to display or perform an operation on the contents of the Shell's namespace. Objects that support IShellFolder are usually created by other Shell folder objects. To retrieve a folder's IShellFolder interface, you normally start by calling SHGetDesktopFolder. This function returns a pointer to the desktop's IShellFolder interface. You can then use its methods to retrieve an IShellFolder interface for a particular namespace folder. See Shell Basics for further discussion.

Note: IShellFolder methods only accept PIDLs that are relative to the folder. Some IShellFolder methods, such as IShellFolder::GetAttributesOf, only accept single-level PIDLs. In other words, the PIDL must contain only a single SHITEMID structure, plus the terminating NULL. When you enumerate the contents of a folder with IEnumIDList, you will receive PIDLs of this form. Other methods, such as IShellFolder::CompareIDs, accept multi-level PIDLs. These PIDLs can have multiple SHITEMID structures and identify objects one or more levels below the parent folder. Check the reference to be sure what type of PIDL can be accepted by a particular method.

IShellFolder Methods | Description
BindToObject | Retrieves the IShellFolder interface for the specified subfolder.
BindToStorage | Not currently implemented.
CompareIDs | Determines the relative order of two file objects or folders, given their item identifier lists.
CreateViewObject | Creates a view object of the folder itself.
EnumObjects | Enumerates the objects in a folder.
GetAttributesOf | Retrieves the attributes of the specified file object or subfolder.
GetDisplayNameOf | Retrieves the display name of a file object or subfolder.
GetUIObjectOf | Creates an OLE interface that can be used to carry out operations on a file object or subfolder.
ParseDisplayName | Translates a display name into an item identifier list.
SetNameOf | Sets the display name of the specified file object or subfolder and changes its identifier accordingly.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::BindToObject

Retrieves an IShellFolder object for a subfolder.

HRESULT BindToObject(
    LPCITEMIDLIST pidl,
    LPBC pbc,
    REFIID riid,
    VOID **ppv
   );

Parameters

pidl
[in] Address of an ITEMIDLIST structure (PIDL) that identifies the subfolder. pidl can refer to an object at any level below the parent folder in the namespace hierarchy. The pidl can thus be either a multi-level PIDL, relative to the parent folder. The structure will contain one or more SHITEMID structures, followed by a terminating NULL.
pbc
[in] Optional address of an IBindCtx interface on a bind context object to be used during this operation. If this parameter is not used, set it to NULL. Because support for pbc is optional for folder object implementations, some folders may not support the use of bind contexts.
riid
[in] Identifier of the interface to return.
ppvOut
[out] Address that receives the interface pointer. If an error occurs, a NULL pointer is returned in this address.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Applications use IShellFolder::BindToObject to obtain a directly exposed interface from the Shell folder object of a subitem. Usually the calling application passes IID_IShellFolder as the interface identifier to retrieve the IShellFolder interface. However, sometimes the calling application wants to obtain some other directly exposed interface, such as IRemoteComputer or IShellFolder2. A Shell namespace extension can implement this function by creating the Shell folder object for the specified subitem and then calling QueryInterface to convert it into the desired interface pointer, which is returned to the calling application.

It is also possible for the implementation to optimize this call if a particular interface is not implemented. For example, if the Shell folder object of the subitem does not support the IRemoteComputer interface, the implementation can return E_NOINTERFACE immediately instead of needlessly creating the Shell folder object for the subitem and then finding that IRemoteComputer was not supported after all. This optimization is useful if creating a Shell folder object is an expensive operation.

In other words, the following two code fragments are equivalent.

   /* This is the more efficient way */
   HRESULT hres = psf->BindToObject(pidl, pbc, riid, ppvOut);

   /* This is the equivalent slower way */
   IShellFolder *psfOut;
   HRESULT hres = psf->BindToObject(pidl, pbc, IID_IShellFolder, (LPVOID)&psfOut);
   if (SUCCEEDED(hres)) {
      hres = psfOut->QueryInterface(riid, ppvOut);
      psfOut->Release();
   } else {
      *ppvOut = NULL;
   }

See Also

SHGetDesktopFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::BindToStorage

Requests a pointer to an object's storage interface.

HRESULT BindToStorage(
    LPCITEMIDLIST pidl,
    LPBC pbc,
    REFIID riid,
    VOID **ppv
   );

Parameters

pidl
[in] Address of an ITEMIDLIST structure that identifies the subfolder relative to its parent folder. The structure must contain exactly one SHITEMID structure followed by a terminating zero.
pbc
[in] Optional address of an IBindCtx interface on a bind context object to be used during this operation. If this parameter is not used, set it to NULL. Because support for pbc is optional for folder object implementations, some folders may not support the use of bind contexts.
riid
[in] IID of the requested storage interface. To retrieve an IStream, IStorage, or IPropertySetStorage interface pointer, set riid to IID_IStream, IID_IStorage, or IID_IPropertySetStorage, respectively.
ppvOut
[out] Address that receives the interface pointer specified by riid. If an error occurs, a NULL pointer is returned in this address.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

Name space extensions have the option of allowing applications to bind to an object that represents an item's storage. If this option is supported, BindToStorage returns a specified interface pointer that can then be used to access the contents of object. See the IMoniker::BindToStorage reference for further discussion.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::CompareIDs

Determines the relative order of two file objects or folders, given their item identifier lists.

HRESULT CompareIDs(
    LPARAM lParam,
    LPCITEMIDLIST pidl1,
    LPCITEMIDLIST pidl2
   );

Parameters

lParam
[in] Value that specifies how the comparison should be performed.

The lower sixteen bits of lParam define the sorting rule. Most applications set the sorting rule to the default value of zero, indicating that the two items should be compared by name. The system does not define any other sorting rules. Some folder objects might allow calling applications to use the lower sixteen bits of lParam to specify folder-specific sorting rules. The rules and their associated lParam values are defined by the folder.

The upper sixteen bits of lParam are used for flags that modify the sorting rule. The system currently defines one modifier flag.

SCHIDS_ALLFIELDS Version 5.0. Compare all the information contained in the ITEMIDLIST structure, not just the display names. This flag is valid only for folder objects that support the IShellFolder2 interface. For instance, if the two items are files, the folder should compare their names, sizes, file times, attributes, and any other information in the structures. If this flag is set, the lower sixteen bits of lParam must be zero.
pidl1
[in] Address of the first item's ITEMIDLIST structure. It will be relative to the folder. This ITEMIDLIST structure can contain more than one element; therefore, the entire structure must be compared, not just the first element.
pidl2
[in] Address of the second item's ITEMIDLIST structure. It will be relative to the folder. This ITEMIDLIST structure can contain more than one element; therefore, the entire structure must be compared, not just the first element.

Return Values

If this method is successful, the CODE field of the HRESULT contains one of the following values. For information regarding the extraction of the CODE field from the returned HRESULT, see Remarks.

Less than zero | The first item should precede the second (pidl1 < pidl2).
Greater than zero | The first item should follow the second (pidl1 > pidl2).
Zero | The two items are the same (pidl1 = pidl2).

If this method is unsuccessful, it returns an OLE error code.

Remarks

Note to Callers

Do not set the SHCIDS_ALLFIELDS flag in lParam if the folder object does not support IShellFolder2. Doing so might have unpredictable results. If you use the SHCIDS_ALLFIELDS flag, the lower sixteen bits of lParam must be set to zero.

Use the HRESULT_CODE macro to extract the CODE field from the HRESULT, then cast the result to (short).

HRESULT hres = psf->CompareIDs(lParam, pidl1, pidl2);
if ((short)HRESULT_CODE(hres) < 0)
   { /* pidl1 comes first */ }
else if ((short)HRESULT_CODE(hres) > 0)
   { /* pidl2 comes first */ }
else
   { /* the two pidls are equal */ }
Note to Implementers

To extract the sorting rule, use a bitwise AND operator (&) to combine lParam with SHCIDS_COLUMNMASK (0X0000FFFF). This operation masks off the upper sixteen bits of lParam, including the SHCIDS_ALLFIELDS value.

Use the MAKE_HRESULT macro to construct the return value.

short sResult = ComputeResult();
return MAKE_HRESULT(SEVERITY_SUCCESS, 0, sResult);

Note that a short only contains 16 bits, so the ComputeResult() function must return a 16-bit value. Otherwise, the value will be truncated.

See Also

IShellFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::CreateViewObject

Requests an object that can be used to obtain information from or interact with a folder object.

HRESULT CreateViewObject(
    HWND hwndOwner,
    REFIID riid,
    VOID **ppv
   );

Parameters

hwndOwner
[in] Handle to the owner window. If you have implemented a custom folder view object, your folder view window should be created as a child of hwndOwner.
riid
[in] Identifier of the requested interface.
ppvOut
[out] Address of a pointer to the requested interface.

Return Values

Returns NOERROR if successful, or an OLE defined error value otherwise.

Remarks

To support this request, create an object that exposes the interface indicated by riid and return a pointer to that interface.

The primary purpose of this method is to provide Windows Explorer with the folder object's folder view object. Windows Explorer requests a folder view object by setting riid to IID_IShellView. The folder view object displays the contents of the folder in the Windows Explorer folder view. The folder view object must be independent of the Shell folder object, because Windows Explorer may call this method more than once to create multiple folder view objects. A new view object must be created each time this method is called. Your folder object can respond in one of two ways to this request. It can:

  • Create a custom folder view object and return a pointer to its IShellView interface.
  • Create a system folder view object and return a pointer to its IShellView interface.

This method is also used to request objects that expose one of several optional interfaces, including IContextMenu or IExtractIcon. In this context, CreateViewObject is similar in usage to IShellFolder::GetUIObjectOf. However, you call IShellFolder::GetUIObjectOf to request an object for one of the items contained by a folder. Call CreateViewObject to request an object for the folder itself. See Standard Shell Interfaces for a list of interfaces that may be requested.

See Also

IShellFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::EnumObjects

Allows a client to determine the contents of a folder by creating an item identifier enumeration object and returning its IEnumIDList interface. The methods supported by that interface can then be used to enumerate the folder's contents.

HRESULT EnumObjects(
    HWND hwnd,
    SHCONTF grfFlags,
    IENUMIDLIST **ppenumIDList
   );

Parameters

hwndOwner
[in] If user input is required to perform the enumeration, this window handle should be used by the enumeration object as the parent window to take user input. An example would be a dialog box to ask for a password or prompt the user to insert a CD or floppy disk. If hwndOwner is set to NULL, the enumerator should not post any messages, and if user input is required, it should silently fail.
grfFlags
[in] Flags indicating which items to include in the enumeration. For a list of possible values, see the SHCONTF enumerated type.
ppenumIDList
[out] Address that receives a pointer to the IEnumIDList interface of the enumeration object created by this method. If an error occurs, ppenumIDList is set to NULL.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The calling application must free the returned IEnumIDList object by calling its Release method.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.

See Also

IShellFolder, SHGetDesktopFolder


IShellFolder::GetAttributesOf

Retrieves the attributes of one or more file objects or subfolders.

HRESULT GetAttributesOf(
    UINT cidl,
    LPCITEMIDLIST *apidl,
    SFGAOF *rgfInOut
   );

Parameters

cidl
[in] Number of file objects from which to retrieve attributes.
apidl
[in] Address of an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object relative to the parent folder. Each ITEMIDLIST structure must contain exactly one SHITEMID structure followed by a terminating zero.
rgfInOut
[in/out] Address of a single ULONG value that, on entry, contains the attributes that the caller is requesting. On exit, this value contains the requested attributes that are common to all of the specified objects. Note that this is the address of a single ULONG value, not an array of ULONG values. The lists below describe the possible flags for this parameter.

A file object's capability flags may be zero or a combination of the following values:

Flag | Value | Description
SFGAO_CANCOPY | 0x00000001 | The specified file objects or folders can be copied (same value as the DROPEFFECT_COPY flag).
SFGAO_CANDELETE | 0x00000020 | The specified file objects or folders can be deleted.
SFGAO_CANLINK | 0x00000004 | Shortcuts can be created for the specified file objects or folders. This flag has the same value as DROPEFFECT_LINK. The normal use of this flag is to add a "Create Shortcut" item to the shortcut menu that is displayed during drag-and-drop operations. However, SFGAO_CANLINK also adds a "Create Shortcut" item to the Windows Explorer's File menu, and to normal shortcut menus. If this item is selected, your application's IContextMenu::InvokeCommand will be invoked with the lpVerb member of the CMINVOKECOMMANDINFO structure set to "link". Your application is responsible for creating the link.
SFGAO_CANMONIKER | 0x00400000 | It is possible to create monikers for the specified file objects or folders.
SFGAO_CANMOVE | 0x00000002 | The specified file objects or folders can be moved (same value as the DROPEFFECT_MOVE flag).
SFGAO_CANRENAME | 0x00000010 | The specified file objects or folders can be renamed. Note that this flag is essentially a suggestion. It does not guarantee that a namespace client will rename the file or folder object.
SFGAO_CAPABILITYMASK | 0x00000177 | This flag is a mask for the capability flags.
SFGAO_DROPTARGET | 0x00000100 | The specified file objects or folders are drop targets.
SFGAO_HASPROPSHEET | 0x00000040 | The specified file objects or folders have property sheets.

A file object's display attributes may be zero or a combination of the following values:

Flag | Value | Description
SFGAO_DISPLAYATTRMASK | 0x000F0000 | This flag is a mask for the display attributes.
SFGAO_GHOSTED | 0x00080000 | The specified file objects or folders should be displayed using a ghosted icon.
SFGAO_LINK | 0x00010000 | The specified file objects are shortcuts.
SFGAO_READONLY | 0x00040000 | The specified file objects or folders are read-only.
SFGAO_SHARE | 0x00020000 | The specified folders are shared.

A file object's contents flags may be zero or a combination of the following values:

Flag | Value | Description
SFGAO_CONTENTSMASK | 0x80000000 | This flag is a mask for the contents attributes.
SFGAO_HASSUBFOLDER | 0x80000000 | The specified folders may have subfolders, and are, therefore expandable in the left pane of Windows® Explorer.

Note: The SFGAO_HASSUBFOLDER attribute is only advisory, and may be returned by Shell folder implementations even if they do not contain subfolders. Returning SFGAO_HASSUBFOLDER is recommended whenever a significant amount of time is required to determine whether or not any subfolders exist. For example, the Shell always returns SFGAO_HASSUBFOLDER when a folder is located on a network drive.

A file object's miscellaneous attributes may be zero or a combination of the following values:

Flag | Value | Description
SFGAO_BROWSABLE | 0x08000000 | The specified items can be browsed in place.
SFGAO_COMPRESSED | 0x04000000 | The specified items are compressed.
SFGAO_FILESYSTEM | 0x40000000 | The specified folders or file objects are part of the file system (that is, they are files, directories, or root directories).
SFGAO_FILESYSANCESTOR | 0x10000000 | The specified folders contain one or more file system folders.
SFGAO_FOLDER | 0x20000000 | The specified items are folders.
SFGAO_NEWCONTENT | 0x00200000 | The objects contain new content.
SFGAO_NONENUMERATED | 0x00100000 | The items are nonenumerated items.
SFGAO_REMOVABLE | 0x02000000 | The specified file objects or folders are on removable media.
SFGAO_VALIDATE | 0x01000000 | Validate cached information. The Shell will validate that the objects specified in apidl still exist and will not use cached information when retrieving the attributes. If one or more of the items specified in apidl no longer exist, this method will return an error code. If cidl is zero, the Shell will discard all cached information for the Shell folder. This is similar to doing a refresh of the folder.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

You can optimize this operation by not returning unspecified flags.

See Also

IShellFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::GetDisplayNameOf

Retrieves the display name for the specified file object or subfolder.

HRESULT GetDisplayNameOf(
    LPCITEMIDLIST pidl,
    DWORD uFlags,
    LPSTRRET lpName
);

Parameters

pidl
[in] Address of an ITEMIDLIST structure (PIDL) that uniquely identifies the file object or subfolder relative to the parent folder.
uFlags
[in] Flags used to request the type of display name to return. For a list of possible values, see the SHGNO enumerated type.
lpName
[out] Address of a STRRET structure in which to return the display name. The type of name returned in this structure can be the requested type, but the Shell folder might return a different type.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Normally, pidl can refer only to items contained by the parent folder. The PIDL must be single-level and contain exactly one SHITEMID structure followed by a terminating zero. If you want to retrieve the display name of an item that is deeper than one level away from the parent folder, use SHBindToParent to bind with the item's immediate parent folder and then pass the item's single-level PIDL to IShellFolder::GetDisplayNameOf.

Also, if the SHGDN_FORPARSING flag is set in uFlags and the SHGDN_INFOLDER flag is not set, pidl can refer to an object at any level below the parent folder in the namespace hierarchy. In this case, pidl can be a multilevel PIDL, relative to the parent folder, and can contain multiple SHITEMID structures.

The simplest way to retrieve the display name from the structure pointed to by lpName is to pass it to either StrRetToBuf or StrRetToStr. These functions take a STRRET structure and return the name. You can also examine the structure's uType member, and retrieve the name from the appropriate member.

The flags specified in uFlags are hints about the intended use of the name. They do not guarantee that IShellFolder will return the requested form of the name. If that form is not available, a different one might be returned. In particular, there is no guarantee that the name returned by the SHGDN_FORPARSING flag will be successfully parsed by ParseDisplayName. There are also some combinations of flags that might cause the GetDisplayName/ParseDisplayName round trip to not return the original identifier list. This occurrence is exceptional, but you should check to be sure.

Note The parsing name that is returned when uFlags has the SHGDN_FORPARSING flag set is not necessarily a normal text string. Virtual folders such as My Computer might return a string containing the folder object's GUID in the form "::{GUID}". Developers who implement IShellFolder::GetDisplayNameOf are encouraged to return parse names that are as close to the display names as possible, because the end user often needs to type or edit these names.

See Also

IShellFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::GetUIObjectOf

Retrieves an OLE interface that can be used to carry out actions on the specified file objects or folders.

HRESULT GetUIObjectOf(
    HWND hwndOwner,
    UINT cidl,
    LPCITEMIDLIST *apidl,
    REFIID riid,
    UINT *rgfReserved,
    VOID **ppv
   );

Parameters

hwndOwner
[in] Handle to the owner window that the client should specify if it displays a dialog box or message box.
cidl
[in] Number of file objects or subfolders specified in the apidl parameter.
apidl
[in] Address of an array of pointers to ITEMIDLIST structures, each of which uniquely identifies a file object or subfolder relative to the parent folder. Each item identifier list must contain exactly one SHITEMID structure followed by a terminating zero.
riid
[in] Identifier of the COM interface object to return. This can be any valid interface identifier that can be created for an item. The most common identifiers used by the Shell are listed in the comments at the end of this reference.
prgfInOut
Reserved.
ppvOut
[out] Pointer to the requested interface. If an error occurs, a NULL pointer is returned in this address.

Return Values

Returns NOERROR if successful, E_NOINTERFACE if the interface is not supported, or an OLE-defined error value otherwise.

Remarks

If cidl is greater than one, the GetUIObjectOf implementation should only succeed if it can create one object for all items specified in apidl. If the implementation cannot create one object for all items, this method should fail.

The following are the most common interface identifiers the Shell uses when requesting an interface from this method. The list also indicates if cidl can be greater than one for the requested interface.

Interface Identifier | Allowed cidl Value
IContextMenu | The cidl parameter can be greater than or equal to one.
IContextMenu2 | The cidl parameter can be greater than or equal to one.
IDataObject | The cidl parameter can be greater than or equal to one.
IDropTarget | The cidl parameter can only be one.
IExtractIcon | The cidl parameter can only be one.
IQueryInfo | The cidl parameter can only be one.

See Also

IShellFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::ParseDisplayName

Translates a file object's or folder's display name into an item identifier list.

HRESULT ParseDisplayName(
    HWND hwnd,
    LPBC pbc,
    LPOLESTR pszDisplayName,
    ULONG *pchEaten,
    LPITEMIDLIST *ppidl,
    ULONG *pdwAttributes
   );

Parameters

hwndOwner
[in] Optional window handle. The client should provide a window handle if it displays a dialog or message box. Otherwise set hwndOwner to NULL.
pbc
[in] Optional bind context that controls the parsing operation. This parameter is normally set to NULL.
lpwszDisplayName
[in] Null-terminated UNICODE string with the display name. Because each Shell folder defines its own parsing syntax, the form this string can take may vary. The desktop folder, for instance, accepts paths such as "c:\My Docs\My File.txt". It also will accept references to items in the namespace that have a globally unique identifier (GUID) associated with them using the "::{GUID}" syntax. For example, to retrieve a fully qualified identifier list for the control panel from the desktop folder, you can use:
"{CLSID for My Computer}\::{CLSID for the Control Panel}"
pchEaten
[out] Pointer to a ULONG value that receives the number of characters of the display name that was parsed. If your application does not need this information, set pchEaten to NULL, and no value will be returned.
ppidl
[out] Pointer to an ITEMIDLIST pointer that receives the item identifier list for the object. The returned item identifier list specifies the item relative to the parsing folder. If the object associated with lpwszDisplayName is within the parsing folder, the returned item identifier list will contain only one SHITEMID structure. If the object is in a subfolder of the parsing folder, the returned item identifier list will contain multiple SHITEMID structures. If an error occurs, NULL is returned in this address.
pdwAttributes
[in/out] Optional parameter that can be used to query for file attributes. If not used, it should be set to NULL. To query for one or more attributes, initialize the pdwAttributes with the flags that represent the attributes of interest. On return, those attributes that are true and were requested will be set. A file object's attribute flags may be zero or a combination of the following values:

Value | Description
SFGAO_CANCOPY | The specified file objects or folders can be copied (same value as the DROPEFFECT_COPY flag).
SFGAO_CANDELETE | The specified file objects or folders can be deleted.
SFGAO_CANLINK | Shortcuts can be created for the specified file objects or folders. This flag has the same value as DROPEFFECT_LINK. Typically, this flag is used to add a "Create Shortcut" item to the shortcut menu that is displayed during drag-and-drop operations. However, SFGAO_CANLINK also adds a "Create Shortcut" item to the Windows Explorer's File menu, and to normal shortcut menus. If this item is selected, your application's IContextMenu::InvokeCommand will be invoked with the lpVerb member of the CMINVOKECOMMANDINFO structure set to "link". Your application is responsible for creating the link.
SFGAO_CANMONIKER | It is possible to create monikers for the specified file objects or folders.
SFGAO_CANMOVE | The specified file objects or folders can be moved (same value as the DROPEFFECT_MOVE flag).
SFGAO_CANRENAME | The specified file objects or folders can be renamed. Note that this flag is essentially a suggestion. It does not guarantee that a namespace client will rename the file or folder object.
SFGAO_CAPABILITYMASK | This flag is a mask for the capability flags.
SFGAO_DROPTARGET | The specified file objects or folders are drop targets.
SFGAO_HASPROPSHEET | The specified file objects or folders have property sheets.

A file object's display attributes may be zero or a combination of the following values:

Value | Description
SFGAO_DISPLAYATTRMASK | This flag is a mask for the display attributes.
SFGAO_GHOSTED | The specified file objects or folders should be displayed using a ghosted icon.
SFGAO_LINK | The specified file objects are shortcuts.
SFGAO_READONLY | The specified file objects or folders are read-only.
SFGAO_SHARE | The specified folders are shared.

A file object's contents flags may be zero or a combination of the following values:

Value | Description
SFGAO_CONTENTSMASK | This flag is a mask for the contents attributes.
SFGAO_HASSUBFOLDER | The specified folders have subfolders (and are, therefore, expandable in the left pane of Windows® Explorer).

A file object's miscellaneous attributes may be zero or a combination of the following values:

Value | Description
SFGAO_BROWSABLE | The specified items can be browsed in place.
SFGAO_COMPRESSED | The specified items are compressed.
SFGAO_FILESYSTEM | The specified folders or file objects are part of the file system (that is, they are files, directories, or root directories).
SFGAO_FILESYSANCESTOR | The specified folders contain one or more file system folders.
SFGAO_FOLDER | The specified items are folders.
SFGAO_NEWCONTENT | The objects contain new content.
SFGAO_NONENUMERATED | The items are nonenumerated items.
SFGAO_REMOVABLE | The specified file objects or folders are on removable media.
SFGAO_VALIDATE | This flag is used to confirm the existence of the folder or object that corresponds to lpwszDisplayName. Not every folder implements this flag, but if it is passed in to ParseDisplayName, and the folder or object does not exist, a failure code should be returned.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Some Shell folders may not implement ParseDisplayName. Each folder that does will define its own parsing syntax.

Querying for some attributes may be relatively slow and use significant amounts of memory. For example, to determine if a file is shared, the Shell will load network components. This procedure may require the loading of several DLLs. The purpose of dwAttributes is to allow you to restrict the query to only that information that is needed. The following code fragment illustrates how to find out if a file is compressed:

IShellFolder *psf;
DWORD dwAttribs = SFGAO_COMPRESSED;
...
hres = psf->ParseDisplayName(NULL,
                NULL,
                lpwszDisplayName,
                &cbEaten,
                &pidl,
                &dwAttribs);
if(dwAttribs & SFGAO_COMPRESSED)
{
//do something with the compressed file
}

Since pdwAttributes is an in/out parameter, it should always be initialized. If you pass in an uninitialized value, some of the bits may be set. ParseDisplayName will then query for the corresponding attributes, which may lead to undesirable delays or memory demands. If you do not wish to query for attributes, set pdwAttributes to NULL to avoid unpredictable behavior.

This method is similar to the OLE IParseDisplayName::ParseDisplayName method.

See Also

IShellFolder, IShellLink, IShellFolder::GetAttributesOf

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder::SetNameOf

Sets the display name of a file object or subfolder, changing the item identifier in the process.

HRESULT SetNameOf(
    HWND hwndOwner,
    LPCITEMIDLIST pidl,
    LPCOLESTR lpszName,
    DWORD uFlags,
    LPITEMIDLIST *ppidlOut
   );

Parameters

hwndOwner
[in] Handle to the owner window of any dialog or message boxes that the client displays.
pidl
[in] Pointer to an ITEMIDLIST structure that uniquely identifies the file object or subfolder relative to the parent folder. The structure must contain exactly one SHITEMID structure followed by a terminating zero.
lpszName
[in] Pointer to a null-terminated string that specifies the new display name.
uFlags
[in] Flags indicating the type of name specified by the lpszName parameter. For a list of possible values, see the description of the SHGNO enumerated type.
ppidlOut
[out] Address of a pointer to an ITEMIDLIST structure which receives the new ITEMIDLIST. Implementations of SetNameOf usually return a pointer to the new ITEMIDLIST in the ppidlOut parameter, but callers of this interface must be capable of handling the case where *ppidlOut is not set. If you call SetNameOf with ppidlOut set to NULL, it will not return a new ITEMIDLIST for the object. If an error occurs, the implementation must set *ppidlOut to NULL (if ppidlOut is non-NULL).

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Changing the display name of a file system object, or a folder within it, renames the file or directory.

Before calling this method, applications should call IShellFolder::GetAttributesOf and check that the SFGAO_CANRENAME flag is set. Note that this flag is essentially a hint to name space clients. It does not necessarily imply that IShellFolder::SetNameOf will succeed or fail.

See also

IShellFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellFolder2

The IShellFolder2 interface extends the capabilities of IShellFolder. Its methods provide a variety of information about the contents of a Shell folder.

When to Implement

Implement IShellFolder2 if your namespace extension provides services to clients beyond those in IShellFolder.

When to Use

Call IShellFolder2 when you need detailed information on items contained by a Shell folder. This interface supersedes IShellDetails.

IShellFolder2 implements all the IShellFolder methods as well as IUnknown. The following methods are specific to IShellFolder2.

Methods | Description
EnumSearches | Requests a pointer to an interface that allows a client to enumerate the available search objects.
GetDefaultColumn | Retrieves the default sorting and display columns.
GetDefaultColumnState | Retrieves the default state for a specified column.
GetDefaultSearchGUID | Requests the GUID of the default search object for the folder.
GetDetailsEx | Retrieves detailed information, identified by a property set ID (FMTID) and property ID (PID), on an item in a Shell folder.
GetDetailsOf | Retrieves detailed information, identified by a column index, on an item in a Shell folder.
MapNameToSCID | Converts a column name to the appropriate property set ID (FMTID) and property ID (PID).

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::EnumSearches

Requests a pointer to an interface that allows a client to enumerate the available search objects.

HRESULT EnumSearches(
    IEnumExtraSearch **ppEnum
);

Parameters

ppEnum
Address of a pointer to an enumerator object's IEnumExtraSearch interface.

Return Values

Returns NOERROR if successful, or an OLE error value otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::GetDefaultColumn

Retrieves the default sorting and display columns.

HRESULT GetDefaultColumn(
    DWORD dwReserved,
    ULONG *pSort,
    ULONG *pDisplay
);

Parameters

dwReserved
[in] Reserved. Set to zero.
pSort
[out] Pointer to a value that receives the index of the default sorted column.
pDisplay
[out] Pointer to a value that receives the index of the default display column.

Return Values

Returns NOERROR if successful, or a COM error value otherwise.

Remarks

Notes to Users

Both column indexes returned by this method are intended for use by an application that is presenting a folder view of this folder.

The column specified by pSort is the one that should be used for sorting the items in the folder. To determine the sorting order of any pair of items, pass their PIDLs to IShellFolder::CompareIDs. Specify the column by setting the lParam parameter of IShellFolder::CompareIDs to the value pointed to by pSort.

If a view will display only one string to represent an item, it should be taken from the column specified by pDisplay. Pass the column index and the item's PIDL to IShellFolder2::GetDetailsOf to retrieve the string.

Notes to Implementers

This method is part of a namespace extension's folder object implementation. It is typically called by a folder view object to ask the folder object which column in Microsoft® Windows® Explorer Details view should be used to sort the items in the folder. For example, a folder object that represents a transaction log might set pSort to the column that displays the transaction time. The items will then be sorted by the time the transaction took place, rather than by name.

Some clients might call this method to request the index of the column with the names that should be displayed in tree view. Set pDisplay to the appropriate column index. The client will then obtain the display names by calling IShellFolder2::GetDetailsOf.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::GetDefaultColumnState

Retrieves the default state for a specified column.

HRESULT GetDefaultColumnState(
    UINT iColumn
    SHCOLSTATEF *pcsFlags
);

Parameters

iColumn
[in] Integer that specifies the column number.
pcsFlags
[out] Pointer to a value that contains flags that indicate the default column state. This parameter can include a combination of the following flags.
SHCOLSTATE_TYPE_STR | A string.
SHCOLSTATE_TYPE_INT | An integer.
SHCOLSTATE_TYPE_DATE | A date.
SHCOLSTATE_ONBYDEFAULT | Should be shown by default in the Microsoft® Windows® Explorer Details view.
SHCOLSTATE_SLOW | Extracting information about the column can be time consuming. This flag recommends that the folder view extract column information asynchronously, on a background thread.
SHCOLSTATE_EXTENDED | Provided by a handler, not the folder object.
SHCOLSTATE_SECONDARYUI | Not displayed in the shortcut menu, but listed in the More dialog box.
SHCOLSTATE_HIDDEN | Not displayed in the user interface.

Return Values

Returns NOERROR if successful, or an OLE error value otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::GetDefaultSearchGUID

Returns the globally unique identifier (GUID) of the default search object for the folder.

HRESULT GetDefaultSearchGUID(
    GUID *pguid
);

Parameters

lpGUID
[out] GUID of the default search object.

Return Values

Returns NOERROR if successful, or an OLE error value otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::GetDetailsEx

Retrieves detailed information, identified by a property set ID (FMTID) and property ID (PID), on an item in a Shell folder.

HRESULT GetDetailsEx(
    LPCITEMIDLIST pidl,
    SHCOLUMNID *pscid,
    VARIANT *pv
);

Parameters

pidl
[in] PIDL of the item, relative to the parent folder. This method accepts only single-level PIDLs. The structure must contain exactly one SHITEMID structure followed by a terminating zero.
pscid
[in] Pointer to an SHCOLUMNID structure that identifies the column.
pv
[out] Pointer to a VARIANT with the requested information. The value will be fully typed.

Return Values

Returns NOERROR if successful, or a COM error value otherwise.

Remarks

This function is a more robust version of IShellFolder2::GetDetailsOf. It provides access to the information that is displayed in the Microsoft® Windows® Explorer Details view of a Shell folder. The primary difference is that GetDetailsEx allows you to identify the column with an FMTID and PID structure instead of having to first determine the column index.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::GetDetailsOf

Retrieves detailed information, identified by a column index, on an item in a Shell folder.

HRESULT GetDetailsOf(
  LPCITEMIDLIST pidl,
  UINT iColumn,
  SHELLDETAILS *psd
);

Parameters

pidl
[in] PIDL of the item for which you are requesting information. This method accepts only single-level PIDLs. The structure must contain exactly one SHITEMID structure followed by a terminating zero. If this parameter is set to NULL, the title of the information field specified by iColumn is returned.
iColumn
[in] Zero-based index of the desired information field. It is identical to the column number of the information as it is displayed in a Microsoft® Windows® Explorer Details view.
pDetails
[out] Pointer to a SHELLDETAILS structure that contains the information.

Return Values

Returns S_OK if successful, or a standard COM error value otherwise.

Remarks

The GetDetailsOf method is identical to IShellDetails::GetDetailsOf. For a more robust way to retrieve item information that doesn't require you to know the column index, use GetDetailsEx.

The GetDetailsOf method provides access to the information that is displayed in the Windows Explorer Details view of a Shell folder. The column numbers, headings, and information that you see in the Windows Explorer Details view are identical to those of GetDetailsOf. Note that the available information fields and their column numbers vary depending on the particular folder. You can enumerate the available fields by calling this method with pidl set to NULL, and examining the title associated with each column index. Bear in mind that these titles can be localized and might not be the same for all locales.

File system folders have a large, standard set of information fields. The first five fields are standard for all file system folders.

Column index | Column title
0 | Name
1 | Size
2 | Type
3 | Modified
4 | Attributes

File system folders can support a number of additional fields. However, they are not required to do so, and the column indexes assigned to these fields might vary.

Each virtual folder has its own unique set of information fields. Normally, the item's display name is in column zero, but the order and content of the remaining fields depend on the implementation of the particular folder object.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellFolder2::MapNameToSCID

IShellFolder2::MapColumnToSCID

Converts a column to the appropriate property set ID (FMTID) and property ID (PID).

HRESULT MapColumnToSCID(
    UINT iColumn,
    SHCOLUMNID *pscid
);

Parameters

columnID
[in] Column ID
pscid
[out] Pointer to an SHCOLUMNID structure containing the FMTID and PID.

Return Values

Returns NOERROR if successful, or a COM error value otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIcon

The IShellIcon interface is used to obtain an icon index for an IShellFolder object. IShellIcon allows an application to obtain the icon for any object within a folder by using only one instance of the interface. IExtractIcon, on the other hand, requires that a separate instance of the interface be created for each object.

When to Implement

Implement IShellIcon when creating an IShellFolder implementation to provide a quick way to obtain the icon for an object in the folder.

If IShellIcon is not implemented by an IShellFolder object, IShellFolder::GetUIObjectOf is used to retrieve an icon for all objects.

When to Use

Use IShellIcon when retrieving the icon index for an item in a Shell folder.
IShellIcon Method | Description
GetIconOf | Retrieves an icon for an object in a folder.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellIcon::GetIconOf

Retrieves an icon for an object inside a specific folder.

HRESULT GetIconOf(
    LPCITEMIDLIST pidl,
    UINT flags,
    LPINT lpIconIndex
   );

Parameters

pidl
Address of the ITEMIDLIST structure that specifies the relative location of the folder.
flags
Flags specifying how the icon is to display. This parameter can be zero or one of the following values:
GIL_FORSHELL | The icon is to be displayed in a Shell folder.
GIL_OPENICON | The icon should be in the open state if both open- and closed-state images are available. If this flag is not specified, the icon should be in the normal or closed state. This flag is typically used for folder objects.
lpIconIndex
Address of the index of the icon in the system image list. The following standard image list indexes can be returned:
0 | Document (blank page, not associated)
1 | Document (with data on the page)
2 | Application (file extension must be .exe, .com, or .bat)
3 | Folder (plain)
4 | Folder (open)

Return Values

Returns NOERROR if lpIconIndex contains the correct system image list index, or S_FALSE if an icon can't be obtained for this object.

Remarks

If you are unable to retrieve an icon for this object using GetIconOf, use the IShellFolder::GetUIObjectOf method to retrieve an object that supports the IExtractIcon::Extract method.

Notes to Callers

The index returned is from the system image list.

Notes to Implementers

If the icon index used is not one of the standard images listed, it is the implementer's responsibility to add the image to the system image list and then place the index into the lpIconIndex parameter. To prevent the system image list from growing too large, each image should only be added once.

See Also

IShellIcon

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellIconOverlay

Icon overlays are small images placed at the lower-left corner of the icon that represents a Shell object. They are normally used to add some extra information to the icon. A commonly used icon overlay is the small arrow that indicates that a file or folder icon represents a link. A namespace extension can specify icon overlays for the objects it contains by implementing an IShellIconOverlay interface.

Icon overlays are part of the system image list. They have two identifiers. One is a one-based overlay index that identifies the overlay relative to other overlays in the image list. The other is an image index that identifies the actual image. These two indexes are equivalent to the values that you assign to the iOverlay and iImage parameters, respectively, when you add an icon overlay to a private image list with ImageList_SetOverlayImage.

Before displaying the icon for an object, the Shell calls the associated folder's IShellIconOverlay interface to query whether the object's icon should have an overlay. Normally it calls IShellIconOverlay::GetOverlayIndex to request the overlay's overlay index. In some cases, the Shell might call IShellIconOverlay::GetOverlayIconIndex to request the overlay's image index. To specify an icon overlay, the methods must return the requested index. Otherwise, they return S_FALSE.

To specify an icon overlay, both methods must first retrieve the overlay's overlay index in the system image list by calling SHGetIconOverlayIndex. When SHGetIconOverlayIndex is called for the first time, the Shell uses the overlay's file name and index within the file to add the image to the system image list. Once an overlay is in the system image list, the Shell simply uses the file name and index as an identifier. You can also use SHGetIconOverlayIndex to retrieve the overlay index of several standard system overlays. IShellIconOverlay::GetOverlayIndex simply returns the overlay index to the Shell. IShellIconOverlay::GetOverlayIconIndex must call INDEXTOOVERLAYMASK to convert the overlay index to the equivalent image index.

Note The number of different icon overlay handlers that the system can support is limited by the amount of space available for icon overlays in the system image list. There are currently fifteen slots allotted for icon overlays, some of which are reserved by the system. For this reason, icon overlays should be specified only if there are no satisfactory alternatives.

When to Implement

This interface is implemented by namespace extensions that need to specify icon overlays for their objects.

When to Use

This interface is not normally used by applications.

Methods

IShellIconOverlay implements the following methods in addition to IUnknown.

GetOverlayIndex | Returns the overlay index in the system image list.
GetOverlayIconIndex | Returns the index of the icon overlay in the system image list.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIconOverlay::GetOverlayIconIndex

Returns the index of the icon overlay in the system image list.

HRESULT GetOverlayIconIndex(
    LPCITEMIDLIST pidlItem,
    int *pIconIndex
);

Parameters

pidlItem
[in] Address of an ITEMIDLIST structure that identifies the object whose icon is being displayed.
pIconIndex
[out] Address of the zero-based index of the icon overlay's image in the system image list. This index is equivalent to the iImage value that is specified when you add an overlay image to a private image list with the ImageList_SetOverlayImage function.

Return Values

Returns NOERROR if successful, or an OLE error code otherwise.

Remarks

To retrieve the overlay's image index in the system image list, you must first call SHGetIconOverlayIndex to retrieve the overlay index. Then call INDEXTOOVERLAYMASK to convert the overlay index into the equivalent image index.

See Also

IShellIconOverlay

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIconOverlay::GetOverlayIndex

Returns the overlay index in the system image list.

HRESULT GetOverlayIndex(
    LPCITEMIDLIST pidlItem,
    int *pIndex
);

Parameters

pidlItem
[in] Address of an ITEMIDLIST structure that identifies the object whose icon is being displayed.
pIndex
[out] Address of the overlay's one-based overlay index in the system image list. This index is equivalent to the iOverlay value that is specified when you add an overlay image to a private image list with the ImageList_SetOverlayImage function.

Return Values

Returns NOERROR if successful, or an OLE error code otherwise.

Remarks

To retrieve the overlay index in the system image list, call SHGetIconOverlayIndex.

See Also

IShellIconOverlay

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIconOverlayIdentifier

Icon overlays are small images placed at the lower-left corner of the icon that represents a Shell object in Microsoft® Windows® Explorer or on the desktop. They are used to add some extra information to the object's normal icon. A commonly used icon overlay is the small arrow that indicates that a file or folder is actually a link. You can specify custom icon overlays for Shell objects by implementing and registering an icon overlay handler.

Icon overlay handlers are COM objects that are associated with a particular icon overlay. All communication between the Shell and the handler takes place through the handler's IShellIconOverlayIdentifier interface. For a general discussion of icon overlay handlers, see Creating Icon Overlay Handlers.

When to Implement

This interface must be implemented by all icon overlay handlers.

When to Use

This interface is not normally called by applications.

Methods

IShellIconOverlayIdentifier implements the following methods in addition to IUnknown.

GetOverlayInfo | Provides the location of the icon overlay's bitmap.
GetPriority | Specifies the priority of an icon overlay.
IsMemberOf | Specifies whether an icon overlay should be added to a Shell object's icon.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIconOverlayIdentifier::GetOverlayInfo

Provides the location of the icon overlay's bitmap.

HRESULT GetOverlayInfo(
    LPWSTR pwszIconFile,
    int cchMax,
    int *pIndex,
    DWORD *pdwFlags
);

Parameters

pwszIconFile
[out] NULL-terminated Unicode string that contains the fully qualified path of the file containing the icon. The .dll, .exe, and .ico file types are all acceptable. You must set the ISIOI_ICONFILE flag in pdwFlags if you return a file name.
cchMax
[in] Size of the pwszIconFile buffer.
pIndex
[out] Address of the index of the icon in a file containing multiple icons. You must set the ISIOI_ICONINDEX flag in pdwFlags if you return an index.
pdwFlags
Address of a flag that specifies what information is being returned. This parameter can be one or both of the following values.
ISIOI_ICONFILE | The path of the icon file is returned through pwszIconFile.
ISIOI_ICONINDEX | There is more than one icon in pwszIconFile. The icon's index is returned through pIndex.

Remarks

This method is called by the Shell at startup so that the handler's icon overlay can be added to the system image list. After initialization is complete, the Shell calls GetOverlayInfo when it needs to display the handler's icon overlay.

Note Once the image has been loaded into the system image list during initialization, it cannot be changed. After initialization, the file name and index are used only to identify the icon overlay. The system will not load a new icon overlay. When GetOverlayInfo is called, your handler must return the same file name and index that were specified when the function was first called.

See Also

IShellIconOverlayIdentifier

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIconOverlayIdentifier::GetPriority

Specifies the priority of an icon overlay.

HRESULT GetPriority(
    int *pPriority
);

Parameters

pPriority
[out] Address of a value that indicates the priority of the overlay identifier. Possible values range from zero to 100, with zero the highest priority.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

If more than one icon overlay is available for an object, the one with highest priority is chosen. The Shell has a set of internal rules that determine priority for many cases. The value returned by GetPriority is used for those cases where the Shell's internal rules do not apply. Normally, you should set the value to zero. However, the priority value is useful when you have implemented two or more icon overlay handlers that can request icon overlay icons for the same object. By setting the priority values appropriately, you can specify which of the requested icon overlays will be displayed.

See Also

IShellIconOverlayIdentifier

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellIconOverlayIdentifier::IsMemberOf

Specifies whether an icon overlay should be added to a Shell object's icon.

HRESULT IsMemberOf(
    LPCWSTR pwszPath,
    DWORD dwAttrib
);

Parameters

pwszPath
Unicode string that contains the fully qualified path of the Shell object.
dwAttrib
Object's attributes. For a complete list of file attributes and their associated flags, see IShellFolder::GetAttributesOf.

Return Values

This method returns one of the following:

S_OK | The icon overlay should be displayed.
S_FALSE | The icon overlay should not be displayed.
E_FAIL | The operation failed.

Remarks

The Shell calls this method to determine whether it should display a handler's icon overlay for a particular object. Icon overlay handlers are normally intended to work with a particular group of files. A typical example is a file class, identified by a specific file name extension. An icon overlay handler might request an icon overlay for all members of the file class. Some handlers request an icon overlay only if a member of the file class is in a particular state. However, icon overlay handlers are free to request their icon overlay for any object that they want.

See Also

IShellIconOverlayIdentifier

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellImageAdviseSink Interface

This is preliminary documentation and is subject to change.

This interface is implemented by classes that need notification of changes in images that are decoded by the IShellImageData interface.

IShellImageAdviseSink Members

StatusChange Notifies objects that have implemented the IShellImageData interface of a change in the associated image.

Remarks

An instance of this interface is passed to IShellImageData::Advise to activate the notification process.

Interface Information

Stock Implementation | shimgvw.dll version 5.5 or later
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shimgdata.h, shimgdata.idl
Minimum operating systems | Whistler

See Also

IShellImageData


IShellImageAdviseSink::StatusChange Method

This is preliminary documentation and is subject to change.

Notifies objects that have implemented the IShellImageData interface of a change in the associated image.

Syntax

HRESULT StatusChange(
    IShellImageData *pImage,
    IMAGESTATUS status,
    HRESULT hrResult
);

Parameters

pImage
[in] Pointer to the IShellImageData interface of the object whose image has changed.
status
[in] An IMAGESTATUS_FLAGS flag describing the type of change.
hrResult
[in] The HRESULT of the operation that caused the image to change.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageData Interface

This is preliminary documentation and is subject to change.

This interface specifies methods that enable image transformation, manipulation, and rendering.

IShellImageData Members

Advise | Sets up a callback in the calling application's code that executes when an image is finished decoding.
Decode | Starts the process of decoding an image from its native format to a pixel format.
DiscardEdit | Discards any editing done to the current image.
DisplayName | Returns the display name of the current image.
Draw | Draws a specified portion of the current image in the specified rectangle of the destination device context.
GetCurrentPage | Decodes the current page.
GetDelay | Returns the animation delay between the current frame and the next frame.
GetPageCount | Returns the total number of pages in a multiple page image.
GetPixelFormat | Returns a globally unique identifier (GUID) that specifies image pixel format.
GetProperties | Returns the set of properties associated with the current image.
GetRawDataFormat | Returns a GUID that specifies the raw data format.
GetResolution | Returns the resolution of the current image.
GetSize | Returns the dimensions of the current page (for multiple page images) or the current frame (in animated images).
IsAnimated | Specifies whether the current image is an animated format.
IsEditable | Specifies whether the current image is editable.
IsFirstPage | Specifies whether the current page of a multiple page image is the first page.
IsLastPage | Specifies whether the current page of a multiple page image is the last page.
IsMultipage | Specifies whether the current image is a multiple page format.
IsPrintable | Specifies whether the current image is printable.
IsTransparent | Specifies whether the current image has a transparent color.
IsVector | Specifies whether the current image is a vector format.
NextFrame | Decodes the next frame in an animated image format.
NextPage | Decodes the next page for image formats that support multiple pages.
PrevPage | Decodes the previous page for image formats that support multiple pages.
Print | Prints the current image.
Rotate | Rotates the image in increments of 90 degrees.
Scale | Scales the image to specified dimensions using a particular interpolation method.
SelectPage | Selects the current page in a multiple page image.
SetEncoderParams | Sets the parameters associated with a given image encoding scheme.
Unadvise | Cancels status messages.
WasEdited | Specifies whether the current image has been edited.

Remarks

This interface is accessible via an object exposed by the CImageDataFactory class.

Interface Information

Stock Implementation | shimgvw.dll version 5.5 or later
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shimgdata.h, shimgdata.idl
Minimum operating systems | Whistler


IShellImageData::Advise Method

This is preliminary documentation and is subject to change.

Sets up a callback in the calling application's code that executes when an image is finished decoding.

Syntax

HRESULT Advise(
    IShellImageAdviseSink *pAdvSink,
    DWORD *pdwConnection
);

Parameters

pAdvSink
[in] Pointer to an IShellImageAdviseSink interface reference.
pdwConnection
[in] Pointer to a DWORD connection identifier (ID).

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageData::Decode Method

This is preliminary documentation and is subject to change.

Starts the process of decoding an image from its native format to a pixel format.

Syntax

HRESULT Decode(
    DWORD dwFlags,
    ULONG cxDesired,
    ULONG cyDesired
);

Parameters

dwFlags
[in] DWORD flag specifying the type of decoding to perform. There are two possible values:
SHIMGDEC_DEFAULT
Decode to the image's native size.
SHIMGDEC_THUMBNAIL
Decode thumbnail version of image.
cxDesired
[in] ULONG specifying the horizontal image offset at which to begin decoding. This is usually zero.
cyDesired
[in] ULONG specifying the vertical image offset at which to begin decoding. This is usually zero.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageData::DiscardEdit Method

This is preliminary documentation and is subject to change.

Discards any editing done to the current image.

Syntax

HRESULT DiscardEdit(VOID);

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageData::DisplayName Method

This is preliminary documentation and is subject to change.

Returns the display name of the current image.

Syntax

HRESULT DisplayName(
    LPWSTR wszName
);

Parameters

wszName
[in, out] Pointer to a string buffer. If the buffer is empty initially, the display name is returned from the current image data. If the buffer contains text initially, the text is assumed to be a path and the file name is stripped and returned in the same buffer.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageData::Draw Method

This is preliminary documentation and is subject to change.

Draws a specified portion of the current image in the specified rectangle of the destination device context.

Syntax

HRESULT Draw(
    HDC hdc,
    LPRECT prcDest,
    LPRECT prcSrc
);

Parameters

hdc
[in] The destination device context, that is, where the image should be drawn.
prcDest
[in] Pointer to the destination rectangle.
prcSrc
[in] Pointer to the source rectangle.

Return Value

Returns S_OK if successful, or an error value otherwise.


IShellImageData::GetCurrentPage Method

This is preliminary documentation and is subject to change.

Decodes the current page.

Syntax

HRESULT GetCurrentPage(
    LONG *pnPage
);

Parameters

pnPage
[out] Pointer to a LONG that returns the page number decoded.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::SelectPage


IShellImageData::GetDelay Method

This is preliminary documentation and is subject to change.

Returns the animation delay between the current frame and the next frame.

Syntax

HRESULT GetDelay(
    DWORD *pdwDelay
);

Parameters

pdwDelay
[out] Pointer to a DWORD that returns the delay in milliseconds.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The animation delay is only meaningful for animated image formats.

In many animation formats, the delay between frames is variable. For example, the delay between the first and second frame may be different than the delay between second and third frames.

See Also

IShellImageData::GetProperties, IShellImageData::GetSize


IShellImageData::GetPageCount Method

This is preliminary documentation and is subject to change.

Returns the total number of pages in a multiple page image.

Syntax

HRESULT GetPageCount(
    LONG *pcPages
);

Parameters

pcPages
[out] Pointer to a LONG that returns the total number of pages. If the image format does not support multiple pages, this routine always returns one.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::GetProperties, IShellImageData::GetSize


IShellImageData::GetPixelFormat Method

This is preliminary documentation and is subject to change.

Returns a globally unique identifier (GUID) that specifies image pixel format.

Syntax

HRESULT GetPixelFormat(
    DWORD *pFormat
);

Parameters

pFormat
[out] Pointer to a DWORD that returns the pixel format identifier (ID). Possible values are defined in GDIPlusPixelFormats.h.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::GetProperties, IShellImageData::GetSize


IShellImageData::GetProperties Method

This is preliminary documentation and is subject to change.

Returns the set of properties associated with the current image.

Syntax

HRESULT GetProperties(
    DWORD dwMode,
    IPropertySetStorage **ppPropSet
);

Parameters

dwMode
[in] DWORD flag indicating the mode (currently ignored).
ppPropSet
[out] Pointer to an IPropertySetStorage Online link interface reference.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::GetResolution, IShellImageData::GetSize


IShellImageData::GetRawDataFormat Method

This is preliminary documentation and is subject to change.

Returns a globally unique identifier (GUID) that specifies the raw data format.

Syntax

HRESULT GetRawDataFormat(
    GUID *pDataFormat
);

Parameters

pDataFormat
[out] Pointer to a GUID that returns the raw data format identifier (ID). Possible values are defined in GDIPlusImaging.h and include:
ImageFormatUndefined
ImageFormatMemoryBMP
ImageFormatBMP
ImageFormatEMF
ImageFormatWMF
ImageFormatJPEG
ImageFormatPNG
ImageFormatGIF
ImageFormatTIFF
ImageFormatEXIF
ImageFormatPhotoCD
ImageFormatFlashPIX
ImageFormatIcon

Return Value

Returns S_OK if successful, or an error value otherwise.


IShellImageData::GetResolution Method

This is preliminary documentation and is subject to change.

Returns the resolution of the current image.

Syntax

HRESULT GetResolution(
    ULONG *puResolutionX,
    ULONG *puResolutionY
);

Parameters

puResolutionX
[out] Pointer to a ULONG that returns horizontal resolution.
puResolutionY
[out] Pointer to a ULONG that returns vertical resolution.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::GetSize


IShellImageData::GetSize Method

This is preliminary documentation and is subject to change.

Returns the dimensions of the current page (for multiple page images) or the current frame (in animated images).

Syntax

HRESULT GetSize(
    SIZE *pSize
);

Parameters

pSize
[out] Pointer to a SIZE structure which returns the dimensions of the current page or the current frame.

Return Value

Returns S_OK if successful, or an error value otherwise.


IShellImageData::IsAnimated Method

This is preliminary documentation and is subject to change.

Specifies whether the current image is an animated format.

Syntax

HRESULT IsAnimated(VOID);

Return Value

Returns S_OK if the current image is animated, S_FALSE if not.


IShellImageData::IsEditable Method

This is preliminary documentation and is subject to change.

Specifies whether the current image is editable.

Syntax

HRESULT IsEditable(VOID);

Return Value

Returns S_OK if the current image is editable, S_FALSE if not.

See Also

IShellImageData::IsPrintable, IShellImageData::IsFirstPage, IShellImageData::IsLastPage, IShellImageData::IsMultipage, IShellImageData::IsTransparent, IShellImageData::IsVector


IShellImageData::IsFirstPage Method

This is preliminary documentation and is subject to change.

Specifies whether the current page of a multiple page image is the first page.

Syntax

HRESULT IsFirstPage(VOID);

Return Value

Returns S_OK if the current page is the last page, S_FALSE if not.

Remarks

If the image format only supports a single page, this method always returns S_OK.


IShellImageData::IsLastPage Method

This is preliminary documentation and is subject to change.

Specifies whether the current page of a multiple page image is the last page.

Syntax

HRESULT IsLastPage(VOID);

Return Value

Returns S_OK if the current image is editable, S_FALSE if not.

Remarks

If the image format only supports a single page, this method always returns S_OK.


IShellImageData::IsMultipage Method

This is preliminary documentation and is subject to change.

Specifies whether the current image is a multiple page format.

Syntax

HRESULT IsMultipage(VOID);

Return Value

Returns S_OK if the current image is in a multiple page format, S_FALSE if not.


IShellImageData::IsPrintable Method

This is preliminary documentation and is subject to change.

Specifies whether the current image is printable.

Syntax

HRESULT IsPrintable(VOID);

Return Value

Returns S_OK if the current page is printable, S_FALSE if not.


IShellImageData::IsTransparent Method

This is preliminary documentation and is subject to change.

Specifies whether the current image has a transparent color.

Syntax

HRESULT IsTransparent(VOID);

Return Value

Returns S_OK if the current image has a transparent color, S_FALSE if not.


IShellImageData::IsVector Method

This is preliminary documentation and is subject to change.

Specifies whether the current image is a vector format.

Syntax

HRESULT IsVector(VOID);

Return Value

Returns S_OK if the current image is in a vector format, S_FALSE if not.


IShellImageData::NextFrame Method

This is preliminary documentation and is subject to change.

Decodes the next frame in an animated image format.

Syntax

HRESULT NextFrame(VOID);

Return Value

Returns S_OK if the next frame is available, E_PENDING if the next frame is still decoding, or E_NOMOREDATA if there is no next frame. If this method is called on an image format that does not support animation, the method returns E_NOMOREDATA.

See Also

IShellImageData::NextPage, IShellImageData::PrevPage


IShellImageData::NextPage Method

This is preliminary documentation and is subject to change.

Decodes the next page for image formats that support multiple pages.

Syntax

HRESULT NextPage(VOID);

Return Value

Returns S_OK if the next page is available, E_PENDING if the next page is still decoding, or E_NOMOREDATA if there is no next page. If this method is called on an image format that does not support multiple pages, the method returns E_NOMOREDATA.

See Also

IShellImageData::PrevPage, IShellImageData::NextFrame


IShellImageData::PrevPage Method

This is preliminary documentation and is subject to change.

Decodes the previous page for image formats that support multiple pages.

Syntax

HRESULT PrevPage(VOID);

Return Value

Returns S_OK if the previous page is available, E_PENDING if the previous page is still decoding, or E_NOMOREDATA if there is no previous page. If this method is called on an image format that does not support multiple pages, the method returns E_NOMOREDATA.

See Also

IShellImageData::NextPage, IShellImageData::NextFrame


IShellImageData::Print Method

This is preliminary documentation and is subject to change.

Prints the current image.

Syntax

HRESULT Print(
    BOOL fShowUI,
    LPWSTR szPrinterName
);

Parameters

fShowUI
[in] BOOL indication of whether to show the printing user interface.
TRUE
Shows the standard print job dialog.
FALSE
Does not show the standard print job dialog.
szPrinterName
[in] Pointer to a string that contains the name of the target printer. Pass NULL to print to the default printer.

Return Value

Returns S_OK if successful, or an error value otherwise.


IShellImageData::Rotate Method

This is preliminary documentation and is subject to change.

Rotates the image in increments of 90 degrees.

Syntax

HRESULT Rotate(
    DWORD dwAngle
);

Parameters

dwAngle
[in] DWORD angle of rotation in 90 degree increments.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::Scale


IShellImageData::Scale Method

This is preliminary documentation and is subject to change.

Scales the image to specified dimensions using a particular interpolation method.

Syntax

HRESULT Scale(
    ULONG cx,
    ULONG cx,
    InterpolationMode hints
);

Parameters

cx
[in] ULONG width of the scaled image.
cx
[in] ULONG height of the scaled image.
hints
[in] The interpolation mode. Interpolation modes are defined in GDIPlusEnums.h.

Return Value

Returns S_OK if successful, or an error value otherwise.


IShellImageData::SelectPage Method

This is preliminary documentation and is subject to change.

Selects the current page in a multiple page image.

Syntax

HRESULT SelectPage(
    LONG iPage
);

Parameters

iPage
[in] LONG that specifies a particular page in a multiple page image.

Return Value

Returns S_OK if successful, or an error value otherwise.


IShellImageData::SetEncoderParams Method

This is preliminary documentation and is subject to change.

Sets the parameters associated with a given image encoding scheme.

Syntax

HRESULT SetEncoderParams(
    IPropertyBag *pbagEnc
);

Parameters

pbagEnc
[in] Pointer to an IPropertyBag interface.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The parameters are dependent upon the current encoder. For example, the JPEG encoder supports compression level, whereas the BMP encoder does not.


IShellImageData::Unadvise Method

This is preliminary documentation and is subject to change.

Cancels status messages.

Syntax

HRESULT Unadvise(
    DWORD pdwConnection
);

Parameters

pdwConnection
[in] DWORD connection identifier (ID).

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData::Advise


IShellImageData::WasEdited Method

This is preliminary documentation and is subject to change.

Specifies whether the current image has been edited.

Syntax

HRESULT WasEdited(VOID);

Return Value

Returns S_OK if the current image has been edited, S_FALSE if not.

Remarks

The IShellImageData::Rotate and IShellImageData::Scale methods cause the current image to be flagged as edited.


IShellImageDataFactory Interface

This is preliminary documentation and is subject to change.

Provides utility methods for initializing, loading, and saving images using an instance of an IShellImageData interface.

IShellImageDataFactory Members

CreateImageFromFile | Loads an image file into a new instance of an object that implements the IShellImageData interface.
CreateImageFromStream | Loads a specified image input stream into a new instance of an object that implements the IShellImageData interface.
CreateIShellImageData | Creates a new instance of an object that implements the IShellImageData interface.
GetDataFormatFromPath | Looks up a specified file extension in the registry, gets the content type, and returns the globally unique identifier (GUID) identifying the data format.

Remarks

This interface is implemented in the Component Object Model (COM) class CImageDataFactory.

Interface Information

Stock Implementation | shimgvw.dll version 5.5 or later
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shimgdata.h, shimgdata.idl
Minimum operating systems | Whistler n


IShellImageDataFactory::CreateImageFromFile Method

This is preliminary documentation and is subject to change.

Loads an image file into a new instance of an object that implements the IShellImageData interface.

Syntax

HRESULT CreateImageFromFile(
    LPCWSTR pszPath,
    IShellImageData **ppshimg
);

Parameters

pszPath
[in] Pointer to a string containing the fully specified path to the image file.
ppshimg
[out] Address of a pointer to a variable that receives an IShellImageData interface pointer.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

This method determines which encoder to use based on the file extension.

See Also

IShellImageData


IShellImageDataFactory::CreateImageFromStream Method

This is preliminary documentation and is subject to change.

Loads a specified image input stream into a new instance of an object that implements the IShellImageData interface.

Syntax

HRESULT CreateImageFromStream(
    IStream *pStream,
    IShellImageData **ppshimg
);

Parameters

pStream
[in] Pointer to an input stream.
ppshimg
[out] Address of a pointer to a variable that receives an IShellImageData interface pointer.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageDataFactory::CreateIShellImageData Method

This is preliminary documentation and is subject to change.

Creates a new instance of an object that implements the IShellImageData interface.

Syntax

HRESULT CreateIShellImageData(
    IShellImageData **ppshimg
);

Parameters

ppshimg
[out] Address of a pointer to a variable that receives an IShellImageData interface pointer.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellImageDataFactory::GetDataFormatFromPath Method

This is preliminary documentation and is subject to change.

Looks up a specified file extension in the registry, gets the content type, and returns the globally unique identifier (GUID) identifying the data format.

Syntax

HRESULT GetDataFormatFromPath(
    LPCWSTR pszPath,
    GUID *pDataFormat
);

Parameters

pszPath
[in] Pointer to a string containing the fully specified path to the image file.
pDataFormat
[out] Pointer to a GUID. Possible values are defined in GDIPlusImaging.h and include:
ImageFormatUndefined
Undefined format.
ImageFormatMemoryBMP
Memory-based bitmap format.
ImageFormatBMP
Standard Microsoft® Windows® BMP format.
ImageFormatEMF
Extended Metafile format.
ImageFormatWMF
Standard Windows Metafile format.
ImageFormatJPEG
JPEG format.
ImageFormatPNG
Portable Network Graphics format.
ImageFormatGIF
Graphics Interchange File format.
ImageFormatTIFF
Tagged Interchange File format.
ImageFormatEXIF
EXIF format.
ImageFormatPhotoCD
PhotoCD format.
ImageFormatFlashPIX
FlashPIX format.
ImageFormatIcon
Standard Windows Icon format.

Return Value

Returns S_OK if successful, or an error value otherwise.

See Also

IShellImageData


IShellLink

The IShellLink interface allows Shell links to be created, modified, and resolved.

Methods

IShellLink supports the following methods:

GetArguments | Retrieves the command-line arguments associated with a Shell link object.
GetDescription | Retrieves the description string for a Shell link object.
GetHotkey | Retrieves the hot key for a Shell link object.
GetIconLocation | Retrieves the location (path and index) of the icon for a Shell link object.
GetIDList | Retrieves the list of item identifiers for a Shell link object.
GetPath | Retrieves the path and file name of a Shell link object.
GetShowCmd | Retrieves the show (SW_) command for a Shell link object.
GetWorkingDirectory | Retrieves the name of the working directory for a Shell link object.
Resolve | Resolves a Shell link by searching for the Shell link object and updating the Shell link path and its list of identifiers (if necessary).
SetArguments | Sets the command-line arguments associated with a Shell link object.
SetDescription | Sets the description string for a Shell link object.
SetHotkey | Sets the hot key for a Shell link object.
SetIconLocation | Sets the location (path and index) of the icon for a Shell link object.
SetIDList | Sets the list of item identifiers for a Shell link object.
SetPath | Sets the path and file name of a Shell link object.
SetRelativePath | Sets the relative path for a Shell link object.
SetShowCmd | Sets the show (SW_) command for a Shell link object.
SetWorkingDirectory | Sets the name of the working directory for a Shell link object.

Remarks

Note: The IShellLink interface has an ANSI version (IShellLinkA) and a Unicode version (IShellLinkW). The version that will be used depends on whether you compile for ANSI or Unicode. However, Microsoft® Windows 95 and Microsoft® Windows 98 only support IShellLinkA.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetArguments

Retrieves the command-line arguments associated with a Shell link object.

HRESULT STDMETHODCALLTYPE GetArguments(
    LPSTR pszArgs,
    int cchMaxPath
   );

Parameters

pszArgs
Pointer to the buffer that receives the command-line arguments.
cchMaxPath
Variable of type int that specifies the maximum number of characters that can be copied to the buffer supplied by the pszArgs parameter.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

For Microsoft® Windows® 2000 or later, the string returned to pszArgs has a maximum length of INFOTIPSIZE. For systems prior to Windows 2000, the size of the string is limited by MAX_PATH.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetDescription

Retrieves the description string for a Shell link object.

HRESULT STDMETHODCALLTYPE GetDescription(
    LPSTR pszName,
    int cchMaxName
   );

Parameters

pszName
Pointer to the buffer that receives the description string.
cchMaxName
Variable of type int that specifies the maximum number of characters to copy to the buffer pointed to by the pszName parameter.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

For Microsoft® Windows® 2000 or later, the string returned to pszName has a maximum length of INFOTIPSIZE. For systems prior to Windows 2000, the size of the string is limited by MAX_PATH.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetHotkey

Retrieves the hot key for a Shell link object.

HRESULT STDMETHODCALLTYPE GetHotkey(
    WORD *pwHotkey
   );

Parameters

pwHotkey
Address of the hot key. The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values:
HOTKEYF_ALT | ALT key
HOTKEYF_CONTROL | CTRL key
HOTKEYF_EXT | Extended key
HOTKEYF_SHIFT | SHIFT key

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetIconLocation

Retrieves the location (path and index) of the icon for a Shell link object.

HRESULT STDMETHODCALLTYPE GetIconLocation(
    LPSTR pszIconPath,
    int cchIconPath,
    int *piIcon
   );

Parameters

pszIconPath
Address of a buffer that receives the path of the file containing the icon.
cchIconPath
Maximum number of characters to copy to the buffer pointed to by the pszIconPath parameter.
piIcon
Address of a value that receives the index of the icon.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetIDList

Retrieves the list of item identifiers for a Shell link object.

HRESULT STDMETHODCALLTYPE GetIDList(
    LPITEMIDLIST *ppidl
   );

Parameters

ppidl
Address of a pointer to a list of item identifiers.

Return Values

Returns NOERROR if the operation is successful and one or more valid PIDLs is retrieved. If the operation is successful, but no PIDLs are retrieved, it returns S_FALSE with ppidl set to NULL. Otherwise, it returns an OLE-defined error value.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetPath

Retrieves the path and file name of a Shell link object.

HRESULT STDMETHODCALLTYPE GetPath(
    LPSTR pszFile,
    int cchMaxPath,
    WIN32_FIND_DATA *pfd,
    DWORD fFlags
   );

Parameters

pszFile
Address of a buffer that receives the path and file name of the Shell link object.
cchMaxPath
Maximum number of bytes to copy to the buffer pointed to by the pszFile parameter.
pfd
Address of a WIN32_FIND_DATA structure that contains information about the Shell link object.
fFlags
Flags that specify the type of path information to retrieve. This parameter can be a combination of the following values:
Flag | Description
SLGP_SHORTPATH | Retrieves the standard short (8.3 format) file name.
SLGP_UNCPRIORITY | Retrieves the Universal Naming Convention (UNC) path name of the file.
SLGP_RAWPATH | Retrieves the raw path name. A raw path is something that might not exist and may include environment variables that need to be expanded.

Return Values

Returns NOERROR if the operation is successful and a valid path is retrieved. If the operation is successful, but no path is retrieved, it returns S_FALSE and pszPath will be empty. Otherwise, it returns an OLE-defined error value.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetShowCmd

Retrieves the show command for a Shell link object.

HRESULT STDMETHODCALLTYPE GetShowCmd(
    int *piShowCmd
);

Parameters

piShowCmd
Pointer to the command. The following commands are supported:
Value | Description
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
SW_SHOWMAXIMIZED | Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED | Activates the window and displays it as a minimized window.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The show command is used to set the initial show state of the corresponding object. This is one of the SW_xxx values described in ShowWindow.

See also

IShellLink, IShellLink::SetShowCmd

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::GetWorkingDirectory

Retrieves the name of the working directory for a Shell link object.

HRESULT STDMETHODCALLTYPE GetWorkingDirectory(
    LPSTR pszDir,
    int cchMaxPath
   );

Parameters

pszDir
Address of a buffer that receives the name of the working directory.
cchMaxPath
Maximum number of characters to copy to the buffer pointed to by the pszDir parameter. The name of the working directory is truncated if it is longer than the maximum specified by this parameter.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::Resolve

Attempts to find the target of a Shell link, even if it has been moved or renamed.

HRESULT Resolve(
    HWND hwnd,
    DWORD fFlags
);

Parameters

hwnd
Handle to the window that the Shell will use as the parent for a dialog box. The Shell displays the dialog box if it needs to prompt the user for more information while resolving a Shell link.
fFlags
Action flags. This parameter can be a combination of the following values:
SLR_INVOKE_MSI
Call the Microsoft Windows Installer.
SLR_NOLINKINFO
Disable distributed link tracking. By default, distributed link tracking tracks removable media across multiple devices based on the volume name. It also uses the UNC path to track remote file systems whose drive letter has changed. Setting SLR_NOLINKINFO disables both types of tracking.
SLR_NO_UI
Do not display a dialog box if the link cannot be resolved. When SLR_NO_UI is set, the high-order word of fFlags can be set to a time-out value that specifies the maximum amount of time to be spent resolving the link. The function returns if the link cannot be resolved within the time-out duration. If the high-order word is set to zero, the time-out duration will be set to the default value of 3,000 milliseconds (3 seconds). To specify a value, set the high word of fFlags to the desired time-out duration, in milliseconds.
SLR_NOUPDATE
Do not update the link information.
SLR_NOSEARCH
Do not execute the search heuristics.
SLR_NOTRACK
Do not use distributed link tracking.
SLR_UPDATE
If the link object has changed, update its path and list of identifiers. If SLR_UPDATE is set, you do not need to call IPersistFile::IsDirty to determine whether or not the link object has changed.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Following link creation, the name or location of the target may change. The IShellLink::Resolve method first retrieves the path associated with the link. If the object is no longer there or has been renamed, Resolve will attempt to find it. If successful, and the following conditions are met:

  • The SLR_UPDATE flag is set.
  • The target has been moved or renamed, updating the internal state of the Shell link object to refer to the new target.
  • The Shell link object was loaded from a file through IPersistFile.

the file that the link object was loaded from will be updated to reflect the new state of the link object. The client can also call IPersistFile::IsDirty method to determine whether the link object has changed and the file needs to be updated.

Resolve has two approaches to finding target objects. The first is the distributed link tracking service. If the service is available, it can find an object that was on an NTFS version 5.0 volume and was moved to another location on that volume. It can also find an object that was moved to another NTFS version 5.0 volume, including volumes on other computers. To suppress the use of this service, set the SLR_NOTRACK flag.

If distributed link tracking is not available or fails to find the link object, Resolve attempts to find it with search heuristics. It first looks in the object's last known directory for an object with a different name but the same attributes and file creation time. Next, it recursively searches subdirectories in the vicinity of the object's last known directory. It looks for an object with the same name or creation time. Finally, Resolve looks for a matching object on the desktop and other local volumes. To suppress the use of the search heuristics, set the SLR_NOSEARCH flag.

If both approaches fail, the system will display a dialog box prompting the user for a location. To suppress the dialog box, set the SLR_NO_UI flag.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetArguments

Sets the command-line arguments for a Shell link object.

HRESULT STDMETHODCALLTYPE SetArguments(
    LPCSTR pszArgs
   );

Parameters

pszArgs
Pointer to a variable of type LPCSTR that specifies the buffer that contains the new command-line arguments.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

This method is useful when creating a link to an application that takes special flags as arguments, such as a compiler.

Remarks

For Microsoft® Windows® 2000 or later, the string specified by pszArgs must be no larger than INFOTIPSIZE. For systems prior to Windows 2000, the size of the string is limited by MAX_PATH.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetDescription

Sets the description for a Shell link object. The description can be any application-defined string.

HRESULT STDMETHODCALLTYPE SetDescription(
    LPCSTR pszName
   );

Parameters

pszName
Pointer to a variable of type LPCSTR that specifies the buffer containing the new description string.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

For Microsoft® Windows® 2000 or later, the string specified by pszName must be no larger than INFOTIPSIZE. For systems prior to Windows 2000, the size of the string is limited by MAX_PATH.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetHotkey

Sets a hot key for a Shell link object.

HRESULT STDMETHODCALLTYPE SetHotkey(
    WORD wHotkey
   );

Parameters

wHotkey
New hot key. The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the values specified in the description of the IShellLink::GetHotkey method.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Setting a hot key allows the user to activate the object by pressing a particular combination of keys.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetIconLocation

Sets the location (path and index) of the icon for a Shell link object.

HRESULT STDMETHODCALLTYPE SetIconLocation(
    LPCSTR pszIconPath,
    int iIcon
   );

Parameters

pszIconPath
Address of a buffer to contain the path of the file containing the icon.
iIcon
Index of the icon.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetIDList

Sets the PIDL for a Shell link object.

HRESULT STDMETHODCALLTYPE SetIDList(
    LPCITEMIDLIST pidl
   );

Parameters

pidl
The object's fully-qualified PIDL.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This method is useful when an application needs to set a Shell link to an object that is not a file, such as a Control Panel application, a printer, or another computer.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetPath

Sets the path and file name of a Shell link object.

HRESULT STDMETHODCALLTYPE SetPath(
    LPCSTR pszFile
   );

Parameters

pszFile
Address of a buffer that contains the new path.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetRelativePath

Sets the relative path to the Shell link object.

HRESULT SetRelativePath(
    LPCSTR pszPathRel,
    DWORD dwReserved
   );

Parameters

pszPathRel
Address of a buffer that contains the new relative path. It should be a file name, not a folder name.
dwReserved
Reserved. Set this parameter to zero.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Example

Consider the following scenario:

  • You have a link: c:\MyLink.lnk
  • The link target is c:\MyDocs\MyFile.txt
  • You want to move the link and MyDocs\MyFile.txt to d:\.

You can assist the resolution process by creating the original link with a relative path before the shortcut is saved:

::SetRelativePath("c:\MyLink.lnk", NULL);

Before the shortcut is resolved, set a new relative path, and the Resolve code will find the file in its new location.

::SetRelativePath("d:\MyLink.lnk", NULL);

Remarks

Clients commonly define a relative link when it mey be moved along with its target, causing the absolute path to become invalid. The SetRelativePath method can be used to help the link resolution process find its target based on a common path prefix between the target and the relative path. To assist in the resolution process, clients should set the relative path as part of the link creation process.

See Also

See also IShellLink, IShellLink::Resolve, IShellLink::SetPath, IShellLink::SetIDList

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetShowCmd

Sets the show command for a Shell link object. The show command sets the initial show state of the window.

HRESULT STDMETHODCALLTYPE SetShowCmd(
    int iShowCmd
);

Parameters

iShowCmd
Command. SetShowCmd accepts one of the following ShowWindow commands:
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when displaying the window for the first time.
SW_SHOWMAXIMIZED | Activates the window and displays it as a maximized window.
SW_SHOWMINNOACTIVE | Displays the window in its minimized state, leaving the currently active window as active.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See also

IShellLink, IShellLink::GetShowCmd

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLink::SetWorkingDirectory

Sets the name of the working directory for a Shell link object.

HRESULT STDMETHODCALLTYPE SetWorkingDirectory(
    LPCSTR pszDir
   );

Parameters

pszDir
Address of a buffer that contains the name of the new working directory.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The working directory is optional unless the target requires a working directory. For example, if an application creates a Shell link to a Microsoft® Word document that uses a template residing in a different directory, the application would use this method to set the working directory.

See Also

IShellLink

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellLinkDataList

The IShellLinkDataList interface allows an application to attach extra data blocks to a Shell link. It provides methods to add, copy, or remove data blocks. The data blocks are in the form of a structure. The first two members are the same for all data blocks. The first member gives the structure's size. The second member is a signature that identifies the type of data block. The remaining members hold the block's data. There are five types of data block currently supported.

Data block structure | Description
EXP_DARWIN_LINK | The link's Windows® Installer ID.
EXP_SPECIAL_FOLDER | Special folder information.
EXP_SZ_LINK | The target name.
NT_CONSOLE_PROPS | Console properties.
NT_FE_CONSOLE_PROPS | The console's code page.

When to Implement

This interface is not implemented by applications.

When to Use

Use this interface if your application needs to add extra data blocks to a Shell link.

Methods

IShellLinkDataList exposes the following methods in addition to IUnknown.

AddDataBlock | Adds a data block to a link.
CopyDataBlock | Retrieves a copy of a link's data block.
GetFlags | Retrieves the current option settings.
RemoveDataBlock | Removes a data block from a link.
SetFlags | Specifies the current option settings.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IShellLinkDataList::AddDataBlock

Adds a data block to a link.

HRESULT AddDataBlock(
    VOID *pDataBlock
);

Parameters

pDataBlock
[in] Data block structure. For a list of supported structures, see IShellLinkDataList.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IShellLinkDataList

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellLinkDataList::CopyDataBlock

Retrieves a copy of a link's data block.

HRESULT CopyDataBlock(
    DWORD dwSig
    VOID **ppDataBlock)
);

Parameters

dwSig
[in] Data block's signature. The signature value for a particular type of data block can be found in its structure reference. For a list of supported data block types and their associated structures, see IShellLinkDataList.
ppDataBlock
[out] Address of a pointer to a copy of the data block structure. If CopyDataBlock returns a successful result, the caller must free the memory when it is no longer needed by calling LocalFree.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IShellLinkDataList

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellLinkDataList::GetFlags

Retrieves the current option settings.

HRESULT GetFlags(
    DWORD *pdwFlags
);

Parameters

pdwFlags
[out] Address of a flag value that indicates the current option settings. This parameter can be a combination of the following values.
SLDF_FORCE_NO_LINKINFO | Do not create link information. Distributed tracking will be disabled.
SLDF_HAS_ARGS | The link has arguments.
SLDF_HAS_DARWINID | The link is a special Windows® Installer link.
SLDF_HAS_EXP_ICON_SZ | The link contains an expandable environment string for the icon path.
SLDF_HAS_EXP_SZ | The link contains expandable environment strings such as "%windir%".
SLDF_HAS_ICONLOCATION | The link has an icon location.
SLDF_HAS_ID_LIST | The Shell link was saved with an ID list.
SLDF_HAS_LINK_INFO | The Shell link was saved with link information to enable distributed tracking.
SLDF_HAS_LOGO3ID | Not currently supported.
SLDF_HAS_NAME | The link has a name.
SLDF_HAS_RELPATH | The link has a relative path.
SLDF_HAS_WORKINGDIR | The link has a working directory.
SLDF_RUNAS_USER | Run this link as a different user.
SLDF_RUN_IN_SEPARATE | Run the 16-bit target application in a separate VDM/WOW.
SLDF_UNICODE | Strings are in Unicode.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IShellLinkDataList

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellLinkDataList::RemoveDataBlock

Removes a data block from a link.

HRESULT RemoveDataBlock(
    DWORD dwSig
);

Parameters

dwSig
[in] Data block's signature. The signature value for a particular type of data block can be found in its structure reference. For a list of supported data block types and their associated structures, see IShellLinkDataList.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IShellLinkDataList

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellLinkDataList::SetFlags

Specifies the current option settings.

HRESULT SetFlags(
    DWORD dwFlags
);

Parameters

dwFlags
[in] Flags that specify the option settings. This parameter can be a combination of the following values.
SLDF_FORCE_NO_LINKINFO | Do not create link information. Distributed tracking will be disabled.
SLDF_HAS_ARGS | The link has arguments.
SLDF_HAS_DARWINID | The link is a special Windows® Installer link.
SLDF_HAS_EXP_ICON_SZ | The link contains an expandable environment string for the icon path.
SLDF_HAS_EXP_SZ | The link contains expandable environment strings such as "%windir%".
SLDF_HAS_ICONLOCATION | The link has an icon location.
SLDF_HAS_ID_LIST | The Shell link was saved with an ID list.
SLDF_HAS_LINK_INFO | The Shell link was saved with link information to enable distributed tracking.
SLDF_HAS_LOGO3ID | Not currently supported.
SLDF_HAS_NAME | The link has a name.
SLDF_HAS_RELPATH | The link has a relative path.
SLDF_HAS_WORKINGDIR | The link has a working directory.
SLDF_RUNAS_USER | Run this link as a different user.
SLDF_RUN_IN_SEPARATE | Run the 16-bit target application in a separate VDM/WOW.
SLDF_UNICODE | Strings are in Unicode.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

IShellLinkDataList

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


IShellPropSheetExt

The IShellPropSheetExt interface allows a property sheet handler to add or replace pages in the property sheet displayed for a file object.
IShellPropSheetExt Methods | Description
AddPages | Adds one or more pages to a property sheet for a file object.
ReplacePage | Replaces a page in a property sheet for a Control Panel object.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellPropSheetExt::AddPages

Adds one or more pages to a property sheet that the Shell displays for a file object. When it is about to display the property sheet, the Shell calls this method for each property sheet handler registered to the file type.

HRESULT STDMETHODCALLTYPE AddPages(
    LPFNADDPROPSHEETPAGE lpfnAddPage,
    LPARAM lParam
);

Parameters

lpfnAddPage
Address of a function that the property sheet handler calls to add a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the AddPages method.
lParam
Parameter to pass to the function specified by the lpfnAddPage method.

Return Values

Returns S_OK if successful. If the method fails, an OLE-defined error code is returned.

Version 4.71. If successful, returns a one-based index to specify the page that should be initially displayed. See the remarks for more information.

If the method fails, an OLE-defined error code is returned.

Remarks

For each page the property sheet handler needs to add to a property sheet, the handler fills a PROPSHEETPAGE structure, calls the CreatePropertySheetPage function, and then calls the function specified by the lpfnAddPage parameter.

Prior to version 4.71, the property sheet determines which page will be initially displayed. With version 4.71 and later, you can request that a particular property sheet page be displayed first, instead of the default page. To do so, return the one-based index of the desired page. For example, if you want the second of three pages displayed, the return value should be 2. Note that this return value is a request. The property sheet may still display the default page.

See Also

IShellPropSheetExt

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellPropSheetExt::ReplacePage

Replaces a page in a property sheet for a Control Panel object.

HRESULT STDMETHODCALLTYPE ReplacePage(
    UINT uPageID,
    LPFNADDPROPSHEETPAGE lpfnReplacePage,
    LPARAM lParam
   );

Parameters

uPageID
Identifier of the page to replace. The values for this parameter for Control Panels can be found in the Cplext.h header file.
lpfnReplacePage
Address of a function that the property sheet handler calls to replace a page to the property sheet. The function takes a property sheet handle returned by the CreatePropertySheetPage function and the lParam parameter passed to the ReplacePage method.
lParam
Parameter to pass to the function specified by the lpfnReplacePage parameter.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

To replace a page, a property sheet handler fills a PROPSHEETPAGE structure, calls CreatePropertySheetPage, and then calls the function specified by lpfnReplacePage.

See Also

IShellPropSheetExt

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView

The IShellView interface is implemented to present a view in the Windows Explorer or folder windows. The object that exposes IShellView is created by a call to the IShellFolder::CreateViewObject method. This provides the channel of communication between a view object and Windows Explorer's outermost frame window. The communication involves the translation of messages, the state of the frame window (activated or deactivated), the state of the document window (activated or deactivated), and the merging of menus and toolbar items.

When to Implement

This interface is implemented by namespace extensions that display themselves in Windows Explorer's namespace. This object is created by the IShellFolder object that hosts the view.

When to Use

These methods are used by the Shell view's Windows Explorer window to manipulate objects while they are active.

Methods

IShellView is derived from IOleWindow. The following are the methods specific to IShellView:

AddPropertySheetPages | Allows the view to add pages to the Options property sheet.
CreateViewWindow | Creates the view window.
DestroyViewWindow | Destroys the view window.
EnableModeless | Enables or disables modeless dialog boxes. Not in use by Windows Explorer at this time.
EnableModelessSV | Not currently in use.
GetCurrentInfo | Returns the current folder settings.
GetItemObject | Allows callers to retrieve an object that represents something in the view.
Refresh | Refreshes the display in response to user input.
SaveViewState | Saves the Shell's view settings so the current state can be restored during a subsequent browsing session.
SelectItem | Changes the state of items within the Shell view window.
TranslateAccelerator | Translates accelerator key strokes when a namespace extension's view has the focus.
UIActivate | Called whenever the activation state of the view window is changed by an event not caused by the Shell view itself.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::AddPropertySheetPages

Allows the view to add pages to the Options property sheet from the View menu.

HRESULT AddPropertySheetPages(
    DWORD dwReserved,
    LPFNADDPROPSHEETPAGE lpfn,
    LPARAM lparam
   );

Parameters

dwReserved
Reserved.
lpfn
[in] Address of the callback function used to add the pages.
lparam
[in] Value that must be passed as the callback function's lParam parameter.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Notes to Implementers

Windows Explorer calls this method when it is opening the Options property sheet from the View menu. Views can add pages by creating them and calling the callback function with the page handles.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::CreateViewWindow

Creates a view window. This can be either the right pane of Windows Explorer or the client window of a folder window.

HRESULT CreateViewWindow(
    IShellView *psvPrevious,
    LPCFOLDERSETTINGS pfs,
    IShellBrowser *psb,
    RECT *prcView,
    HWND *phWnd
   );

Parameters

lpPrevView
[in] Address of the IShellView interface of the view window being exited. Views can use this parameter to communicate with a previous view of the same implementation. This interface can be used to optimize browsing between like views. This pointer may be NULL.
lpfs
[in] Address of a FOLDERSETTINGS structure. The view should use this when creating its view.
psb
[in] Address of the current instance of the IShellBrowser interface. The view should call this interface's AddRef method and keep the interface pointer to allow communication with the Windows Explorer window.
prcView
[in] Dimensions of the new view, in client coordinates.
phWnd
[out] Address of the window handle being created.

Return Values

Returns an OLE success code if successful, or an OLE error code otherwise. Use the SUCCEEDED and FAILED macros to determine whether the operation succeeded or failed.

Remarks

Notes to Callers

Call this method when the view needs to be created.

Notes to Implementers

Create your view window and restore any persistent state by calling the IShellBrowser::GetViewStateStream method. Store the IShellBrowser pointer for further use.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::DestroyViewWindow

Destroys the view window.

HRESULT DestroyViewWindow(void)

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Windows Explorer calls this method when a folder window or Explorer is being closed.

Notes to Implementers

Clean up all states that represent the view, including the window and any other associated resources.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::EnableModeless

Enables or disables modeless dialog boxes. This method is not currently implemented.

HRESULT EnableModeless(
    BOOL fEnable
   );

Parameters

fEnable
Nonzero to enable modeless dialog box windows or zero to disable them.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::EnableModelessSV

Not currently implemented.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::GetCurrentInfo

Retrieves the current folder settings.

HRESULT GetCurrentInfo(
    LPFOLDERSETTINGS lpfs
   );

Parameters

lpfs
Address of a FOLDERSETTINGS structure to receive the settings.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Windows Explorer uses this method to query the view for standard settings.

Notes to Callers

This method is used to retrieve the current view settings of the view.

Notes to Implementers

Return as many of the settings as apply. This is intended to maintain the same basic settings when the user browses from view to view. For example, if the user sets the Details view, that view should be maintained as the user goes from one folder to the other in Windows Explorer mode.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::GetItemObject

Retrieves an interface that refers to data presented in the view.

HRESULT GetItemObject(
    UINT uItem,
    REFIID riid,
    LPVOID *ppv
   );

Parameters

uItem
Constants that refer to an aspect of the view. This parameter can be any of the following values:
SVGIO_BACKGROUND | Refers to the background of the view. It is used with IID_IContextMenu to get a shortcut menu for the view background.
SVGIO_SELECTION | Refers to the currently selected items. IID_IDataObject uses this constant to retrieve a data object that represents the selected items.
SVGIO_ALLVIEW | Same as SVGIO_SELECTION but refers to all items in the view.
riid
Identifier of the COM interface being requested.
ppv
Address that receives the interface pointer. If an error occurs, the pointer returned must be NULL.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Used by the common dialog boxes to retrieve the selected items from the view.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::Refresh

Refreshes the view's contents in response to user input.

HRESULT Refresh(void)

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Tells the view to refresh its contents, revalidating any view information it has.

Notes to Callers

Windows Explorer calls this method when the F5 key is pressed on an already open view.

Notes to Implementers

Refill the view by going to any underlying storage for the contents.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::SaveViewState

Saves the Shell's view settings so the current state can be restored during a subsequent browsing session.

HRESULT SaveViewState(void)

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

The Shell view obtains a view stream by calling the IShellBrowser::GetViewStateStream method and stores the current view state in that stream.

Notes to Callers

Windows Explorer calls this method when it wants to save the view state for a view.

Notes to Implementers

Be sure to make the format of the data stored in the stream robust enough that different versions of the implementation can read it without error.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::SelectItem

Changes the selection state of one or more items within the Shell view window.

HRESULT SelectItem(
    LPCITEMIDLIST pidlItem,
    UINT uFlags
   );

Parameters

pidlItem
Address of the ITEMIDLIST structure.
uFlags
Flag specifying what type of selection to apply. This parameter can be one of the following values:
SVSI_DESELECT | Deselect the specified item.
SVSI_DESELECTOTHERS | Deselect all but the specified item. If pidlItem is NULL, deselect all items.
SVSI_EDIT | Put pidlItem in edit mode.
SVSI_ENSUREVISIBLE | Ensure the item is displayed on the screen.
SVSI_FOCUSED | The item should be given the focus.
SVSI_SELECT | The item should be selected.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Notes to Implementers

This method is used to implement the Target command from the File menu of the Shell shortcut property sheet.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::TranslateAccelerator

Translates accelerator key strokes when a namespace extension's view has the focus.

HRESULT TranslateAccelerator(
    LPMSG lpmsg
   );

Parameters

lpmsg
Address of the message to be translated.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

If the view returns S_OK, it indicates that the message was translated and should not be translated or dispatched by Windows Explorer.

Remarks

This method is called by Windows Explorer to let the view translate its accelerators.

Notes to Callers

Windows Explorer calls this method before any other translation if the view has the focus. If the view does not have the focus, it is called after Explorer translates its own accelerators.

Notes to Implementers

By default, the view should return S_FALSE so that Windows Explorer can either do its own accelerator translation or normal menu dispatching. The view should return S_OK only if it has processed the message as the accelerator and does not want Explorer to process it further.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView::UIActivate

Called when the activation state of the view window is changed by an event that is not caused by the Shell view itself. For example, if the TAB key is pressed when the tree has the focus, the view should be given the focus.

HRESULT UIActivate(
    UINT uState
   );

Parameters

uState
Flag specifying the activation state of the window. This parameter can be one of the following values:
SVUIA_ACTIVATE_FOCUS | Windows Explorer has just created the view window with the input focus. This means the Shell view should be able to set menu items appropriate for the focused state.
SVUIA_ACTIVATE_NOFOCUS | The Shell view is losing the input focus, or it has just been created without the input focus. The Shell view should be able to set menu items appropriate for the nonfocused state. This means no selection-specific items should be added.
SVUIA_DEACTIVATE | Windows Explorer is about to destroy the Shell view window. The Shell view should remove all extended user interfaces. These are typically merged menus and merged modeless pop-up windows.
SVUIA_INPLACEACTIVATE | The Shell view is active without focus. This flag is only used when UIActivate is exposed through the IShellView2 interface.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

Before remerging menu items, the Shell view typically hooks the WM_SETFOCUS message and calls the IShellBrowser::OnViewWindowActive method. The Shell view should not hook the WM_KILLFOCUS message to remerge menu items.

Notes to Callers

Call this method to inform the view of an activation state change.

Notes to Implementers

Use this method to track the activation state and change any behavior, as appropriate.

See Also

IShellView

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IShellView2

The IShellView2 interface extends the capabilities of IShellView.

When to Implement

Implement IShellView2 if your namespace extension provides services to clients beyond those in IShellView.

When to Use

You do not call this interface directly. IShellView2 is used by the operating system only when it has confirmed that your application is aware of this interface. Objects that expose IShellView and IShellView2 are usually created by other Shell folder objects.

IShellView2 implements all the IShellView methods as well as IUnknown. The following methods are specific to IShellFolder2.
IShellFolder2 Methods | Description
CreateViewWindow2 | Used to request the creation of a Shell View window.
GetView | Used to request the GUID of the default or current Shell View.
HandleRename | Used to change an item's ID.
SelectAndPositionItem | Used to reposition an item.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IShellView2::CreateViewWindow2

Used to request the creation of a new Shell-view window. It can be either the right pane of Windows® Explorer or the client window of a folder window.

HRESULT CreateViewWindow2(
    LPSV2CVW2_PARAMS lpParams
);

Parameters

lpParams
Pointer to an SV2CVW2_PARAMS structure that defines the new view window.

Return Values

Returns an OLE success code if successful, or an OLE error code otherwise. Use the SUCCEEDED and FAILED macros to determine whether the operation succeeded or failed.

Remarks

This method supersedes IShellView::CreateViewWindow. With CreateViewWindow2, developers are not restricted to the standard view modes provided by IShellView::CreateWindow, but may also create their own. All view modes are now identified by their globally unique identifier (GUID).

The size of the structure, previous view window, folder settings, parent Shell browser, and view rectangle are passed into CreateViewWindow2 in the first five members of lpParams. The method is responsible for creating the new window and passing back its window handle and the GUID of the view mode in the last two parameters. CreateViewWindow2 should call the parent browser's IShellBrowser::AddRef method and store the interface pointer. It can be used for communication with the Windows Explorer window.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IShellView2::GetView

Used to request the globally unique identifier (GUID) for either the current or default Shell view.

HRESULT GetView(
    SHELLVIEWID	*pvid,
    ULONG uView
);

Parameters

pvid
[out] Identifier (GUID) of the requested view.
uView
[in] Type of view requested:
SV2GV_CURRENTVIEW | Current Shell view.
SV2GV_DEFAULTVIEW | Default Shell view.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IShellView2::HandleRename

Used to change an item's identifier.

HRESULT HandleRename(
    LPCITEMIDLIST pidlNew,
);

Parameters

pidlNew
Pointer to an ITEMIDLIST structure. The current identifier is passed in and is replaced by the new one.

Return Values

Return NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IShellView2::SelectAndPositionItem

Used to select and position an item in a Shell View.

HRESULT SelectAndPositionItem(
    LPCITEMIDLIST pidlItem,
    UINT uFlags,
    POINT point
);

Parameters

pidlItem
Pointer to an ITEMIDLIST structure that uniquely identifies the item of interest.
uFlags
Flags specifying the selection type. You can combine one or more of the following:
SVSI_DESELECT | Deselect the specified item. This flag is incompatible with SVSI_DESELECTOTHERS.
SVSI_DESELECTOTHERS | Deselect all but the specified item. If pidlItem is NULL, deselect all items. This flag is incompatible with SVSI_DESELECTOTHERS.
SVSI_EDIT | Put pidlItem in edit mode.
SVSI_ENSUREVISIBLE | Ensure the item is displayed on the screen.
SVSI_FOCUSED | The item should be given the focus.
SVSI_SELECT | The item should be selected.
SVSI_TRANSLATEPT | Convert the point from screen coordinates to client coordinates.
point
POINT structure containing the new position.

Return Values

Return NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList

The ITaskbarList interface is used to control the taskbar. It allows you to dynamically add items to the taskbar, remove items from the taskbar, and activate items on the taskbar. See Modifying Contents of the Taskbar for more information about using this interface.

When to Implement

You do not implement ITaskbarList; it is implemented by the Shell.

When to Use

You use ITaskbarList to add items to the taskbar, remove items from the taskbar, and activate items on the taskbar.

ITaskbarList is derived from IUnknown. The following methods are specific to ITaskbarList:

ITaskbarList Methods | Description
ActivateTab | Activates an item on the taskbar.
AddTab | Adds an item to the taskbar.
DeleteTab | Deletes an item from the taskbar.
HrInit | Initializes the taskbar list object.
SetActiveAlt | Marks a taskbar item as active but does not visually activate it.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList::ActivateTab

Activates an item on the taskbar. The window is not actually activated; the window's item on the taskbar is merely displayed as active.

HRESULT ActivateTab(
    HWND hwnd
);

Parameters

hwnd
Handle to the window on the taskbar to be displayed as active.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList::AddTab

Adds an item to the taskbar.

HRESULT AddTab(
    HWND hwnd
);

Parameters

hwnd
Handle to the window to be added to the taskbar.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

Any type of window can be added to the taskbar, but it is recommended that the window at least have the WS_CAPTION style.

Any window added with this method must be removed with the DeleteTab method when the added window is destroyed.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList::DeleteTab

Deletes an item from the taskbar.

HRESULT DeleteTab(
    HWND hwnd
);

Parameters

hwnd
Handle to the window to be deleted from the taskbar.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList::HrInit

Initializes the taskbar list object. This method must be called before any other ITaskbarList methods can be called.

HRESULT HrInit(void);

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise. If the method fails, no other methods can be called. The calling application should release the interface pointer.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList::SetActiveAlt

Marks a taskbar item as active but does not visually activate it.

HRESULT SetActiveAlt(
    HWND hwnd
);

Parameters

hwnd
Handle to the window to be marked as active.

Return Values

Returns NOERROR if successful, or an OLE-defined error code otherwise.

Remarks

SetActiveAlt marks the item associated with hwnd as the currently active item for the window's process without changing the pressed state of any item. Any user action that would activate a different tab in that process will activate the tab associated with hwnd instead. The active state of the window's item is not guaranteed to be preserved when the process associated with hwnd is not active. To ensure that a given tab is always active, call SetActiveAlt whenever any of your windows are activated. Calling SetActiveAlt with a NULL hwnd clears this state.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITaskbarList2 Interface

This is preliminary documentation and is subject to change.

The ITaskbarList2 interface extends the ITaskbarList interface by providing a method to mark a window as a full-screen display.

ITaskbarList2 Members

MarkFullscreenWindow Used to mark a window as full-screen.

Remarks

The Shell also automatically attempts to detect full-screen applications, but it is not as reliable as using the ITaskbarList2::MarkFullscreenWindow method.

Interface Information

Stock Implementation | shell32.dll
Custom Implementation | No
Inherits from | ITaskbarList
Header | shobjidl.h
Minimum operating systems | Whistler


ITaskbarList2::MarkFullscreenWindow Method

This is preliminary documentation and is subject to change.

Used to mark a window as full-screen.

Syntax

HRESULT MarkFullscreenWindow(
    HWND hwnd,
    BOOL fFullscreen
);

Parameters

hwnd
Handle of the window to be marked.
fFullscreen
A Boolean value marking the desired full-screen status of the window.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Setting the value of fFullscreen to TRUE, the Shell treats this window as a full-screen window, and the taskbar is moved to the bottom of the z-order when this window is active. Setting the value of fFullscreen to FALSE removes the full-screen marking, but does not cause the Shell to treat the window as though it were definitely not full-screen. With a FALSE fFullscreen value, the Shell will depend on its automatic detection facility to specify how the window should be treated, possibly still flagging the window as full-screen.

See Also

ITaskbarList


IURLSearchHook

The IURLSearchHook interface is used by the browser to translate the address of an unknown URL protocol. When attempting to browse to a URL address that does not contain a protocol, the browser will first attempt to determine the correct protocol from the address. If this is not successful, the browser will create URL Search Hook objects and call each object's Translate method until the address is translated or all of the hooks have been queried.

URL Search Hooks are registered by adding a value that contains the object's CLSID string under the following key in the registry:

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Internet Explorer
            UrlSearchHooks

When to Implement

Implement this interface if your application defines a custom URL protocol and if address translation for this protocol is required.

When to Use

You do not normally use this interface; it is called by the browser.
IURLSearchHook Method | Description
Translate | Called by the browser when the browser cannot determine the protocol of a URL address.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IURLSearchHook::Translate

Called by the browser when the browser cannot determine the protocol of a URL address.

HRESULT Translate(
    LPWSTR lpwszSearchURL,
    DWORD cchBufferSize
   );

Parameters

lpwszSearchURL
Address of a wide character buffer that, on entry, contains the URL address for which the browser is trying to determine the protocol. On exit, this buffer contains the modified URL address if the method was successful. See the return value for more information.
cchBufferSize
Size, in characters, of the buffer at lpwszSearchURL.

Return Values

This method must return one of the following values:
S_OK | The URL address was completely translated. The lpwszSearchURL parameter contains the full URL address. The browser will not call any other URL Search Hooks and will attempt to browse to the modified address.
S_FALSE | The URL address has been partially processed, but further translation is still required. The lpwszSearchURL parameter contains the result of the processing. The browser will continue executing the rest of the URL Search Hooks.
E_FAIL | The URL address was not translated. The lpwszSearchURL parameter has not been modified. The browser will continue executing the rest of the URL Search Hooks.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


IUserNotification Interface

This is preliminary documentation and is subject to change.

This interface provides methods that display ToolTip information to the user.

IUserNotification Members

SetBalloonInfo | Sets the information to be displayed in a balloon style ToolTip.>
SetBalloonRetry | Specifies the conditions for trying to display user information again.
SetIconInfo | Sets the icon associated with specific user information.
Show | Displays the user information balloon-style ToolTip.

Interface Information

Stock Implementation | shell32.dll
Custom Implementation | No
Inherits from | IUnknown
Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


IUserNotification::SetBalloonInfo Method

This is preliminary documentation and is subject to change.

Sets the information to be displayed in a balloon style ToolTip.>

Syntax

HRESULT SetBalloonInfo(
    LPCWSTR pszTitle,
    LPCWSTR pszText,
    DWORD dwInfoFlags
);

Parameters

pszTitle
[in] Pointer to a string that receives the title of the ToolTip.
pszText
[in] Pointer to a string that receives the text to be displayed in the balloon.
dwInfoFlags
[in] DWORD that contains the value of a state flag.

Return Value

Returns S_OK if successful, or an error value otherwise.


IUserNotification::SetBalloonRetry Method

This is preliminary documentation and is subject to change.

Specifies the conditions for trying to display user information again.

Syntax

HRESULT SetBalloonRetry(
    DWORD dwShowTime,
    DWORD dwInterval,
    UINT cRetryCount
);

Parameters

dwShowTime
[in] DWORD that specifies the length of time to display the user information.
dwInterval
[in] DWORD that specifies the interval of time between attempts to display the user information.
cRetryCount
[in] Integer that receives the number of times the system has tried to display the user information.

Return Value

Returns S_OK if successful, or an error value otherwise.


IUserNotification::SetIconInfo Method

This is preliminary documentation and is subject to change.

Sets the icon associated with specific user information.

Syntax

HRESULT SetIconInfo(
    HICON hIcon,
    LPCWSTR pszToolTip
);

Parameters

hIcon
[in] Handle to the icon.
pszToolTip
[in] Pointer to a string that contains the ToolTip information associated with the specified icon.

Return Value

Returns S_OK if successful, or an error value otherwise.


IUserNotification::Show Method

This is preliminary documentation and is subject to change.

Displays the user information balloon-style ToolTip.

Syntax

HRESULT Show(
    IQueryContinue *pqc,
    DWORD dwContinuePollInterval
);

Parameters

pqc
[in] Pointer to an IQueryContinue interface.
dwContinuePollInterval
[in] DWORD that specifies the amount of time to display user information.

Return Value

Returns S_OK if successful, or an error value otherwise.


CPlApplet

Library-defined callback function that serves as the entry point for a Control Panel application.

LONG CPlApplet(
    HWND hwndCPl,
    UINT uMsg,
    LPARAM lParam1,
    LPARAM lParam2
);

Parameters

hwndCPl
Identifier of the main window of the controlling application. Use the hwndCPl parameter for dialog boxes or other windows that require a handle to a parent window.
uMsg
Message being sent to the Control Panel application.
lParam1
Additional message-specific information.
lParam2
Additional message-specific information.

Return Values

The return value depends on the message.

For more information, see the descriptions of the individual Control Panel messages.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.
Import Library: user-defined.


CSIDL Values

A number of folders are used frequently by applications, but may not have the same name or location on any given system. For example, the system folder may be "C:\Windows" on one system and "C:\Winnt" on another. CSIDL values provide a unique system-independent way to identify these special folders. The values supersede the use of environment variables for this purpose.

A CSIDL is used in conjunction with one of four Shell functions, SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, and SHGetSpecialFolderPath, to retrieve a special folder's pathname or item ID list (PIDL).

If a special folder does not exist, you can force its creation by using the following special CSIDL:

CSIDL_FLAG_CREATE
Version 5.0. Combine this CSIDL with any of the CSIDLs listed below to force the creation of the associated folder.

The remaining CSIDLs correspond to either file system folders or virtual folders. Where the CSIDL identifies a file system folder, a commonly used path is given as an example. Other paths may be used. Some CSIDLs can be mapped to an equivalent %VariableName% environment variable. CSIDLs are more reliable, however, and should be used if possible.

CSIDL_ADMINTOOLS
Version 5.0. File system directory that is used to store administrative tools for an individual user. The Microsoft Management Console will save customized consoles to this directory, and it will roam with the user.
CSIDL_ALTSTARTUP
File system directory that corresponds to the user's nonlocalized Startup program group.
CSIDL_APPDATA
Version 4.71. File system directory that serves as a common repository for application-specific data. A typical path is C:\Documents and Settings\username\Application Data. This CSIDL is supported by the redistributable ShFolder.dll for systems that do not have the Internet Explorer 4.0 integrated Shell installed.
CSIDL_BITBUCKET
Virtual folder containing the objects in the user's Recycle Bin.
CSIDL_COMMON_ADMINTOOLS
Version 5.0. File system directory containing containing administrative tools for all users of the computer.
CSIDL_COMMON_ALTSTARTUP
File system directory that corresponds to the nonlocalized Startup program group for all users. Valid only for Windows NT® systems.
CSIDL_COMMON_APPDATA
Version 5.0. Application data for all users. A typical path is C:\Documents and Settings\All Users\Application Data.
CSIDL_COMMON_DESKTOPDIRECTORY
File system directory that contains files and folders that appear on the desktop for all users. A typical path is C:\Documents and Settings\All Users\Desktop. Valid only for Windows NT® systems.
CSIDL_COMMON_DOCUMENTS
File system directory that contains documents that are common to all users. Typical paths are C:\Documents and Settings\All Users\Documents. Valid for Windows NT® systems and Windows 95 and Windows 98 systems with Shfolder.dll installed.
CSIDL_COMMON_FAVORITES
File system directory that serves as a common repository for all users' favorite items. Valid only for Windows NT® systems.
CSIDL_COMMON_PROGRAMS
File system directory that contains the directories for the common program groups that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs. Valid only for Windows NT® systems.
CSIDL_COMMON_STARTMENU
File system directory that contains the programs and folders that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu. Valid only for Windows NT® systems.
CSIDL_COMMON_STARTUP
File system directory that contains the programs that appear in the Startup folder for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs\Startup. Valid only for Windows NT® systems.
CSIDL_COMMON_TEMPLATES
File system directory that contains the templates that are available to all users. A typical path is C:\Documents and Settings\All Users\Templates. Valid only for Windows NT® systems.
CSIDL_CONTROLS
Virtual folder containing icons for the Control Panel applications.
CSIDL_COOKIES
File system directory that serves as a common repository for Internet cookies. A typical path is C:\Documents and Settings\username\Cookies.
CSIDL_DESKTOP
Windows Desktop—virtual folder that is the root of the namespace.
CSIDL_DESKTOPDIRECTORY
File system directory used to physically store file objects on the desktop (not to be confused with the desktop folder itself). A typical path is C:\Documents and Settings\username\Desktop
CSIDL_DRIVES
My Computer—virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. The folder may also contain mapped network drives.
CSIDL_FAVORITES
File system directory that serves as a common repository for the user's favorite items. A typical path is C:\Documents and Settings\username\Favorites.
CSIDL_FONTS
Virtual folder containing fonts. A typical path is C:\WINNT\Fonts.
CSIDL_HISTORY
File system directory that serves as a common repository for Internet history items.
CSIDL_INTERNET
Virtual folder representing the Internet.
CSIDL_INTERNET_CACHE
Version 4.72. File system directory that serves as a common repository for temporary Internet files. A typical path is C:\Documents and Settings\username\Temporary Internet Files.
CSIDL_LOCAL_APPDATA
Version 5.0. File system directory that serves as a data repository for local (nonroaming) applications. A typical path is C:\Documents and Settings\username\Local Settings\Application Data.
CSIDL_MYMUSIC
File system directory that serves as a common repository for music files. A typical path is C:\My Music.
CSIDL_MYPICTURES
Version 5.0. My Pictures folder. A typical path is C:\Documents and Settings\username\My Documents\My Pictures.
CSIDL_NETHOOD
A file system folder containing the link objects that may exist in the My Network Places virtual folder. It is not the same as CSIDL_NETWORK, which represents the network namespace root. A typical path is C:\Documents and Settings\username\NetHood.
CSIDL_NETWORK
Network Neighborhood—virtual folder representing the root of the network namespace hierarchy.
CSIDL_PERSONAL
File system directory that serves as a common repository for documents. A typical path is C:\Documents and Settings\username\My Documents. This should be distinguished from the virtual My Documents folder in the namespace. To access that virtual folder, use the technique described in Managing the File System.
CSIDL_PRINTERS
Virtual folder containing installed printers.
CSIDL_PRINTHOOD
File system directory that contains the link objects that may exist in the Printers virtual folder. A typical path is C:\Documents and Settings\username\PrintHood.
CSIDL_PROFILE
Version 5.0. User's profile folder.
CSIDL_PROGRAM_FILES
Version 5.0. Program Files folder. A typical path is C:\Program Files.
CSIDL_PROGRAM_FILES_COMMON
Version 5.0. A folder for components that are shared across applications. A typical path is C:\Program Files\Common. Valid only for Windows NT® and Windows® 2000 systems.
CSIDL_PROGRAMS
File system directory that contains the user's program groups (which are also file system directories). A typical path is C:\Documents and Settings\username\Start Menu\Programs.
CSIDL_RECENT
File system directory that contains the user's most recently used documents. A typical path is C:\Documents and Settings\username\Recent. To create a shortcut in this folder, use SHAddToRecentDocs. In addition to creating the shortcut, this function updates the Shell's list of recent documents and adds the shortcut to the Documents submenu of the Start menu.
CSIDL_SENDTO
File system directory that contains Send To menu items. A typical path is C:\Documents and Settings\username\SendTo.
CSIDL_STARTMENU
File system directory containing Start menu items. A typical path is C:\Documents and Settings\username\Start Menu.
CSIDL_STARTUP
File system directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT® or starts Windows® 95. A typical path is C:\Documents and Settings\username\Start Menu\Programs\Startup.
CSIDL_SYSTEM
Version 5.0. System folder. A typical path is C:\WINNT\SYSTEM32.
CSIDL_TEMPLATES
File system directory that serves as a common repository for document templates.
CSIDL_WINDOWS
Version 5.0. Windows directory or SYSROOT. This corresponds to the %windir% or %SYSTEMROOT% environment variables. A typical path is C:\WINNT.

See Also

SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, SHGetSpecialFolderPath


DefScreenSaverProc

Provides default processing for any messages that a screen saver application does not process.

LONG DefScreenSaverProc(
    HWND hWnd,
    UINT msg,
    WPARAM wParam,
    LPARAM lParam
);

Parameters

hWnd
Identifier of the screen saver window.
msg
Message to be processed. The DefScreenSaverProc function responds to messages that affect the screen saver's operation, as detailed in the Remarks section.
If a screen saver application must perform a different action in response to any of these messages, the application's ScreenSaverProc window procedure should process the message.
wParam
Additional message-specific information.
lParam
Additional message-specific information.

Return Values

The return value specifies the result of the message processing and depends on the message sent.

Remarks

A screen saver application's ScreenSaverProc window procedure should use DefScreenSaverProc instead of the DefWindowProc function to provide default message processing. The DefScreenSaverProc function passes any messages that do not affect screen saver operation to DefWindowProc.

The following table describes how the DefScreenSaverProc processes a variety of window messages.

WM_ACTIVATE, WM_ACTIVATEAPP, WM_NCACTIVATE
Closes the screen saver if the wParam parameter is FALSE. A wParam value of FALSE indicates that the screen saver is losing the input focus. The screen saver is closed by sending a WM_CLOSE message.
WM_SETCURSOR
Removes the cursor from the screen by setting the cursor to NULL.
WM_LBUTTONDOWN, WM_RBUTTONDOWN, WM_MBUTTONDOWN, WM_KEYDOWN, WM_KEYUP, WM_MOUSEMOVE
Calls the PostQuitMessage function to close the screen saver.
WM_DESTROY
Posts a WM_CLOSE message to close the screen saver window.
WM_SYSCOMMAND
Returns FALSE if the wParam parameter of WM_SYSCOMMAND is either SC_CLOSE or SC_SCREENSAVE.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in scrnsave.h.
Import Library: scrnsave.lib.


DefSubclassProc Function

Calls the next handler in a window's subclass chain.

Syntax

HRESULT DefSubclassProc(
    HWND hWnd,
    UINT uMsg,
    WPARAM WPARAM,
    LPARAM LPARAM
);

Parameters

hWnd
[in] Handle of window being subclassed.
uMsg
[in] Value of type unsigned integer that specifies a window message.
WPARAM
[in] Value of type WPARAM that specifies window message's WPARAM parameter.
LPARAM
[in] Value of type LPARAM that specifies the window message's LPARAM parameter. Note: On 64-bit versions of Microsoft® Windows® LPARAM is a 64-bit value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

You do not need to call the default window procedure; this function calls it automatically.

Function Information

Stock Implementation | comctl32.dll version 6.0 or later
Custom Implementation | No
Header | commctrl.h
Import library | comctl32.lib
Minimum operating systems | Whistler

See Also

GetWindowSubclass, SetWindowSubclass, RemoveWindowSubclass


DoEnvironmentSubst

Parses an input string containing references to one or more environment variables and replaces them with their current values.

DWORD DoEnvironmentSubst(
    LPCTSTR szString,
    UINT cchString
);

Parameters

pszString
Null-terminated string that contains references to one or more environment variables in the form:
    %VariableName%

Case is ignored. Each %VariableName% string is replaced with the variable's current value. The replacement rules are the same as those used by the command interpreter. If the name is not found, the %variableName% string is left intact.

As environment variables can be added by the user or applications, the complete list is system-dependent. The following environment variables are standard with Microsoft® Windows NT® and are available to both interactive applications and services.
COMPUTERNAME | NUMBER_OF_PROCESSORS
OS | PROCESSOR_ARCHITECTURE
PROCESSOR_IDENTIFIER | PROCESSOR_LEVEL
PROCESSOR_REVISION | PROGRAMFILES
SYSTEMDRIVE | SYSTEMROOT
USERPROFILE | WINDIR

The remainder are only available to interactive applications.
HOMEDRIVE | HOMEPATH
LOGONSERVER | USERDOMAIN
USERNAME

Only the WINDIR variable is available on Windows® 95/98 systems.

cbSize
Size of the pszString buffer. It must be large enough to hold the values that will be returned.

Return Values

If the expanded values don't overfill the buffer, they replace the original pszString array. TRUE is returned in the LOWORD, and the length of pszString is returned in the HIWORD. If the buffer is too small, pszString is not modified. FALSE is returned in the LOWORD and cbSize in the HIWORD.

Remarks

This function is retained for backward compatibility with Windows 3.1. Use ExpandEnvironmentStrings instead.

Because the string that is returned in pszString will normally be longer than the input string, make sure that the buffer is large enough.

The environment variables that correspond to file system folders can be mapped to an equivalent CSIDL value and obtained with SHGetFolderLocation. CSIDLs are more reliable than variable names and should be used if at all possible.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


DllGetVersion

Implemented by many of the Windows Shell DLLs to allow applications to obtain DLL-specific version information.

HRESULT CALLBACK DllGetVersion(
    DLLVERSIONINFO *pdvi
);

Parameters

pdvi
Pointer to a DLLVERSIONINFO structure that receives the version information. The cbSize member must be filled in before calling the function.

Version 5.0. DLLs that are shipped with Windows 2000 or later systems may return a DLLVERSIONINFO2 structure. To maintain backward compatibility, the first member of a DLLVERSIONINFO2 structure is a DLLVERSIONINFO structure.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This function is not an API. It is exported by name from each DLL that implements it. Currently, most of the Windows Shell and common controls DLLs implement DllGetVersion. These include, but are not limited to, Shell32.dll, Comctl32.dll, Shdocvw.dll, and Shlwapi.dll.

To call this function, use the LoadLibrary and GetProcAddress functions to obtain the function pointer. The DLLGETVERSIONPROC type is used as the data type for the function pointer. See Shell and Common Controls Versions for a detailed discussion of Shell and common controls versions, and how to use DllGetVersion.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlwapi.h.


DLLGETVERSIONPROC

This type definition is used to define a pointer to a DllGetVersion function. This pointer is used when calling the function dynamically by loading the library and getting the function's address. For more information, see the example in DllGetVersion.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlwapi.h.
Import Library: user_defined.


DragAcceptFiles

Registers whether a window accepts dropped files.

VOID DragAcceptFiles(
    HWND hWnd,
    BOOL fAccept
);

Parameters

hWnd
Identifier of the window that is registering whether it will accept dropped files.
fAccept
Value that indicates if the window identified by the hWnd parameter accepts dropped files. This value is TRUE to accept dropped files or FALSE to discontinue accepting dropped files.

Return Values

No return value.

Remarks

An application that calls DragAcceptFiles with the fAccept parameter set to TRUE has identified itself as able to process the WM_DROPFILES message from File Manager.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


DragFinish

Releases memory that the system allocated for use in transferring file names to the application.

VOID DragFinish(
    HDROP hDrop
);

Parameters

hDrop
Identifier of the structure that describes dropped files. This handle is retrieved from the wParam parameter of the WM_DROPFILES message.

Return Values

No return value.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


DragQueryFile

Retrieves the names of dropped files that result from a successful drag-and-drop operation.

UINT DragQueryFile(
    HDROP hDrop,
    UINT iFile,
    LPTSTR lpszFile,
    UINT cch
);

Parameters

hDrop
Identifier of the structure containing the file names of the dropped files.
iFile
Index of the file to query. If the value of the iFile parameter is 0xFFFFFFFF, DragQueryFile returns a count of the files dropped. If the value of the iFile parameter is between zero and the total number of files dropped, DragQueryFile copies the file name with the corresponding value to the buffer pointed to by the lpszFile parameter.
lpszFile
Address of a buffer to receive the file name of a dropped file when the function returns. This file name is a null-terminated string. If this parameter is NULL, DragQueryFile returns the required size, in characters, of the buffer.
cch
Size, in characters, of the lpszFile buffer.

Return Values

When the function copies a file name to the buffer, the return value is a count of the characters copied, not including the terminating null character.

If the index value is 0xFFFFFFFF, the return value is a count of the dropped files. Note that the index variable itself returns unchanged, and will therefore remain 0xFFFFFFFF.

If the index value is between zero and the total number of dropped files and the lpszFile buffer address is NULL, the return value is the required size, in characters, of the buffer, not including the terminating null character.

See Also

DragQueryPoint

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


DragQueryPoint

Retrieves the position of the mouse pointer at the time a file was dropped during a drag-and-drop operation.

BOOL DragQueryPoint(
    HDROP hDrop,
    LPPOINT lppt
);

Parameters

hDrop
Identifier of the structure that describes the dropped file.
lppt
Address of a POINT structure that the function fills with the coordinates of the mouse pointer at the time the file was dropped.

Return Values

Returns nonzero if the drop occurred in the client area of the window, or zero if the drop did not occur in the client area of the window.

Remarks

The window for which coordinates are returned is the window that received the WM_DROPFILES message.

See Also

DragQueryFile

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


FindEnvironmentString

Looks up the specified environment variable and returns a pointer to its value.

LPCTSTR FindEnvironmentString(
    LPCTSTR pszEnvVar,
);

Parameters

pszEnvVar
Null-terminated string with the environment variable of interest. Case is ignored. Because environment variables can be added by the user or applications, the complete list is system-dependent. The following environment variables are standard with Microsoft® Windows NT® and are available to both interactive applications and services.
COMPUTERNAME | NUMBER_OF_PROCESSORS
OS | PROCESSOR_ARCHITECTURE
PROCESSOR_IDENTIFIER | PROCESSOR_LEVEL
PROCESSOR_REVISION | PROGRAMFILES
SYSTEMDRIVE | SYSTEMROOT
USERPROFILE | WINDIR

The remainder are only available to interactive applications.
HOMEDRIVE | HOMEPATH
LOGONSERVER | USERDOMAIN
USERNAME

Only the WINDIR variable is available on Windows 95/98 systems.

Return Values

Returns the value of the environment variable, or returns NULL if the variable isn't in the environment.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.


FindExecutable

Retrieves the name of and handle to the executable (.exe) file associated with the specified file name.

HINSTANCE FindExecutable(
    LPCTSTR lpFile,
    LPCTSTR lpDirectory,
    LPTSTR lpResult
);

Parameters

lpFile
Address of a null-terminated string specifying a file name. This should be a document.
lpDirectory
Address of a null-terminated string specifying the default directory.
lpResult
Address of a buffer to receive the file name when the function returns. This file name is a null-terminated string specifying the executable file started when an "open" by association is run on the file specified in the lpFile parameter.

Return Values

Returns a value greater than 32 if successful, or a value less than or equal to 32 otherwise.

The following table lists the possible error values:
0 | The system is out of memory or resources.
31 | There is no association for the specified file type.
ERROR_FILE_NOT_FOUND | The specified file was not found.
ERROR_PATH_NOT_FOUND | The specified path was not found.
ERROR_BAD_FORMAT | The .exe file is invalid (non-Win32 .exe or error in .exe image).

Remarks

Use FindExecutable for documents. If you want to retrieve the path of an executable file, use the following:

AssocQueryString(ASSOCF_OPEN_BYEXENAME,
                 ASSOCSTR_EXECUTABLE,
                 pszExecutableName,
                 NULL,
                 pszPath,
                 pcchOut);

Here, pszExecutableName is a pointer to a null-terminated string that specifies the name of the executable file, pszPath is a pointer to the null-terminated string buffer that receives the path to the executable file, and pcchOut is a pointer to a DWORD that specifies the number of characters in the pszPath buffer. When the function returns, pcchOut will be set to the number of characters actually placed in the buffer. See AssocQueryString for more information.

When FindExecutable returns, the lpResult parameter may contain the path to the DDE (Dynamic Data Exchange) server started if a server does not respond to a request to initiate a DDE conversation with the DDE client application.

See Also

ShellExecute

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


GetMenuContextHelpId

Retrieves the Help context identifier associated with the specified menu.

DWORD GetMenuContextHelpId(
    HMENU hmenu
);

Parameters

hmenu
Handle to the menu for which the Help context identifier is to be retrieved.

Return Values

Returns the Help context identifier if the menu has one, or zero otherwise.

See Also

SetMenuContextHelpId

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.
Import Library: user32.lib.


GetWindowContextHelpId

Retrieves the Help context identifier, if any, associated with the specified window.

DWORD GetWindowContextHelpId(
    HWND hwnd
);

Parameters

hwnd
Handle to the window for which the Help context identifier is to be retrieved.

Return Values

Returns the Help context identifier if the window has one, or zero otherwise.

See Also

SetWindowContextHelpId

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.
Import Library: user32.lib.


GetWindowSubclass Function

Retrieves the reference data for the specified window subclass callback.

Syntax

HRESULT GetWindowSubclass(
    HWND hWnd,
    SUBCLASSPROC pfnSubclass,
    UINT_PTR uIdSubclass,
    DWORD_PTR *pdwRefData
);

Parameters

hWnd
[in] Handle of the window being subclassed.
pfnSubclass
[in] Pointer to a window procedure. This pointer and the subclass identifier (ID) uniquely identify this subclass callback.
uIdSubclass
[in] ULONG_PTR subclass ID. This ID and the callback pointer uniquely identify this subclass callback. Note: On 64-bit versions of Microsoft® Windows® this is a 64-bit value.
pdwRefData
[in] Pointer to a DWORD which will return the reference data. Note: On 64-bit versions of Windows, pointers are 64-bit values.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | comctl32.dll version 6.0 or later
Custom Implementation | No
Header | commctrl.h
Import library | comctl32.lib
Minimum operating systems | Whistler

See Also

DefSubclassProc, SetWindowSubclass, RemoveWindowSubclass


InetIsOffline

Determines whether or not the system is connected to the Internet.

BOOL InetIsOffline(
  DWORD dwFlags,
);

Parameters

dwFlags
Input flags for the function. This must be set to zero.

Return Value

Returns TRUE if the local system in not currently connected to the Internet. Returns FALSE if the local system is connected to the Internet or if no attempt has yet been made to connect to the Internet.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


MIMEAssociationDialog

Runs the unregistered MIME content type dialog box.

HRESULT MIMEAssociationDialog(
  HWND     hwndParent,
  DWORD    dwInFlags,
  LPCSTR   pcszFile,
  LPCSTR   pcszMIMEContentType,
  LPSTR    pszAppBuf,
  UINT     ucAppBufLen,
);

Parameters

hwndParent
Handle to the parent window of any posted child windows.
dwInFlags
Bit flag value that specifies if an association is to be registered. The bit flag is the value MIMEASSOCDLG_FL_REGISTER_ASSOC (0x0001). If this bit is set, the selected application is registered as the handler for the given MIME type. If this bit is clear, no association is registered.

An application is registered only if this flag is set and the user indicates that a persistent association is to be made.

Registration is impossible if the string at pcszFile does not contain an extension.

pcszFile
Address of a null-terminated string that contains the name of the target file. This file must conform to the content type described by the pcszMIMEContentType parameter.
pcszMIMEContentType
Address of a null-terminated string that contains the unregistered content type.
pszAppBuf
Address of a buffer that receives the path of the application specified by the user.
ucAppBufLen
Size of pszAppBuf, in characters.

Return Value

Returns one of the following values:

Returns S_OK if the content type was successfully associated with the extension. In this case, the extension is associated as the default for the content type, and pszAppBuf points to the string that contains the path of the specified application. The function returns S_FALSE if nothing was registered. Otherwise, the return value will be one of the following:

E_ABORT | The user canceled the operation.
E_FLAGS | The flag combination passed in dwInFlags is invalid.
E_OUTOFMEMORY | There was insufficient memory available to complete the operation.
E_POINTER | One of the input pointers is invalid.

Remarks

This function does not validate the syntax of the input content type string at pcszMIMEContentType. A successful return value does not indicate that the specified MIME content type is valid.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


RegisterDialogClasses

Registers any nonstandard window classes required by a screen saver's configuration dialog box.

BOOL RegisterDialogClasses(
    HANDLE hInst
);

Parameters

hInst
Identifier of an instance of the module registering the window classes.

Return Values

Returns nonzero if successful, or zero otherwise.

To retrieve extended error information, call GetLastError.

Remarks

The RegisterDialogClasses function should not be exported. It is called by routines defined in the Scrnsave.lib file.

If a screen saver does not register any special window classes for the configuration dialog box, the RegisterDialogClasses function must return TRUE.

See Also

ScreenSaverConfigureDialog

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in scrnsave.h.
Import Library: scrnsave.lib.


RemoveWindowSubclass Function

Removes a subclass callback from a window.

Syntax

BOOL RemoveWindowSubclass(
    HWND hWnd,
    SUBCLASSPROC pfnSubclass,
    UINT_PTR uIdSubclass
);

Parameters

hWnd
[in] Handle of window being subclassed.
pfnSubclass
[in] Pointer to a window procedure. This pointer and the subclass identifier (ID) uniquely identify this subclass callback.
uIdSubclass
[in] ULONG_PTR subclass ID. This ID and the callback pointer uniquely identify this subclass callback. Note: On 64-bit versions of Microsoft® Windows® this is a 64-bit value.

Return Value

TRUE | The subclass callback was successfully removed.
FALSE | The subclass callback was not removed.

Remarks

Subclass callbacks are identified by their combination of the callback address and the caller-defined subclass ID.

Function Information

Stock Implementation | comctl32.dll version 6.0 or later
Custom Implementation | No
Header | commctrl.h
Import library | comctl32.lib
Minimum operating systems | Whistler

See Also

GetWindowSubclass, DefSubclassProc, SetWindowSubclass


ScreenSaverConfigureDialog

Receives messages sent to a screen saver's configuration dialog box. A screen saver that allows user configuration must define this function.

BOOL ScreenSaverConfigureDialog(
    HWND hDlg,
    UINT message,
    WPARAM wParam,
    LPARAM lParam
);

Parameters

hDlg
Identifier of the configuration dialog box.
message
Message that was sent to the screen saver's configuration dialog box.
wParam
Additional message-specific information.
lParam
Additional message-specific information.

Return Values

If the function successfully processes the message, it should return TRUE. If not, it should return FALSE, except in response to a WM_INITDIALOG message. In response to a WM_INITDIALOG message, ScreenSaverConfigureDialog should return FALSE if it calls the SetFocus function to set the keyboard focus to one of the controls in the dialog box. Otherwise, the function should return TRUE, in which case the system sets the keyboard focus to the first control in the dialog box that can be given the focus.

Remarks

The dialog box template for the configuration dialog box must have the DLG_SCRNSAVECONFIGURE identifier.

The dialog box procedure is used only if the application specifies the default window class (WC_DIALOG) for the dialog box. The application uses the default class if no explicit class is given in the dialog box template. Although the dialog box procedure is similar to a window procedure, it must not call the DefWindowProc function to process unwanted messages. Unwanted messages are processed internally by the default dialog box procedure.

The ScreenSaverConfigureDialog function must be exported by including it in the EXPORTS statement in the application's module-definition (.def) file.

See Also

RegisterDialogClasses

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in scrnsave.h.
Import Library: scrnsave.lib.


ScreenSaverProc

Receives messages sent to the specified screen saver window.

LONG ScreenSaverProc(
    HWND hWnd,
    UINT message,
    WPARAM wParam,
    LPARAM lParam
);

Parameters

hWnd
Identifier of the window.
message
Message sent to the screen saver window.
wParam
Additional message-specific information.
lParam
Additional message-specific information.

Return Value

The return value is the result of the message processing and depends on the message sent.

Remarks

A screen saver's ScreenSaverProc window procedure should use the DefScreenSaverProc function instead of the DefWindowProc function to provide default message processing. The DefScreenSaverProc function passes any messages that do not affect screen saver operations to DefWindowProc.

The ScreenSaverProc function must be exported by including it in the EXPORTS statement in the application's module-definition (.def) file.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in scrnsave.h.
Import Library: scrnsave.lib.


SetMenuContextHelpId

Associates a Help context identifier with a menu.

BOOL SetMenuContextHelpId(
    HMENU hmenu,
    DWORD dwContextHelpId
);

Parameters

hmenu
Handle to the menu with which to associate the Help context identifier.
dwContextHelpId
Help context identifier.

Return Values

Returns nonzero if successful, or zero otherwise.

To retrieve extended error information, call GetLastError.

Remarks

All items in the menu share this identifier. Help context identifiers can't be attached to individual menu items.

See Also

GetMenuContextHelpId

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.
Import Library: user32.lib.


SetWindowContextHelpId

Associates a Help context identifier with the specified window.

BOOL SetWindowContextHelpId(
    HWND hwnd,
    DWORD dwContextHelpId
);

Parameters

hwnd
Handle to the window with which to associate the Help context identifier.
dwContextHelpId
Help context identifier.

Return Values

Returns nonzero if successful, or zero otherwise.

To retrieve extended error information, call GetLastError.

Remarks

If a child window does not have a Help context identifier, it inherits the identifier of its parent window. Likewise, if an owned window does not have a Help context identifier, it inherits the identifier of its owner window. This inheritance of Help context identifiers allows an application to set just one identifier for a dialog box and all of its controls.

See Also

GetWindowContextHelpId

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.
Import Library: user32.lib.


SetWindowSubclass Function

Installs and/or updates a window subclass callback.

Syntax

BOOL SetWindowSubclass(
    HWND hWnd,
    SUBCLASSPROC pfnSubclass,
    UINT_PTR uIdSubclass,
    DWORD dwRefData
);

Parameters

hWnd
[in] Handle of window being subclassed.
pfnSubclass
[in] Pointer to a window procedure. This pointer and the subclass identifier (ID) uniquely identify this subclass callback.
uIdSubclass
[in] ULONG_PTR subclass ID. This ID and the callback pointer uniquely identify this subclass callback. Note: On 64-bit versions of Microsoft® Windows® this is a 64-bit value.
dwRefData
[in] DWORD reference data. This value is defined by the caller. This subclass stores one reference data item for each subclass callback.

Return Value

TRUE | The subclass callback was successfully installed.
FALSE | The subclass callback was not installed.

Remarks

Subclass callbacks are identified by the combination of the callback address and the caller-defined subclass ID. If the callback address and ID pair have not yet been installed, then this function installs the subclass. If the pair has already been installed, then this function just updates the reference data.

Function Information

Stock Implementation | comctl32.dll version 6.0 or later
Custom Implementation | No
Header | commctrl.h
Import library | comctl32.lib
Minimum operating systems | Whistler

See Also

GetWindowSubclass, DefSubclassProc, RemoveWindowSubclass


SHAddToRecentDocs

Adds a document to the Shell's list of recently used documents or clears all documents from the list.

VOID SHAddToRecentDocs(
    UINT uFlags,
    LPCVOID pv
);

Parameters

uFlags
[in] Flag that indicates the meaning of the pv parameter. This flag can be one of the following values:
SHARD_PATH | The pv parameter points to a NULL-terminated string with the path and file name of the object.
SHARD_PIDL | The pv parameter points to an an ITEMIDLIST structure (PIDL) that identifies the document's file object. PIDLs that identify nonfile objects are not allowed.
pv
[in] A pointer to either a NULL terminated string with the path and file name of the document, or a PIDL that identifies the document's file object. Set this parameter to NULL to clear all documents from the list.

Remarks

In addition to updating its list of recent documents, the Shell adds a shortcut to the user's Recent directory (CSIDL_RECENT) and the Start menu's Documents submenu.

See Also

SHGetFolderLocation, SHGetFolderPath

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHAppBarMessage

Sends an appbar message to the system.

UINT_PTR SHAppBarMessage(
    DWORD dwMessage,
    PAPPBARDATA pData
);

Parameters

dwMessage
Appbar message value to send. This parameter can be one of the following values:
ABM_ACTIVATE | Notifies the system that an appbar has been activated.
ABM_GETAUTOHIDEBAR | Retrieves the handle to the autohide appbar associated with a particular edge of the screen.
ABM_GETSTATE | Retrieves the autohide and always-on-top states of the Windows taskbar.
ABM_GETTASKBARPOS | Retrieves the bounding rectangle of the Windows taskbar.
ABM_NEW | Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar.
ABM_QUERYPOS | Requests a size and screen position for an appbar.
ABM_REMOVE | Unregisters an appbar, removing the bar from the system's internal list.
ABM_SETAUTOHIDEBAR | Registers or unregisters an autohide appbar for an edge of the screen.
ABM_SETPOS | Sets the size and screen position of an appbar.
ABM_SETSTATE | Sets the state of the appbar's autohide and always-on-top attributes.
ABM_WINDOWPOSCHANGED | Notifies the system when an appbar's position has changed.
pData
Address of an APPBARDATA structure. The content of the structure depends on the value set in the dwMessage parameter.

Return Values

Returns a message-dependent value. For more information, see the Microsoft Platform SDK documentation for the appbar message sent.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHBindToParent

This function takes the fully-qualified PIDL of a namespace object, and returns a specified interface pointer on the parent object.

HRESULT SHBindToParent(
  LPCITEMIDLIST pidl,
  REFIID riid,
  VOID **ppv,
  LPCITEMIDLIST *ppidlLast
);

Parameters

pidl
[in] The item's PIDL.
riid
[in] The REFIID of one of the interfaces exposed by the item's parent object.
ppv
[out] A pointer to the interface specified by riid. You must release the object when you are finished.
ppidlLast
[out] The item's PIDL relative to the parent folder. This PIDL can be used with many of the methods supported by the parent folder's interfaces. If you set ppidlLast to NULL, the PIDL will not be returned.

Return Values

Returns S_OK if successful, an OLE-defined error value otherwise.

Example

The following code fragment uses SHBindToParent to retrieve the display name from an item's PIDL. The StrRetToBuf function is used to convert the STRRET structure returned by IShellFolder::GetDisplayNameOf into a string.

IShellFolder *psfParent; //A pointer to the parent folder object's IShellFolder interface
LPITEMIDLIST pidlItem = NULL; //the item's PIDL
LPITEMIDLIST pidlRelative = NULL; //the item's PIDL relative to the parent folder
STRRET str; //the display name's STRRET structure
TCHAR szDisplayName[MAX_PATH]; //the display name's string

HRESULT hres = SHBindToParent(pidlItem, IID_IShellFolder, &psfParent, &pidlRelative);
if(SUCCEEDED(hres))
{
    psfParent->GetDisplayNameOf(pidlRelative, SHGDN_NORMAL, &str);
    psfParent->Release();
    StrRetToBuf(&str, pidlItem, szDisplayName, ARRAYSIZE(szDisplayName));
}

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Not available.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHBrowseForFolder

Displays a dialog box that enables the user to select a Shell folder.

LPITEMIDLIST SHBrowseForFolder(
    LPBROWSEINFO lpbi
);

Parameters

lpbi
[in] Pointer to a BROWSEINFO structure that contains information used to display the dialog box.

Return Values

Returns a pointer to an ITEMIDLIST structure (PIDL) that specifies the location of the selected folder relative to the root of the namespace. If the user chooses the Cancel button in the dialog box, the return value is NULL.

Remarks

You must initialize COM using CoInitializeEx with the COINIT_APARTMENTTHREADED flag on dwCoInit set prior to calling SHBrowseForFolder. You can also use CoInitialize or OLEInitialize, which always use apartment threading.

The calling application is responsible for freeing the returned PIDL with the Shell allocator's IMalloc::Free method. To retrieve a handle to the Shell allocator's IMalloc interface, call SHGetMalloc. See The Shell Namespace for further discussion of the Shell allocator and PIDLs.

There are two styles of dialog box available. The older style is displayed by default, and is not resizable. To specify a new-style dialog box, set the BIF_USENEWUI flag in the ulFlags member of the BROWSEINFO structure. It has a number of additional features, including: drag and drop capability within the dialog box, reordering, shortcut menus, new folders, delete, and other shortcut menu commands. Initially, it is larger than the old dialog box, but can be resized by the user.

If you implement a callback function, you will receive a handle to the dialog box. One use of this window handle is to modify the layout or contents of the dialog box. Because it is not resizable, modifying the old-style dialog box is relatively straightforward. Modifying the new-style dialog box is much more difficult, and not recommended. Not only does it have a different size and layout than the old style, but its dimensions and the positions of its controls change every time it is resized by the user.

If the BIF_RETURNONLYFSDIRS flag is set in the ulFlags member of the BROWSEINFO structure, the OK button will remain enabled for "\\server" items, as well as "\\server\share" and directory items. However, if the user selects a "\\server" item, passing the PIDL returned by the dialog box to SHGetPathFromIDList will fail.

See Also

Open and Save Common Dialog Boxes

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHChangeNotify

Notifies the system of an event that an application has performed. An application should use this function if it performs an action that may affect the Shell.

VOID SHChangeNotify(
    LONG wEventId,
    UINT uFlags,
    LPCVOID dwItem1,
    LPCVOID dwItem2
);

Parameters

wEventId
Describes the event that has occurred. Typically, only one event is specified at a time. If more than one event is specified, the values contained in the dwItem1 and dwItem2 parameters must be the same, respectively, for all specified events. This parameter can be one or more of the following values:
SHCNE_ALLEVENTS | All events have occurred.
SHCNE_ASSOCCHANGED | A file type association has changed. SHCNF_IDLIST must be specified in the uFlags parameter. dwItem1 and dwItem2 are not used and must be NULL.
SHCNE_ATTRIBUTES | The attributes of an item or folder have changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item or folder that has changed. dwItem2 is not used and should be NULL.
SHCNE_CREATE | A nonfolder item has been created. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item that was created. dwItem2 is not used and should be NULL.
SHCNE_DELETE | A nonfolder item has been deleted. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item that was deleted. dwItem2 is not used and should be NULL.
SHCNE_DRIVEADD | A drive has been added. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that was added. dwItem2 is not used and should be NULL.
SHCNE_DRIVEADDGUI | A drive has been added and the Shell should create a new window for the drive. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that was added. dwItem2 is not used and should be NULL.
SHCNE_DRIVEREMOVED | A drive has been removed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that was removed. dwItem2 is not used and should be NULL.
SHCNE_EXTENDED_EVENT | Not currently used.
SHCNE_FREESPACE | The amount of free space on a drive has changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive on which the free space changed. dwItem2 is not used and should be NULL.
SHCNE_MEDIAINSERTED | Storage media has been inserted into a drive. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive that contains the new media. dwItem2 is not used and should be NULL.
SHCNE_MEDIAREMOVED | Storage media has been removed from a drive. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the root of the drive from which the media was removed. dwItem2 is not used and should be NULL.
SHCNE_MKDIR | A folder has been created. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that was created. dwItem2 is not used and should be NULL.
SHCNE_NETSHARE | A folder on the local computer is being shared via the network. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that is being shared. dwItem2 is not used and should be NULL.
SHCNE_NETUNSHARE | A folder on the local computer is no longer being shared via the network. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that is no longer being shared. dwItem2 is not used and should be NULL.
SHCNE_RENAMEFOLDER | The name of a folder has changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the previous PIDL or name of the folder. dwItem2 contains the new PIDL or name of the folder.
SHCNE_RENAMEITEM | The name of a nonfolder item has changed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the previous PIDL or name of the item. dwItem2 contains the new PIDL or name of the item.
SHCNE_RMDIR | A folder has been removed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that was removed. dwItem2 is not used and should be NULL.
SHCNE_SERVERDISCONNECT | The computer has disconnected from a server. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the server from which the computer was disconnected. dwItem2 is not used and should be NULL.
SHCNE_UPDATEDIR | The contents of an existing folder have changed, but the folder still exists and has not been renamed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the folder that has changed. dwItem2 is not used and should be NULL. If a folder has been created, deleted, or renamed, use SHCNE_MKDIR, SHCNE_RMDIR, or SHCNE_RENAMEFOLDER, respectively, instead.
SHCNE_UPDATEIMAGE | An image in the system image list has changed. SHCNF_DWORD must be specified in uFlags. dwItem1 contains the index in the system image list that has changed. dwItem2 is not used and should be NULL.
SHCNE_UPDATEITEM | An existing nonfolder item has changed, but the item still exists and has not been renamed. SHCNF_IDLIST or SHCNF_PATH must be specified in uFlags. dwItem1 contains the item that has changed. dwItem2 is not used and should be NULL. If a nonfolder item has been created, deleted, or renamed, use SHCNE_CREATE, SHCNE_DELETE, or SHCNE_RENAMEITEM, respectively, instead.

The following values specify combinations of other events:
SHCNE_DISKEVENTS | Specifies a combination of all of the disk event identifiers.
SHCNE_GLOBALEVENT | Specifies a combination of all of the global event identifiers.

The following value modifies other event values and cannot be used alone:
SHCNE_INTERRUPT The specified event occurred as a result of a system interrupt.

uFlags
Flags that indicate the meaning of the dwItem1 and dwItem2 parameters. The uFlags parameter must be one of the following values:
SHCNF_DWORD | The dwItem1 and dwItem2 parameters are DWORD values.
SHCNF_IDLIST | dwItem1 and dwItem2 are the addresses of ITEMIDLIST structures that represent the item(s) affected by the change. Each ITEMIDLIST must be relative to the desktop folder.
SHCNF_PATH | dwItem1 and dwItem2 are the addresses of NULL-terminated strings that contain the full path names of the items affected by the change.
SHCNF_PRINTER | dwItem1 and dwItem2 are the addresses of NULL-terminated strings that represent the friendly names of the printer(s) affected by the change.

The following flags modify other data-type flags and cannot be used by themselves:
SHCNF_FLUSH | The function should not return until the notification has been delivered to all affected components.
SHCNF_FLUSHNOWAIT | The function should begin delivering notifications to all affected components but should return as soon as the notification process has begun.

dwItem1
First event-dependent value.
dwItem2
Second event-dependent value.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHCreateDirectoryEx

Creates a new file system folder.

int SHCreateDirectoryEx(
    HWND hwnd,
    LPCSTR pszPath,
    SECURITY_ATTRIBUTES *psa
);

Parameters

hwnd
[in] Handle to a parent window. This parameter can be set to NULL if no user interface will be displayed.
pszPath
[in] Pointer to a string with the fully qualified path of the directory.
psa
[in] Pointer to a SECURITY_ATTRIBUTES structure with the directory's security attribute. Set this parameter to NULL if no security attributes need to be set.

Return Values

Returns ERROR_SUCCESS if successful. If the operation fails, one of the following error codes can be returned.

Error code | Description
ERROR_BAD_PATHNAME | The pszPath parameter was set to a relative path.
ERROR_FILENAME_EXCED_RANGE | The path pointed to by pszPath is too long.
ERROR_FILE_EXISTS | The directory exists.
ERROR_ALREADY_EXISTS | The directory exists.
ERROR_CANCELLED | The user canceled the operation.

Remarks

This function creates a file system folder whose fully qualified path is given by pszPath. If one or more of the intermediate folders do not exist, they will be created as well. SHCreateDirectoryEx also verifies that the files will be visible. If not:

  • If hwnd is set to a valid window handle, a message box is displayed warning the user that he or she might not be able to access the files. If the user chooses not to proceed, the function returns ERROR_CANCELLED.
  • If hwnd is set to NULL, no user interface is displayed and the function returns ERROR_CANCELLED.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHCreateProcessAsUserW

Creates a new user-mode process and its primary thread to run a specified executable file.

BOOL SHCreateProcessAsUserW(
    PSHCREATEPROCESSINFOW pscpi
);

Parameters

pscpi
[in] Pointer to an SHCREATEPROCESSINFOW structure with information on how to create the process.

Return Values

Returns TRUE if successful, or FALSE if not. To retrieve extended error information, call GetLastError.

Remarks

This function is similar to ShellExecuteEx with runas as the verb. However, SHCreateProcessAsUserW creates a process that runs in the security context of the user represented by the hUserToken member of the structure pointed to by pscpi. The structure's lpProcessInformation member can be used to return a PROCESS_INFORMATION structure with information on the new process.

The runas verb must be supported by the executable file's file class. The .exe file class supports runas. Use the AssocQueryString function to check whether or not runas is supported by other file classes. The following code fragment illustrates the syntax:

AssocQueryString(0, ASSOCSTR_COMMAND, pszFile, TEXT("runas"), NULL, &cchVerb)

For a discussion of how to use the Shell to launch applications, see Launching Applications.

See Also

CreateProcess, CreateProcessAsUser

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


Shell_NotifyIcon

Sends a message to the taskbar's status area.

BOOL Shell_NotifyIcon(
    DWORD dwMessage,
    PNOTIFYICONDATA lpdata
);

Parameters

dwMessage
[in] Variable of type DWORD that specifies the action to be taken. It can have one of the following values:
NIM_ADD
Adds an icon to the status area. The hWnd and uID members of the NOTIFYICONDATA structure pointed to by pnid will be used to identify the icon in future calls to Shell_NotifyIcon.
NIM_DELETE
Deletes an icon from the status area. Use the hWnd and uID members of the NOTIFYICONDATA structure pointed to by pnid to identify the icon to be deleted.
NIM_MODIFY
Modifies an icon in the status area. Use the hWnd and uID members of the NOTIFYICONDATA structure pointed to by pnid to identify the icon to be modified.
NIM_SETFOCUS
Version 5.0. Returns focus to the taskbar notification area. Taskbar icons should use this message when they have completed their user interface operation. For example, if the taskbar icon displays a shortcut menu, but the user presses ESCAPE to cancel it, use NIM_SETFOCUS to return focus to the taskbar notification area.
NIM_SETVERSION
Version 5.0. Instructs the taskbar to behave according to the version number specified in the uVersion member of the structure pointed to by pnid. This message allows you to specify whether you want the version 5.0 behavior found on Microsoft® Windows® 2000 systems, or that found with earlier Shell versions. The default value for uVersion is zero, indicating that the original Windows 95 notify icon behavior should be used. For details, see the Remarks section.
pnid
[in] Address of a NOTIFYICONDATA structure. The content of the structure depends on the value of dwMessage.

Return Values

Returns TRUE if successful, or FALSE otherwise. If dwMessage is set to NIM_SETVERSION, the function returns TRUE if the version was successfully changed, or FALSE if the requested version is not supported.

Remarks

The taskbar notification area is sometimes erroneously called the "tray."

Version 5.0 of the Shell, found on Windows 2000, handles Shell_NotifyIcon mouse and keyboard events differently than earlier Shell versions, found on Windows NT® 4.0, Windows 95, and Windows 98. The differences are:

  • If a user selects a notify icon's shortcut menu with the keyboard, the version 5.0 Shell sends the associated application a WM_CONTEXTMENU message. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
  • If a user selects a notify icon with the keyboard and activates it with the space bar or ENTER key, the version 5.0 Shell sends the associated application an NIN_KEYSELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
  • If a user selects a notify icon with the mouse and activates it with the ENTER key, the version 5.0 Shell sends the associated application an NIN_SELECT notification. Earlier versions send WM_RBUTTONDOWN and WM_RBUTTONUP messages.
  • If a user passes the mouse pointer over an icon with which a balloon ToolTip is associated, the version 5.0 Shell sends the following messages:
    • NIN_BALLOONSHOW - Sent when the balloon is shown (balloons are queued).
    • NIN_BALLOONHIDE - Sent when the balloon disappears—when the icon is deleted, for example. This message is not sent if the balloon is dismissed because of a timeout or mouse click by the user.
    • NIN_BALLOONTIMEOUT - Sent when the balloon is dismissed because of a timeout.
    • NIN_BALLOONUSERCLICK - Sent when the balloon is dismissed because the user clicked the mouse.

You can select which way the Shell should behave by calling Shell_NotifyIcon with dwMessage set to NIM_SETVERSION. Set the uVersion member of the NOTIFYICONDATA structure to indicate whether you want version 5.0 or pre-version 5.0 behavior.

Note The messages discussed above are not conventional Windows messages. They are sent as the lParam value of the application-defined message that is specified when the icon is added with NIM_ADD.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


ShellAbout

Displays a ShellAbout dialog box.

int ShellAbout (
   HWND hWnd,
   LPCTSTR szApp,
   LPCTSTR szOtherStuff,
   HICON hIcon
);

Parameters

hWnd
Window handle to a parent window. This parameter can be NULL.
szApp
Displays text in the title bar of the ShellAbout dialog box and on the first line of the dialog box after the text "Microsoft". If the text contains a separator (#) dividing it into two parts, the function displays the first part in the title bar and the second part on the first line after the text "Microsoft".
szOtherStuff
Displays text in the dialog box after the version and copyright information.
hIcon
Icon that the function displays in the dialog box. If this parameter is NULL, the function displays the Microsoft® Windows® or Windows NT® icon.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

Note that the ShellAbout function dialog box uses text and a default icon that are specific to either Windows or Windows NT.

An example of a ShellAbout dialog box can be seen by selecting the About Program Manager command in Program Manager.

Requirements

Windows NT/2000: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


ShellExecute

Performs an operation on a specified file.

HINSTANCE ShellExecute(
    HWND hwnd,
    LPCTSTR lpOperation,
    LPCTSTR lpFile,
    LPCTSTR lpParameters,
    LPCTSTR lpDirectory,
    INT nShowCmd
);

Parameters

hwnd
Handle to a parent window. This window receives any message boxes that an application produces, such as error reporting.
lpVerb
A string, referred to as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. For more information about verbs and their availability, see Object Verbs. See Extending Shortcut Menus for further discussion of shortcut menus. The following verbs are commonly used:
Verb | Description
edit | Launches an editor and opens the document for editing. If lpFile is not a document file, the function will fail.
explore | Explores the folder specified by lpFile.
find | Initiates a search starting from the specified directory.
open | Opens the file specified by the lpFile parameter. The file can be an executable file, a document file, or a folder.
print | Prints the document file specified by lpFile. If lpFile is not a document file, the function will fail.

If you set this parameter to NULL:

  • For systems prior to Microsoft® Windows® 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used.
  • For Windows 2000 and later systems, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry.
lpFile
Address of a null-terminated string that specifies the file or object on which to execute the specified verb. To specify a Shell namespace object, pass the fully-qualified parse name. Note that not all verbs are supported on all objects. For example, not all document types support the "print" verb.
lpParameters
If the lpFile parameter specifies an executable file, lpParameters is an address to a null-terminated string that specifies the parameters to be passed to the application.The format of this string is determined by the verb that is to be invoked. If lpFile specifies a document file, lpParameters should be NULL.
lpDirectory
Address of a null-terminated string that specifies the default directory.
nShowCmd
Flags that specify how an application is to be displayed when it is opened. If lpFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it.
SW_HIDE | Hides the window and activates another window.
SW_MAXIMIZE | Maximizes the specified window.
SW_MINIMIZE | Minimizes the specified window and activates the next top-level window in the z-order.
SW_RESTORE | Activates and displays the window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when restoring a minimized window.
SW_SHOW | Activates the window and displays it in its current size and position.
SW_SHOWDEFAULT | Sets the show state based on the SW_ flag specified in the STARTUPINFO structure passed to the CreateProcess function by the program that started the application. An application should call ShowWindow with this flag to set the initial show state of its main window.
SW_SHOWMAXIMIZED | Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED | Activates the window and displays it as a minimized window.
SW_SHOWMINNOACTIVE | Displays the window as a minimized window. The active window remains active.
SW_SHOWNA | Displays the window in its current state. The active window remains active.
SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The active window remains active.
SW_SHOWNORMAL | Activates and displays a window. If the window is minimized or maximized, Windows restores it to its original size and position. An application should specify this flag when displaying the window for the first time.

Return Values

Returns a value greater than 32 if successful, or an error value that is less than or equal to 32 otherwise. The following table lists the error values. The return value is cast as an HINSTANCE for backward compatibility with 16-bit Microsoft® Windows® applications. It is not a true HINSTANCE, however. The only thing that can be done with the returned HINSTANCE is to cast it to an integer and compare it with the value 32 or one of the error codes below.

0 | The operating system is out of memory or resources.
ERROR_FILE_NOT_FOUND | The specified file was not found.
ERROR_PATH_NOT_FOUND | The specified path was not found.
ERROR_BAD_FORMAT | The .exe file is invalid (non-Win32® .exe or error in .exe image).
SE_ERR_ACCESSDENIED | The operating system denied access to the specified file.
SE_ERR_ASSOCINCOMPLETE | The file name association is incomplete or invalid.
SE_ERR_DDEBUSY | The DDE transaction could not be completed because other DDE transactions were being processed.
SE_ERR_DDEFAIL | The DDE transaction failed.
SE_ERR_DDETIMEOUT | The DDE transaction could not be completed because the request timed out.
SE_ERR_DLLNOTFOUND | The specified dynamic-link library was not found.
SE_ERR_FNF | The specified file was not found.
SE_ERR_NOASSOC | There is no application associated with the given file name extension. This error will also be returned if you attempt to print a file that is not printable.
SE_ERR_OOM | There was not enough memory to complete the operation.
SE_ERR_PNF | The specified path was not found.
SE_ERR_SHARE | A sharing violation occurred.

Remarks

This method allows you to execute any commands in a folder's shortcut menu or stored in the registry.

To open a folder, use either of the following calls:

ShellExecute(handle, NULL, path_to_folder, NULL, NULL, SW_SHOWNORMAL);

or

ShellExecute(handle, "open", path_to_folder, NULL, NULL, SW_SHOWNORMAL);

To explore a folder, use:

ShellExecute(handle, "explore", path_to_folder, NULL, NULL, SW_SHOWNORMAL);

To launch the Shell's Find utility for a directory, use:

ShellExecute(handle, "find", path_to_folder, NULL, NULL, 0);

If lpOperation is NULL, the function opens the file specified by lpFile. If lpOperation is "open" or "explore", the function will attempt to open or explore the folder.

To obtain information about the application that is launched as a result of calling ShellExecute, use ShellExecuteEx.

See Also

IShellExecuteHook

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


ShellExecuteEx

Performs an action on a file.

BOOL ShellExecuteEx(
    LPSHELLEXECUTEINFO lpExecInfo
);

Parameters

lpExecInfo
Address of a SHELLEXECUTEINFO structure that contains and receives information about the application being executed.

Return Values

Returns TRUE if successful, or FALSE otherwise. Call GetLastError for error information.

Remarks

With multiple monitors, if you specify an hwnd and set the lpVerb member of lpExecInfo to "Properties" , any windows created by ShellExecuteEx may not appear in the correct position.

If the function succeeds, it sets the hInstApp member of the SHELLEXECUTEINFO structure to a value greater than 32. If the function fails, hInstApp is set to the SE_ERR_XXX error value that best indicates the cause of the failure. Although hInstApp is declared as an HINSTANCE for compatibility with 16-bit Microsoft Windows applications, it is not a true HINSTANCE. It can only be cast to an integer and compared to either 32 or the SE_ERR_XXX error codes.

Note: the SE_ERR_XXX error values are provided for compatibility with ShellExecute. To retrieve more accurate error information, use GetLastError. It may return one of the following values:

ERROR_FILE_NOT_FOUND | The specified file was not found.
ERROR_PATH_NOT_FOUND | The specified path was not found.
ERROR_DDE_FAIL | The DDE transaction failed.
ERROR_NO_ASSOCIATION | There is no application associated with the given file name extension.
ERROR_ACCESS_DENIED | Access to the specified file is denied.
ERROR_DLL_NOT_FOUND | One of the library files necessary to run the application can't be found.
ERROR_CANCELLED | The function prompted the user for additional information, but the user canceled the request.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to perform the specified action.
ERROR_SHARING_VIOLATION | A sharing violation occurred.

See Also

IShellExecuteHook

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHEmptyRecycleBin

Empties the Recycle Bin on the specified drive.

HRESULT SHEmptyRecycleBin(
    HWND hwnd,
    LPCTSTR pszRootPath,
    DWORD dwFlags
);

Parameters

hwnd
Handle to the parent window of any dialog boxes that might be displayed during the operation. This parameter can be NULL.
pszRootPath
Address of a NULL-terminated string that contains the path of the root drive on which the Recycle Bin is located. This parameter can contain the address of a string formatted with the drive, folder, and subfolder names (c:\windows\system . . .). It can also contain an empty string or NULL. If this value is an empty string or NULL, all Recycle Bins on all drives will be emptied.
dwFlags
One or more of the following values:
SHERB_NOCONFIRMATION | No dialog box confirming the deletion of the objects will be displayed.
SHERB_NOPROGRESSUI | No dialog box indicating the progress will be displayed.
SHERB_NOSOUND | No sound will be played when the operation is complete.

Return Values

Returns S_OK if successful, or an OLE-defined error value otherwise.

See Also

SHQueryRecycleBin

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHFileOperation

Copies, moves, renames, or deletes a file system object.

int SHFileOperation(
    LPSHFILEOPSTRUCT lpFileOp
);

Parameters

lpFileOp
[in] Address of an SHFILEOPSTRUCT structure that contains information this function needs to carry out the specified operation.

Return Values

Returns zero if successful, or nonzero otherwise.

Remarks

You should use fully-qualified pathnames with this function. Using it with relative path-names is not thread-safe.

With two exceptions, you cannot use SHFileOperation to move special folders from a local drive to a remote computer by specifying a network path. The exceptions are the MyDocs and MyPics folders (CSIDL_PERSONAL and CSIDL_MYPICTURES, respectively).

When used to delete a file, SHFileOperation will attempt to place the deleted file in the Recycle Bin. If you wish to delete a file and guarantee that it will not be placed in the Recycle Bin, use DeleteFile.

If a copy callback handler is exposed and registered, SHFileOperation will call it unless you set a flag such as FOF_NOCONFIRMATION in the fFlags member of the structure pointed to by lpFileOp. See ICopyHook::CopyCallback for details on implementing copy callback handlers.

File deletion is recursive unless you set the FOF_NORECURSION flag in lpFileOp.

With Microsoft® Windows 2000® and later, it is possible to connect an HTML file with a folder containing related files such as GIF images or style sheets. If file connection is enabled, when you move or copy the HTML file, all of the files in the folder will be moved or copied as well. Conversely, if you move the folder with the related files, the HTML file is also moved.

The HTML file must have a .htm or .html extension. You create the connection to the related files by placing them in a subfolder of the folder containing the HTML file. The folder must have the name of the HTML file followed by " files". For example, if the HTML file is MyFile.htm, the folder should be named "MyFile files". Any files you place in the "MyFile files" subfolder will be connected to MyFile.htm.

File connection is enabled by default. It can be disabled by adding a REG_DWORD value, NoFileFolderConnection, to the HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer registry key. Setting NoFileFolderConnection to 1 disables file connection. If the value is set to zero or is missing, file connection is enabled.

To move only specified files from a group of connected files, set the FOF_ NO_CONNECTED_ELEMENTS flag in the fFlags member of the structure pointed to by lpFileOp.

Note that the use of a folder with a name like "MyFile files" to define a connection may not be valid for localized versions of Windows NT. The term "files" may need be replaced by the equivalent word in the local language.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHFreeNameMappings

Frees a file name mapping object that was retrieved by the SHFileOperation function.

 VOID SHFreeNameMappings(;
    HANDLE hNameMappings
);

Parameters

hNameMappings
Handle to the file name mapping object to be freed.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHGetDataFromIDList

Retrieves extended property data from a relative identifier list.

HRESULT SHGetDataFromIDList(
    IShellFolder *psf,
    LPCITEMIDLIST pidl,
    int nFormat,
    PVOID pv,
    int cb
);

Parameters

psf
Address of the parent IShellFolder interface. This must be the immediate parent of the ITEMIDLIST structure referenced by the pidl parameter.
pidl
Address of an ITEMIDLIST structure that identifies the object relative to the folder specified in psf.
nFormat
Format in which the data is being requested. This parameter must be set to one of the following values.
SHGDFIL_FINDDATA | Format used for file system objects. The pv parameter is the address of a WIN32_FIND_DATA structure.
SHGDFIL_NETRESOURCE | Format used for network resources. The pv parameter is the address of a NETRESOURCE structure.
SHGDFIL_DESCRIPTIONID | Version 4.71. Format used for network resources. The pv parameter is the address of an SHDESCRIPTIONID structure.
pv
Address of a buffer that receives the requested data. The format of this buffer is determined by nFormat.

If nFormat is SHGDFIL_NETRESOURCE, there are two possible cases. If the buffer is large enough, the net resource's string information (fields for the network name, local name, provider, and comments) will be placed into the buffer. If the buffer is not large enough, only the net resource structure will be placed into the buffer and the string information pointers will be NULL.

cb
Size of the buffer at pv, in bytes.

Return Values

Returns NOERROR if successful, or E_INVALIDARG otherwise.

Remarks

This function extracts only information that is present in the PIDL. Since the content of a PIDL depends on the folder object that created the PIDL, there is no guarantee that all requested information will be available. In addition, the information that is returned reflects the state of the object at the time the PIDL was created. The current state of the object could be different. For example, if you set nFormat to SHGDFIL_FINDDATA, the function might assign meaningful values to only some of the members of the WIN32_FIND_DATA structure. The remaining members will be set to zero. To retrieve complete current information on a file system file or folder, use standard file system functions such as GetFileTime or FindFirstFile.

E_INVALIDARG is returned if the psf, pidl, pv, or cb parameter does not match the nFormat parameter, or if nFormat is not one of the specific SHGDFIL_ values shown above.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetDesktopFolder

Retrieves the IShellFolder interface for the desktop folder, which is the root of the Shell's namespace.

HRESULT SHGetDesktopFolder(
    IShellFolder **ppshf
);

Parameters

ppshf
Address that receives an IShellFolder interface pointer for the desktop folder. The calling application is responsible for eventually freeing the interface by calling its Release method.

Return Values

Returns NOERROR if successful, or an OLE-defined error result otherwise.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetDiskFreeSpace

Retrieves disk space information for a disk volume.

BOOL SHGetDiskFreeSpace(
    LPCTSTR pszVolume,
    ULARGE_INTEGER *pqwFreeCaller,
    ULARGE_INTEGER *pqwTot,
    ULARGE_INTEGER *pqwFree
);

Parameters

pszVolume
A NULL-terminated string that specifies the volume for which size information will be retrieved. This can be a drive letter, UNC name, or the path of a folder. You cannot use NULL to represent the current drive.
pqwFreeCaller
Address of a ULARGE_INTEGER value that receives the number of bytes available to the caller on the volume. If the operating system implements per-user quotas, this value may be less than the total number of free bytes on the volume.
pqwTot
Address of a ULARGE_INTEGER value that receives the total size of the volume, in bytes.
pqwFree
Address of a ULARGE_INTEGER value that receives the number of bytes of free space on the volume.

Return Values

Returns nonzero if successful or zero otherwise.

Remarks

SHGetDiskFreeSpace is nearly identical to the GetDiskFreeSpaceEx API. SHGetDiskFreeSpace will load the proper module, obtain the address of GetDiskFreeSpaceEx and then call it. This approach prevents the caller from having to perform these operations themselves. See the operating system restrictions in the GetDiskFreeSpaceEx reference for more information.

This function is implemented in Shell versions 4.71 and later. In order to maintain backward compatibility with previous Shell versions, this function should not be used explicitly. Instead, the LoadLibrary and GetProcAddress functions should be used to obtain the function address.

See Also

GetDiskFreeSpace

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHGetFileInfo

Retrieves information about an object in the file system, such as a file, a folder, a directory, or a drive root.

DWORD_PTR SHGetFileInfo(
    LPCTSTR pszPath,
    DWORD dwFileAttributes,
    SHFILEINFO *psfi,
    UINT cbFileInfo,
    UINT uFlags
);

Parameters

pszPath
[in] Address of a buffer that contains the path and file name. Both absolute and relative paths are valid.

If the uFlags parameter includes the SHGFI_PIDL flag, this parameter must be the address of an ITEMIDLIST (PIDL) structure that contains the list of item identifiers that uniquely identifies the file within the Shell's namespace. The PIDL must be a fully qualified PIDL. Relative PIDLs are not allowed.

If the uFlags parameter includes the SHGFI_USEFILEATTRIBUTES flag, this parameter does not have to be a valid file name. The function will proceed as if the file exists with the specified name and with the file attributes passed in the dwFileAttributes parameter. This allows you to obtain information about a file type by passing just the extension for pszPath and passing FILE_ATTRIBUTE_NORMAL in dwFileAttributes.

This string can use either short (the 8.3 form) or long file names.

dwFileAttributes
[in] Combination of one or more file attribute flags (FILE_ATTRIBUTE_ values). If uFlags does not include the SHGFI_USEFILEATTRIBUTES flag, this parameter is ignored.
psfi
[out] Address of a SHFILEINFO structure to receive the file information.
cbFileInfo
[in] Size, in bytes, of the SHFILEINFO structure pointed to by the psfi parameter.
uFlags
[in] Flags that specify the file information to retrieve. This parameter can be a combination of the following values:
SHGFI_ATTR_SPECIFIED
Modifies SHGFI_ATTRIBUTES. Indicates that the dwAttributes member of the SHFILEINFO structure at psfi contains the specific attributes that are desired. These attributes will be passed to IShellFolder::GetAttributesOf. If this flag is not specified, 0xFFFFFFFF will be passed to GetAttributesOf, requesting all attributes. This flag cannot be specified with the SHGFI_ICON flag.
SHGFI_ATTRIBUTES
Retrieve the item attributes. The attributes are copied to the dwAttributes member of the structure specified in the psfi parameter. These are the same attributes that are obtained from IShellFolder::GetAttributesOf.
SHGFI_DISPLAYNAME
Retrieve the display name for the file. The name is copied to the szDisplayName member of the structure specified in psfi. The returned display name uses the long file name, if there is one, rather than the 8.3 form of the file name.
SHGFI_EXETYPE
Retrieve the type of the executable file if pszPath identifies an executable file. The information is packed into the return value. This flag cannot be specified with any other flags.
SHGFI_ICON
Retrieve the handle to the icon that represents the file and the index of the icon within the system image list. The handle is copied to the hIcon member of the structure specified by psfi, and the index is copied to the iIcon member.
SHGFI_ICONLOCATION
Retrieve the name of the file and the icon index within that file that contains the icon representing the file specified by pszPath. The name of the file containing the icon is copied to the szDisplayName member of the structure specified by psfi. The icon's index is copied to that structure's iIcon member.
SHGFI_LARGEICON
Modify SHGFI_ICON, causing the function to retrieve the file's large icon. The SHGFI_ICON flag must also be set.
SHGFI_LINKOVERLAY
Modify SHGFI_ICON, causing the function to add the link overlay to the file's icon. The SHGFI_ICON flag must also be set.
SHGFI_OPENICON
Modify SHGFI_ICON, causing the function to retrieve the file's open icon. A container object displays an open icon to indicate that the container is open. The SHGFI_ICON flag must also be set.
SHGFI_PIDL
Indicate that pszPath is the address of an ITEMIDLIST structure rather than a path name.
SHGFI_SELECTED
Modify SHGFI_ICON, causing the function to blend the file's icon with the system highlight color. The SHGFI_ICON flag must also be set.
SHGFI_SHELLICONSIZE
Modify SHGFI_ICON, causing the function to retrieve a Shell-sized icon. If this flag is not specified the function sizes the icon according to the system metric values. The SHGFI_ICON flag must also be set.
SHGFI_SMALLICON
Modify SHGFI_ICON, causing the function to retrieve the file's small icon. The SHGFI_ICON flag must also be set.
SHGFI_SYSICONINDEX
Retrieve the index of a system image list icon. If successful, the index is copied to the iIcon member of psfi. The return value is a handle to the system image list. Only those images whose indices are successfully copied to iIcon are valid. Attempting to access other images in the system image list will result in undefined behavior.
SHGFI_TYPENAME
Retrieve the string that describes the file's type. The string is copied to the szTypeName member of the structure specified in psfi.
SHGFI_USEFILEATTRIBUTES
Indicates that the function should not attempt to access the file specified by pszPath. Rather, it should act as if the file specified by pszPath exists with the file attributes passed in dwFileAttributes. This flag cannot be combined with the SHGFI_ATTRIBUTES, SHGFI_EXETYPE, or SHGFI_PIDL flags.

Return Values

Returns a value whose meaning depends on the uFlags parameter. If uFlags contains the SHGFI_EXETYPE flag, the return value specifies the type of the executable file. It will be one of the following values:

Value | Executable File Type
0 | Nonexecutable file or an error condition
LOWORD = NE or PE and HIWORD = 3.0, 3.5, or 4.0 | Windows application
LOWORD = MZ and HIWORD = 0 | MS-DOS .exe, .com, or .bat file
LOWORD = PE and HIWORD = 0 | Win32 console application

If uFlags contains SHGFI_SYSICONINDEX, the return value is a handle to an image list that contains the large icon images. If SHGFI_SMALLICON is included with SHGFI_SYSICONINDEX, the return value is the handle to an image list that contains the small icon images.

If uFlags does not contain SHGFI_EXETYPE or SHGFI_SYSICONINDEX, the return value is nonzero if successful, or zero otherwise.

Remarks

If SHGetFileInfo returns an icon handle in the hIcon member of the SHFILEINFO structure pointed to by psfi, you are responsible for freeing it with DestroyIcon when you no longer need it.

Note: Once you have a handle to a system image list, you can use the Image List API to manipulate it like any other image list. Because system image lists are created on a per-process basis, you should treat them as read-only objects. Writing to a system image list may overwrite or delete one of the system images, making it unavailable or incorrect for the remainder of the process.

You must initialize COM with CoInitialize or OLEInitialize prior to calling SHGetFileInfo.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHGetFolderLocation

Retrieves the path of a folder as an ITEMIDLIST structure.

HRESULT SHGetFolderLocation(
    HWND hwndOwner,
    int nFolder,
    HANDLE hToken,
    DWORD dwReserved,
    LPITEMIDLIST *ppidl
);

Parameters

hwndOwner
[in] Handle to the owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a UI prompt will appear in this window.
nFolder
[in] A CSIDL value that identifies the folder to be located. The folders associated with the CSIDLs will not necessarily exist on a particular system.
hToken
[in] Token that can be used to represent a particular user. It is usually set to NULL, but it may be needed when there are multiple users for those folders that are treated as belonging to a single user. The caller is responsible for correct impersonation when hToken is non-NULL. It must have appropriate security privileges for the particular user, and the user's registry hive must be currently mounted.
dwReserved
Reserved. Must be set to zero.
ppidl
[out] Address of a pointer to an item identifier list structure specifying the folder's location relative to the root of the namespace (the desktop). The ppidl parameter will be set to NULL on failure. The calling application is responsible for freeing this pointer with the Shell's IMalloc interface (see SHGetMalloc).

Return Values

S_OK | Success.
S_FALSE | The CSIDL in nFolder is valid but the folder does not exist.
E_INVALIDARG | The CSIDL in nFolder is not valid.

A standard OLE-defined error result may also be returned.

Remarks

The SHGetFolderLocation, SHGetFolderPath, SHGetSpecialFolderLocation, and SHGetSpecialFolderPath functions are the preferred ways to obtain handles to folders. Functions such as ExpandEnvironmentStrings that use the environment variable names directly, in the form %VariableName%, may not be reliable.

This function is a superset of SHGetSpecialFolderLocation, included with earlier versions of the Shell.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Windows 95/98/Me: Not available.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetFolderPath

Takes the CSIDL of a folder and returns the pathname.

HRESULT SHGetFolderPath(
    HWND hwndOwner,
    int nFolder,
    HANDLE hToken,
    DWORD dwFlags,
    LPTSTR pszPath
);

Parameters

hwndOwner
Handle to an owner window. This parameter is typically set to NULL. If it is not NULL, and a dial-up connection needs to be made to access the folder, a UI prompt will appear in this window.
nFolder
A CSIDL value that identifies the folder whose path is to be retrieved. Only real folders are valid. If a virtual folder is specified, this function will fail. You can force creation of a folder with SHGetFolderPath by combining the folder's CSIDL with CSIDL_FLAG_CREATE.
hToken

An access token that can be used to represent a particular user. For systems earlier than Microsoft® Windows® 2000, it should be set to NULL. For later systems, hToken is usually set to NULL. However, you may need to assign a value to hToken for those folders that can have multiple users but are treated as belonging to a single user. The most commonly used folder of this type is My Documents.

The caller is responsible for correct impersonation when hToken is non-NULL. It must have appropriate security privileges for the particular user, including TOKEN_QUERY and TOKEN_IMPERSONATE, and the user's registry hive must be currently mounted. See Access Control for further discussion of access control issues.

dwFlags
Flags to specify which path is to be returned. It is used for cases where the folder associated with a CSIDL may be moved or renamed by the user.
Flag | Description
SHGFP_TYPE_CURRENT | Return the folder's current path.
SHGFP_TYPE_DEFAULT | Return the folder's default path.
pszPath
Buffer of length [MAX_PATH] to receive the path. If an error occurs or S_FALSE is returned, this string will be empty.

Return Values

Value | Description
S_OK | Success.
S_FALSE | The CSIDL in nFolder is valid, but the folder does not exist.
E_INVALIDARG | The CSIDL in nFolder is not valid.

A standard OLE-defined error result may also be returned.

Example

The following code fragment uses SHGetFolderPath to find or create a folder and then creates a file in it.

TCHAR szPath[MAX_PATH]
...
if(SUCCEEDED(SHGetFolderPath(NULL, CSIDL_PERSONAL|CSIDL_FLAG_CREATE, NULL, O, szPath))
{
    PathAppend(szPath, TEXT("New Doc.txt"));
    HANDLE hFile = CreateFile(szPath, ...);
}

Remarks

This function is a superset of SHGetSpecialFolderPath, included with earlier versions of the Shell. It is implemented in a redistributable DLL, SHFolder.dll, that also simulates many of the new Shell folders on older platforms such as Windows 95, Windows 98, and Windows NT 4.0. This DLL always calls the current platform's version of this function. If that fails, it will try to simulate the appropriate behavior. Only some CSIDLs are supported, including:

  • CSIDL_ADMINTOOLS
  • CSIDL_COMMON_ADMINTOOLS
  • CSIDL_APPDATA
  • CSIDL_COMMON_APPDATA
  • CSIDL_COMMON_DOCUMENTS
  • CSIDL_COOKIES
  • CSIDL_FLAG_CREATE
  • CSIDL_HISTORY
  • CSIDL_INTERNET_CACHE
  • CSIDL_LOCAL_APPDATA
  • CSIDL_MYPICTURES
  • CSIDL_PERSONAL
  • CSIDL_PROGRAM_FILES
  • CSIDL_PROGRAM_FILES_COMMON
  • CSIDL_SYSTEM
  • CSIDL_WINDOWS

Requirements

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in shlobj.h.
Import Library: shell32.lib.


SHGetIconOverlayIndex

Returns the index of the overlay icon in the system image list.

int SHGetIconOverlayIndex(
    LPCTSTR pszIconPath,
    int iIconIndex
);

Parameters

pszIconPath
[in] Fully qualified path of the file that contains the icon.
iIconIndex
[in] Icon's index in the file pointed to by pszIconPath. To request a standard overlay icon, set pszIconPath to NULL, and iIconIndex to one of the following:
IDO_SHGIOI_SHARE | The overlay icon that indicates a shared folder.
IDO_SHGIOI_LINK | The overlay icon that indicates a linked folder or file.
IDO_SHGIOI_SLOWFILE | The overlay icon that indicates a slow file.

Return Values

Returns the index of the overlay icon in the system image list if successful, or -1 otherwise.

Remarks

Icon overlays are part of the system image list. They have two identifiers. One is a one-based overlay index that identifies the overlay relative to other overlays in the image list. The other is an image index that identifies the actual image. These two indexes are equivalent to the values that you assign to the iOverlay and iImage parameters, respectively, when you add an icon overlay to a private image list with ImageList_SetOverlayImage. ShGetIconOverlayIndex returns the overlay index. To convert an overlay index to its equivalent image index, call INDEXTOOVERLAYMASK.

Note Once the image has been loaded into the system image list during initialization, it cannot be changed. The file name and index specified by pszIconPath and iIconIndex are used only to identify the icon overlay. ShGetIconOverlayIndex cannot be used to modify the system image list.

See Also

IShellIconOverlayIdentifier, IShellIconOverlay

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetInstanceExplorer

Allows components that run in a Web browser (Iexplore.exe) or a nondefault Windows® Explorer (Explorer.exe) process to hold a reference to the process. The components can use the reference to prevent the process from closing prematurely.

HRESULT SHGetInstanceExplorer(
    IUnknown **ppunk
);

Parameters

ppunk
[out] Address of an Explorer.exe or Iexplore.exe IUnknown interface pointer. If the function succeeds, SHGetInstanceExplorer increments the host's reference count before it returns. Components thus do not need to call (*ppunk)->AddRef. Components should call (*ppunk)->Release to release the reference when the host process is no longer needed. If SHGetInstanceExplorer fails, *ppunk is set to NULL.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

There are a number of components, such as Shell extension handlers, that are implemented as DLLs and run in the process space of Windows Explorer (Explorer.exe) or Internet Explorer (Iexplore.exe). Normally, when the user closes the host process, the component is shut down immediately as well. Such an abrupt termination can create problems for some components. For example, if a component is using a background thread to download data or run user-interface functions, it might need additional time to safely shut itself down.

The SHGetInstanceExplorer function allows components that run in an Iexplorer.exe or a nondefault Explorer.exe process to hold a reference on the host process. SHGetInstanceExplorer increments the host's reference count and returns a pointer to its IUnknown interface. By holding that reference, a component can prevent the host process from closing prematurely. Once the component has completed all necessary processing, it should call (*ppunk)->Release to release the host's reference and allow the process to die.

Note If SHGetInstanceExplorer is successful, the component must release the host's reference when it is no longer needed. Otherwise, all resources associated with the process will remain in memory. The IUnknown interface pointed to by *ppunk can be used only to release this reference. Components cannot use (*ppunk)->QueryInterface to request other interface pointers.

SHGetInstanceExplorer succeeds only if it is called from within an Explorer.exe or Iexplorer.exe process. It is typically used by components that run in the context of the Web browser (Iexplore.exe). However, it is also useful when Explorer.exe has been configured to run all folders in a second process. SHGetInstanceExplorer fails if the component is running in the default Explorer.exe process. There is no need to hold a reference to this process, as it is shut down only when the user logs out.

In general, components can be loaded by either the default Explorer.exe process or a secondary Explorer.exe or Iexplore.exe process. The component must thus be able to handle either the success or failure of SHGetInstanceExplorer.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetUnreadMailCount Function

This is preliminary documentation and is subject to change.

Retrieves a specified user's unread message count for any or all e-mail accounts.

Syntax

HRESULT SHGetUnreadMailCount(
    HKEY hKeyUser,
    LPCTSTR pszMailAddress,
    DWORD *pdwCount,
    FILETIME *pFileTime,
    LPCTSTR pszShellExecuteCommand,
    int cchShellExecuteCommand
);

Parameters

hKeyUser
[in] A valid HKEY for a given user or HKEY_CURRENT_USER if the current user information is required.
pszMailAddress
[in] Pointer to a string in Unicode that specifies the e-mail address of an account belonging to the specified user. When this parameter is NULL, pdwCount returns the total count of unread messages for all accounts owned by the designated user.
pdwCount
[out] Pointer to an unsigned long integer count of the number of unread messages.
pFileTime
[out] Pointer to a FILETIME structure into which this function should place the FILETIME of the last SHSetUnreadMailCount call for the specified user and e-mail account. This parameter can be NULL when the FILETIME information is not required.
pszShellExecuteCommand
[out] Pointer to a string in Unicode that returns the ShellExecute command statement passed into the last SHSetUnreadMailCount call for the specified user and e-mail account. This command string starts the e-mail application that owns the account referenced by pszMailAddress. If the ShellExecute command is not required, this parameter may be NULL.
cchShellExecuteCommand
[in] integer specifying the maximum size in characters of the ShellExecute command buffer pointed to by pszShellExecuteCommand. This parameter must be zero for total counts when pszMailAddress is NULL. It can also be NULL whenever the ShellExecute command string is not required.

Return Value

Returns S_OK if this function is successful, otherwise an error code.

Remarks

This function is exported from Shell32.dll in Unicode only; there is no ANSI version.

Function Information

Stock Implementation | shell32.dll version 5.60 or later
Custom Implementation | No
Header | shell32.h
Import library | shell32.lib
Minimum operating systems | Windows NT Whistler


SHGetMalloc

Retrieves a pointer to the Shell's IMalloc interface.

HRESULT SHGetMalloc(
    LPMALLOC *ppMalloc
);

Parameters

ppMalloc
Address of a pointer that receives the Shell's IMalloc interface pointer.

Return Values

Returns NOERROR if successful, or E_FAIL otherwise.

Remarks

This interface must be used to free memory that was allocated by the Shell or to allocate memory that will be freed by the Shell. Applications can also use this interface to allocate and free their own memory.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetNewLinkInfo

Creates the proper name for a new shortcut. This function does not actually create a shortcut.

BOOL SHGetNewLinkInfo(
    LPCTSTR pszLinkTo,
    LPCTSTR pszDir,
    LPTSTR pszName,
    BOOL *pfMustCopy,
    UINT uFlags
);

Parameters

pszLinkTo
[in] Specifies the path and file name of the target of the shortcut. If uFlags does not contain the SHGNLI_PIDL value, this parameter is the address of a NULL-terminated string that contains the target. If uFlags contains the SHGNLI_PIDL value, this parameter is a PIDL that represents the target.
pszDir
[in] Address of a NULL-terminated string that contains the path of the folder that the shortcut would be created in.
pszName
[out] Address of a string that receives the NULL-terminated path and file name for the shortcut. This buffer is assumed to be at least MAX_PATH characters in size.
pfMustCopy
[out] Address of a BOOL value that receives a flag that indicates if the shortcut would be copied. When a shortcut to another shortcut is created, the Shell simply copies the target shortcut and modifies that copied shortcut appropriately. This value receives a non-zero value if the target specified in pszLinkTo specifies a shortcut that will cause the target shortcut to be copied. This value receives zero if the target does not specify a shortcut that would be copied.
uFlags
[in] Specifies the options for the function. This can be zero or a combination of the following values:
Value | Description
SHGNLI_PIDL | pszLinkTo is a PIDL that represents the target. If this flag is not included, pszLinkTo is the address of a string that contains the path and file name of the target.
SHGNLI_NOUNIQUE | The function will not create a unique name within the destination folder. If this flag is not included, the function create the shortcut name and then determine if the name is unique in the destination folder. If a file with the same name exists within the destination folder, the shortcut name will be modified. This process is repeated until a unique name is found.
SHGNLI_PREFIXNAME | The created name will be preceded by the string "Shortcut to ".

Return Values

Returns non-zero if successful or zero otherwise.

Remarks

SHGetNewLinkInfo will determine the executable type of the target. If pszLinkTo specifies a DOS application, the ".PIF" extension will be used, otherwise the ".LNK" extension will be used for the shortcut.

SHGetNewLinkInfo will also determine if the destination file system supports long file names. If the destination file system does support long file names, then a long file name will be used for the shortcut name. If the destination file system does not support long file names, then the shortcut name will be returned in an 8.3 format.

This function is implemented in Shell versions 4.71 and later. In order to maintain backward compatibility with previous Shell versions, this function should not be used explicitly. Instead, the LoadLibrary and GetProcAddress functions should be used to obtain the function address.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHGetPathFromIDList

Converts an item identifier list to a file system path.

BOOL SHGetPathFromIDList(
    LPCITEMIDLIST pidl,
    LPSTR pszPath
);

Parameters

pidl
Address of an item identifier list that specifies a file or directory location relative to the root of the namespace (the desktop).
pszPath
Address of a buffer to receive the file system path. This buffer must be at least MAX_PATH characters in size.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the location specified by the pidl parameter is not part of the file system, this function will fail.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetSettings

Retrieves the current Shell option settings.

VOID SHGetSettings(
    LPSHELLFLAGSTATE lpsfs,
    DWORD dwMask
);

Parameters

lpsfs
Address of a SHELLFLAGSTATE structure that receives the Shell option settings.
dwMask
Set of flags that determine which members of lpsfs are being requested. This can be one or more of the following values:
SSF_DESKTOPHTML | The fDesktopHTML member is being requested.
SSF_DONTPRETTYPATH | The fDontPrettyPath member is being requested.
SSF_DOUBLECLICKINWEBVIEW | The fDoubleClickInWebView member is being requested.
SSF_HIDEICONS | The fHideIcons member is being requested.
SSF_MAPNETDRVBUTTON | The fMapNetDrvBtn member is being requested.
SSF_NOCONFIRMRECYCLE | The fNoConfirmRecycle member is being requested.
SSF_SHOWALLOBJECTS | The fShowAllObjects member is being requested.
SSF_SHOWATTRIBCOL | The fShowAttribCol member is being requested.
SSF_SHOWCOMPCOLOR | The fShowCompColor member is being requested.
SSF_SHOWEXTENSIONS | The fShowExtensions member is being requested.
SSF_SHOWINFOTIP | The fShowInfoTip member is being requested.
SSF_SHOWSYSFILES | The fShowSysFiles member is being requested.
SSF_WIN95CLASSIC | The fWin95Classic member is being requested.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHGetSpecialFolderLocation

Retrieves a pointer to the ITEMIDLIST structure of a special folder.

HRESULT SHGetSpecialFolderLocation(
    HWND hwndOwner,
    int nFolder,
    LPITEMIDLIST *ppidl
);

Parameters

hwndOwner
Handle to the owner window the client should specify if it displays a dialog box or message box.
nFolder
A CSIDL value that identifies the folder of interest.
ppidl
A pointer to the folder's item identifier list (PIDL) specifying the folder's location relative to the root of the namespace (the desktop). The calling application is responsible for freeing this pointer with the Shell's IMalloc interface (see SHGetMalloc).

Return Values

Returns NOERROR if successful, or an OLE-defined error result otherwise.

Remarks

With Windows 2000, this function is superseded by ShGetFolderLocation.

See Also

SHGetSpecialFolderPath

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHGetSpecialFolderPath

Retrieves the path of a special folder, identified by its CSIDL.

BOOL SHGetSpecialFolderPath(
    HWND hwndOwner,
    LPTSTR lpszPath,
    int nFolder,
    BOOL fCreate
);

Parameters

hwndOwner
Handle to the owner window the client should specify if it displays a dialog box or message box.
lpszPath
Address of a character buffer that receives the drive and path of the specified folder. This buffer must be at least MAX_PATH characters in size.
nFolder
A CSIDL that identifies the folder of interest. If a virtual folder is specified, this function will fail.
fCreate
Indicates if the folder should be created if it does not already exist. If this value is nonzero, the folder will be created. If this value is zero, the folder will not be created.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The Microsoft® Internet Explorer 4.0 Desktop Update must be installed for this function to be available.

With Microsoft® Windows® 2000, this function is superseded by ShGetFolderPath. You can use this function on earlier systems by including the redistributable DLL, ShFolder.dll.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHIsFileAvailableOffline Function

Determines whether a file or folder is available for offline use. It also determines whether the file would be opened from the network, from the local Offline Files cache, or from both locations.

Syntax

HRESULT SHIsFileAvailableOffline(
    LPCWSTR pszPath,
    LPDWORD pdwStatus
);

Parameters

pszPath
[in] Pointer to a string value that specifies the full path to a network file or directory. This path does not need to be in Universal Naming Convention (UNC) form. If pszPath is not a network path, the function returns E_INVALIDARG.
pdwStatus
[out] Pointer to a variable of type DWORD that receives one or more of the following flags if the function succeeds.
OFFLINE_STATUS_LOCAL
If the file is open, it is open in the cache.
OFFLINE_STATUS_REMOTE
If the file is open, it is open on the server.
OFFLINE_STATUS_INCOMPLETE
The local copy is currently incomplete. The file cannot be opened in offline mode until it has been synchronized.

Return Value

Returns one of the following values:

S_OK | The file or directory is cached. It is available offline unless OFFLINE_STATUS_INCOMPLETE is set.
E_INVALIDARG | The path is invalid or not a network path. The file or directory is not cached.
E_FAIL | The file or directory is not cached.

Remarks

If pszPath is a directory, SHIsFileAvailableOffline will not return the OFFLINE_STATUS_INCOMPLETE flag.

If SHIsFileAvailableOffline returns both OFFLINE_STATUS_LOCAL and OFFLINE_STATUS_REMOTE, the file or directory is open in both places. This is common when the server is online.

Function Information

Stock Implementation | shell32.dll version 5.00 or later
Custom Implementation | No
Header | shellapi.h
Import library | shell32.lib
Minimum operating systems | Windows 2000


SHLoadNonloadedIconOverlayIdentifiers Function

Causes the Shell to load icon overlay identifiers that either failed creation or were not present for creation at startup. Identifiers that have already been loaded are not affected.

Syntax

HRESULT SHLoadNonloadedIconOverlayIdentifiers(VOID);

Return Value

Returns S_OK.

Remarks

For more information, see Creating Icon Overlay Handlers.

Function Information

Stock Implementation | shell32.dll version 5.00 or later
Custom Implementation | No
Header | shellapi.h
Import library | shell32.lib
Minimum operating systems | Windows 2000


SHPathPrepareForWrite Function

Checks to see if the path exists. This includes remounting mapped network drives, prompting for ejectable media to be reinserted, creating the paths, prompting for the media to be formatted, and providing the appropriate user interfaces, if necessary. Read/write permissions for the medium are not checked.

Syntax

HRESULT SHPathPrepareForWrite(
    HWND hwnd,
    IUnknown *punkEnableModless,
    LPCTSTR pszPath,
    DWORD dwFlags
);

Parameters

hwnd
[in] Handle to a window that specifies the parent window to be used for any user interface windows that need to be created. If set to NULL, user interface windows will not be created.
punkEnableModless
[in] Pointer to an IUnknown interface that specifies the IOleInPlaceActiveObject object that implements the EnableModeless method.
pszPath
[in] Pointer to a string value that specifies the path to be verified as valid for writing. This can be a Universal Naming Convention (UNC) or file drive path.
dwFlags
[in] DWORD that specifies the flags that determine behavior options. This parameter can be a combination of the following values:
SHPPFW_NONE
Do not create new directories.
SHPPFW_DEFAULT
Default. Do not prompt the user if a directory needs to be created. This is identical to SHPPFW_DIRCREATE. Do not pass with SHPPFW_ASKDIRCREATE.
SHPPFW_DIRCREATE
Create directories without prompting the user. Do not pass with SHPPFW_ASKDIRCREATE.
SHPPFW_ASKDIRCREATE
Prompt the user before creating directories. Do not pass with SHPPFW_DIRCREATE.
SHPPFW_IGNOREFILENAME
Last item in pszPath is a file name, so ignore. For example, if pszPath="C:\MyDir\MyFile.doc", only use "C:\MyDir". If pszPath="C:\MyFirDir\MySecDir", only use "C:\MyFirDir".
SHPPFW_NOWRITECHECK
Not currently implemented.

Return Value

Returns S_OK if the path is available, or an error code otherwise. Note that a return value of S_OK does not mean that the medium is writable; it simply means that the path is available.

Remarks

The primary use of this function is for a program to check a path before using it and display the necessary user interface to prompt the user. For example, if the disk in drive A: were missing, a window prompting the user to insert the disk would appear.

Function Information

Stock Implementation | shell32.dll version 5.00 or later
Custom Implementation | No
Header | shlobj.h
Import library | shell32.lib
Minimum operating systems | Windows 2000


SHSetLocalizedName Function

This is preliminary documentation and is subject to change.

Displays the localized name of a file in a Shell folder.

Syntax

HRESULT SHSetLocalizedName(
    LPWSTR pszPath,
    LPCWSTR pszResModule,
    int idsRes
);

Parameters

pszPath
[in] Pointer to a string that specifies the fully qualified path of the target file.
pszResModule
[in] Pointer to a string resource that specifies the localized version of the file name.
idsRes
[in] Integer ID that specifies the localized file name in the string resource.

Return Value

Returns S_OK on success, an error code otherwise.

Function Information

Stock Implementation | shell32.dll version 5.6 or later
Custom Implementation | No
Header | shellapi.h
Import library | shell32.dll
Minimum operating systems | Windows NT Whistler


SHInvokePrinterCommand

Executes a command on a printer object.

BOOL SHInvokePrinterCommand(
    HWND hwnd,
    UINT uAction,
    LPCTSTR lpBuf1,
    LPCTSTR lpBuf2,
    BOOL fModal
);

Parameters

hwnd
Handle of the window that will be used as the parent of any windows or dialog boxes that are created during the operation.
uAction
A value that determines the type of printer operation that will be performed. This can be one of the following values:
PRINTACTION_DOCUMENTDEFAULTS | Windows NT® only. The default document properties for the printer specified by the name in lpBuf1 will be displayed. lpBuf2 is ignored.
PRINTACTION_NETINSTALL | The network printer specified by the name in lpBuf1 will be installed. lpBuf2 is ignored.
PRINTACTION_NETINSTALLLINK | A shortcut to the network printer specified by the name in lpBuf1 will be created. lpBuf2 specifies the drive and path of the folder in which the shortcut will be created. The network printer must have already been installed on the local computer.
PRINTACTION_OPEN | The printer specified by the name in lpBuf1 will be opened. lpBuf2 is ignored.
PRINTACTION_OPENNETPRN | The network printer specified by the name in lpBuf1 will be opened. lpBuf2 is ignored.
PRINTACTION_PROPERTIES | The properties for the printer specified by the name in lpBuf1 will be displayed. lpBuf2 can either be NULL or specify.
PRINTACTION_SERVERPROPERTIES | Windows NT® only. The properties for the server of the printer specified by the name in lpBuf1 will be displayed. lpBuf2 is ignored.
PRINTACTION_TESTPAGE | A test page will be printed on the printer specified by the name in lpBuf1. lpBuf2 is ignored.
lpBuf1
Address of a string that contains additional information for the printer command. The information contained in this parameter depends upon the value of uAction.
lpBuf2
Address of a string that contains additional information for the printer command. The information contained in this parameter depends upon the value of uAction.
fModal
A value that determines whether SHInvokePrinterCommand should return after initializing the command or wait until the command is completed. If this value is non-zero, SHInvokePrinterCommand will not return until the command is completed. If this value is zero, SHInvokePrinterCommand will return as soon as the command is initialized.

Return Values

Returns non-zero if successful or zero otherwise.

Remarks

When a printer name is specified by lpBuf1, the name can either be the name of a local printer or the server and share name of a network printer. When specifying a network printer name, the name must be specified in the format of "\\<server>\<shared printer name>".

This function is implemented in Shell versions 4.71 and later. In order to maintain backward compatibility with previous Shell versions, this function should not be used explicitly. Instead, the LoadLibrary and GetProcAddress functions should be used to obtain the function address.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHLoadInProc

Creates an instance of the specified object class from within the context of the Shell's process.

HRESULT SHLoadInProc(
    REFCLSID rclsid
);

Parameters

rclsid
CLSID of the object class to be created.

Return Values

Returns NOERROR if successful, or an OLE-defined error result otherwise.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SHOpenFolderAndSelectItems Function

This is preliminary documentation and is subject to change.

Opens a Shell folder and selects specified items.

Syntax

HRESULT SHOpenFolderAndSelectItems(
    LPCITEMIDLIST pidlFolder,
    UINT cidl,
    LPCITEMIDLIST *apidl,
    DWORD dwFlags
);

Parameters

pidlFolder
[in] Pointer to a fully qualified Shell Item identifier (ID) List, also known as a PIDL. For a detailed discussion of pidls see Working with Item ID Lists
cidl
[in] Unsigned integer count of items in the selection array, apidl. If cidl is zero, then pidlFolder must point to a fully specified Shell Item ID List describing a single item to select. This function opens the parent folder and selects that item.
apidl
[in] Pointer to an array of PIDL structures, each of which is an item to select in the target folder referenced by pidlFolder.
dwFlags
[in] Optional flags. In the current implementation, this parameter is ignored.

Return Value

Returns S_OK on success, otherwise an error code.

Function Information

Stock Implementation | shell32.dll version 5.6 or later
Custom Implementation | No
Header | shlobj.h
Import library | shell32.lib
Minimum operating systems | Windows NT Whistler


SHQueryRecycleBin

Retrieves the size of the Recycle Bin, and the number of items in it, on the specified drive.

HRESULT SHQueryRecycleBin(
    LPCTSTR pszRootPath,
    LPSHQUERYRBINFO pSHQueryRBInfo
);

Parameters

pszRootPath
Address of a NULL-terminated string to contain the path of the root drive on which the Recycle Bin is located. This parameter can contain the address of a string formatted with the drive, folder, and subfolder names (C:\Windows\System...).
pSHQueryRBInfo
Address of a SHQUERYRBINFO structure that receives the Recycle Bin information. The cbSize member of the structure must be set to the size of the structure before calling this API.

Return Values

Returns S_OK if successful, or an OLE-defined error value otherwise.

Remarks

With Microsoft® Windows® 2000, if NULL is passed in the pszRootPath parameter, the function fails and returns an E_INVALIDARG error code. Earlier versions of the operating system allow you to pass an empty string or NULL. If pszRootPath contains an empty string or NULL, information is retrieved for all Recycle Bins on all drives.

See Also

SHEmptyRecycleBin

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHSetUnreadMailCount Function

This is preliminary documentation and is subject to change.

Stores the current user's unread message count for a specified e-mail account.

Syntax

HRESULT SHSetUnreadMailCount(
    LPCTSTR pszMailAddress,
    DWORD dwCount,
    LPCTSTR pszShellExecuteCommand
);

Parameters

pszMailAddress
[in] Pointer to a string in Unicode that contains the current user's full e-mail address.
dwCount
[in] Unsigned long count of the number of unread messages.
pszShellExecuteCommand
[in] Pointer to a string in Unicode that contains the full text of a command that can be passed to ShellExecute. This command should start the e-mail application that owns the account referenced by pszMailAddress.

Return Value

HRESULT, which includes the following possibilities:

S_OK | The call completed successfully.
E_OUTOFMEMORY | Insufficient memory available.
E_INVALIDARG | Invalid string argument in either the pszMailAddress or pszShellExecuteCommand parameters.

Remarks

This function is exported from Shell32.dll in Unicode; there is no ANSI version.

Function Information

Stock Implementation | shell32.dll version 5.60 or later
Custom Implementation | No
Header | shell32.h
Import library | shell32.lib
Minimum operating systems | Windows NT Whistler


SHUpdateImage

Notifies the Shell that an image in the system image list has changed.

void SHUpdateImage(
    LPCTSTR pszHashItem,
    int iIndex,
    UINT uFlags,
    int iImageIndex
);

Parameters

pszHashItem
[in] Pointer to a string value that specifies the fully qualified path of the file that contains the icon. Use the path that is returned in the buffer pointed to by the szIconFile parameter of IExtractIcon::GetIconLocation.
iIndex
[in] Integer that specifies the zero-based index of the icon in the file specified by pszHashItem. Use the value that is pointed to by the piIndex parameter of IExtractIcon::GetIconLocation.
uFlags
[in] Unsigned integer that specifies the flags that determine the icon attributes. Set uFlags to the value that is pointed to by the pwFlags parameter of IExtractIcon::GetIconLocation. The flags that are relevant to SHUpdateImage are GIL_NOTFILENAME and GIL_SIMULATEDOC.
iImageIndex
[in] Integer that specifies the index in the system image list of the icon that is being updated.

Return Values

No return value.

Remarks

If you do not know the index in the system image list of the icon that you want to update, use SHGetFileInfo with the uFlags parameter set to SHGFI_SYSICONINDEX.

Note that you must use IExtractIcon::GetIconLocation with the parameters of the old icon that needs to be updated, not those of the new icon you want to replace it with.

See Also

SHChangeNotify

Requirements

Version 4.7x and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.
Import Library: Shell32.lib.


SoftwareUpdateMessageBox

Displays a standard message box that can be used to notify a user that an application has been updated.

DWORD SoftwareUpdateMessageBox(
    HWND hWnd,
    LPCWSTR szDistUnit,
    DWORD dwFlags,
    LPSOFTDISTINFO psdi
);

Parameters

hWnd
Handle to the parent window.
szDistUnit
String value containing the identifier for the code distribution unit. For ActiveX® controls, szDistUnit is typically a globally unique identifier (GUID).
dwFlags
Reserved. Must be set to zero.
psdi
Address of a SOFTDISTINFO structure in which to store the update information. The cbSize member must be initialized to the sizeof(SOFTDISTINFO).

Return Values

Returns one of the following values.
IDNO | The user clicked the Don't Update button on the dialog box.
IDYES | The user clicked the Update Now or About Update button. The application should navigate to the HTML page referred to by the szHREF member of the structure pointed to by psdi.
IDIGNORE | There is no pending software update.
IDABORT | An error occurred.

Remarks

The preferred way to handle updates is to author a Channel Definition Format with an Open Software Description (OSD) vocabulary inside and make the shortcut OSD-aware. Refer to the Channel Definition Format documentation for details.

The SoftwareMessageBox function is intended to be used in the case where Shell shortcut hooks do not work. One example is an application that was not installed on the start menu. If that application needs to do it's own software update check it should use this function.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


TranslateURL

Applies common translations to a given URL string, creating a new URL string.

HRESULT TranslateURL(
  LPCSTR pcszURL,
  DWORD dwInFlags,
  LPSTR *ppszTranslatedURL,
);

Parameters

pcszURL
Address of the URL string to be translated.
dwInFlags
Bit flags that specify how the URL string is to be translated. This value can be a combination of the following:
TRANSLATEURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system automatically chooses a scheme and adds it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system adds the default protocol to the URL.
ppszTranslatedURL
Pointer variable that receives the pointer to the newly created, translated URL string, if any. The *ppszTranslatedURL parameter is valid only if the function returns S_OK.

Return Value

Returns S_OK upon success, or S_FALSE if the URL did not require translation. If an error occurs, the function returns one of the following values:

E_FLAGS
The flag combination passed in dwInFlags is invalid.
E_OUTOFMEMORY
There was insufficient memory to complete the operation.
E_POINTER
One of the input pointers is invalid.

Remarks

This function does not validate the input URL string. A successful return value does not indicate that the URL strings are valid URLs.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


URLAssociationDialog

Invokes the unregistered URL protocol dialog box. This dialog box allows the user to select an application to associate with a previously unknown protocol.

HRESULT URLAssociationDialog(
  HWND hwndParent,
  DWORD dwInFlags,
  LPCSTR pcszFile,
  LPCSTR pcszURL,
  LPSTR pszAppBuf,
  UINT ucAppBufLen,
);

Parameters

hwndParent
Handle to the parent window.
dwInFlags
Bit flags that specify the behavior of the function. This value can be a combination of the following:
URLASSOCDLG_FL_USE_DEFAULT_NAME
Use the default file name (that is, "Internet Shortcut").
URLASSOCDLG_FL_REGISTER_ASSOC
Register the selected application as the handler for the protocol specified in pcszURL. The application is registered only if this flag is set and the user indicates that a persistent association is desired.
pcszFile
Address of a constant zero-terminated string that contains the file name to associate with the URL's protocol.
pcszURL
Address of a constant zero-terminated string that contains the URL with an unknown protocol.
pszAppBuf
Address of a buffer that receives the path of the application specified by the user.
ucAppBufLen
The size of pszAppBuf, in characters.

Return Value

Returns S_OK if the application is registered with the URL protocol, or S_FALSE if nothing is registered. For example, the function returns S_FALSE when the user elects to perform a one-time execution via the selected application.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


WinHelp

Starts Microsoft® Windows® Help (Winhelp.exe) and passes additional data that indicates the nature of the help requested by the application.

BOOL WinHelp(
    HWND hWndMain,
    LPCTSTR lpszHelp,
    UINT uCommand,
    DWORD dwData
);

Parameters

hWndMain
Handle to the window requesting help. The WinHelp function uses this handle to keep track of which applications have requested help. If the uCommand parameter specifies HELP_CONTEXTMENU or HELP_WM_HELP, hWndMain identifies the control requesting help.
lpszHelp
Address of a null-terminated string containing the path, if necessary, and the name of the Help file that WinHelp is to display.

The file name can be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. You must define the name of the secondary window in the [WINDOWS] section of the Help project (.hpj) file.

uCommand
Type of help requested. For a list of possible values and how they affect the value to place in the dwData parameter, see the Remarks section.
dwData
Additional data. The value used depends on the value of the uCommand parameter. For a list of possible dwData values, see the Remarks section.

Return Values

Returns nonzero if successful, or zero otherwise. To retrieve extended error information, call GetLastError.

Remarks

Before closing the window that requested help, the application must call WinHelp with the uCommand parameter set to HELP_QUIT. Until all applications have done this, Windows Help will not terminate. Note that calling Windows Help with the HELP_QUIT command is not necessary if you used the HELP_CONTEXTPOPUP command to start Windows Help.

The following table shows the possible values for the uCommand parameter and the corresponding formats of the dwData parameter.

uCommand | Action | dwData
HELP_COMMAND | Executes a Help macro or macro string. | Address of a string that specifies the name of the Help macro(s) to run. If the string specifies multiple macro names, the names must be separated by semicolons. You must use the short form of the macro name for some macros because Windows Help does not support the long name.
HELP_CONTENTS | Displays the topic specified by the Contents option in the [OPTIONS] section of the .hpj file. This command is for backward compatibility. New applications should provide a .cnt file and use the HELP_FINDER command. | Ignored; set to 0.
HELP_CONTEXT | Displays the topic identified by the specified context identifier defined in the [MAP] section of the .hpj file. | Contains the context identifier for the topic.
HELP_CONTEXTMENU | Displays the Help menu for the selected window, then displays the topic for the selected control in a pop-up window. | Address of an array of double word pairs. The first double word in each pair is the control identifier, and the second is the context identifier for the topic. The array must be terminated by a pair of zeros {0,0}. If you do not want to add Help to a particular control, set its context identifier to -1.
HELP_CONTEXTPOPUP | Displays the topic identified by the specified context identifier defined in the [MAP] section of the .hpj file in a pop-up window. | Contains the context identifier for a topic.
HELP_FINDER | Displays the Help Topics dialog box. | Ignored; set to 0.
HELP_FORCEFILE | Ensures that Windows Help is displaying the correct Help file. If the incorrect Help file is being displayed, Windows Help opens the correct one; otherwise, there is no action. | Ignored; set to 0.
HELP_HELPONHELP | Displays help on how to use Windows Help, if the Winhlp32.hlp file is available. | Ignored; set to 0.
HELP_INDEX | Displays the topic specified by the Contents option in the [OPTIONS] section of the .hpj file. This command is for backward compatibility. New applications should use the HELP_FINDER command. | Ignored; set to 0.
HELP_KEY | Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Index with the topics listed in the Topics Found list box. | Address of a keyword string. Multiple keywords must be separated by semicolons.
HELP_MULTIKEY | Displays the topic specified by a keyword in an alternative keyword table. | Address of a MULTIKEYHELP structure that specifies a table footnote character and a keyword.
HELP_PARTIALKEY | Displays the topic in the keyword table that matches the specified keyword, if there is an exact match. If there is more than one match, displays the Topics Found dialog box. To display the index without passing a keyword, use a pointer to an empty string. | Address of a keyword string. Multiple keywords must be separated by semicolons.
HELP_QUIT | Informs Windows Help that it is no longer needed. If no other applications have asked for help, Windows closes Windows Help. | Ignored; set to 0.
HELP_SETCONTENTS | Specifies the Contents topic. Windows Help displays this topic when the user clicks the Contents button if the Help file does not have an associated .cnt file. | Contains the context identifier for the Contents topic.
HELP_SETPOPUP_POS | Sets the position of the subsequent pop-up window. | Contains the position data. Use MAKELONG to concatenate the horizontal and vertical coordinates into a single value. The pop-up window is positioned as if the mouse cursor were at the specified point when the pop-up window was invoked.
HELP_SETWINPOS | Displays the Windows Help window, if it is minimized or in memory, and sets its size and position as specified. | Address of a HELPWININFO structure that specifies the size and position of either a primary or secondary Help window.
HELP_TCARD | Indicates that a command is for a training card instance of Windows Help. Combine this command with other commands using the bitwise OR operator. | Depends on the command with which this command is combined.
HELP_WM_HELP | Displays the topic for the control identified by the hWndMain parameter in a pop-up window. | Address of an array of double word pairs. The first double word in each pair is a control identifier, and the second is a context identifier for a topic. The array must be terminated by a pair of zeros {0,0}. If you do not want to add Help to a particular control, set its context identifier to -1.

See Also

HELPWININFO, MULTIKEYHELP

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winuser.h.
Import Library: User32.lib.


SOBailOut

Allows the file parser to return an error condition.

VOID SOBailOut(
    WORD wError,
    HPROC reserved
);

Parameters

wError
Error flag. This parameter can be one of these values:
SOERROR_BADFILE | Invalid file format
SOERROR_EOF | Unexpected end of file (EOF)
SOERROR_GENERAL | Unspecified error
reserved
Reserved; do not use.

Return Values

No return value.

Remarks

The parser should return from the VwStreamReadFunc function as soon as possible after this function is called.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOBeginTable

Starts a table definition, indicating that the text in subsequent output calls is part of a table. This function must be called between paragraphs and before row and cell formats are specified.

Syntax

VOID SOBeginTable(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEndColumnInfo

Ends the definition of column information. The file parser must call this function immediately after setting the column information.

Syntax

VOID SOEndColumnInfo(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEndFieldInfo

Ends the definition of field information.

VOID SOEndFieldInfo(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Values

No return value.

Remarks

The file parser must have previously called the SOStartFieldInfo function.

The file parser calls the SOEndFieldInfo function immediately after setting the field information. The SOEndFieldInfo function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEndFontTable

Ends the definition of a font table.

Syntax

VOID SOEndFontTable(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return

No return value.

Remarks

The file parser must call this function immediately after setting font entries. This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEndPalette

Ends the definition of a color palette.

Syntax

VOID SOEndPalette(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser calls this function immediately after specifying the last palette entry.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEndTable

Ends a table definition, indicating that the text in subsequent output calls is no longer part of a table.

Syntax

VOID SOEndTable(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function must be called after a row break.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEndTabStops

Ends the definition of tabs stops for a paragraph.

VOID SOEndTabStops(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Values

No return value.

Remarks

To set tab stops, use the SOPutTabStop function.

The file parser calls the SOEndTabStops function immediately after setting the last tab stop for the paragraph.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOGetInfo

Retrieves information about a spreadsheet.

Syntax

VOID SOGetInfo(
    WORD wInfo,
    void VWPTR *pInfo,
    HPROC reserved
);

Parameters

wInfo
Information type. If this parameter is the SOINFO_COLUMNRANGE value, the function retrieves the range of columns for a spreadsheet to read.
pInfo
Address of a 32-bit variable that receives the first column number in the low-order word and the second column number in the high-order word.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOGetScanLineBuffer

Retrieves the address of the buffer for storing the current scan line.

WORD SOGetScanLineBuffer(
    VOID VWPTR *ppScanLineData,
    HPROC reserved

);

Parameters

ppScanLineData
Address of the variable that receives the address of the scan line data buffer.
reserved
Reserved; do not use.

Return Value

Returns the size, in bytes, of the scan line data buffer. The size is the maximum number of bytes that may be accessed using the returned address and is guaranteed to be sufficient to hold a scan line as wide as the entire tile.

Remarks

This function is called from the VwStreamReadFunc function for each scan line produced.

The SOGetScanLineBuffer function sets the variable pointed to by ppScanLineData to the address where the scan line data should be built.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutBitmapHeader

Outputs information about a bitmap.

Syntax

VOID SOPutBitmapHeader(
    PSOBITMAPHEADER pBitmapHeader,
    HPROC reserved
);

Parameters

pBitmapHeader
Address of the SOBITMAPHEADER structure that contains the bitmap header information.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutBreak

Sets a paragraph, cell, record, page, section, or other type of break.

Syntax

WORD SOPutBreak(
    WORD wType,
    DWORD dwInfo,
    HPROC reserved
);

Parameters

wType
Type of break. This parameter can be one of these values:
SO_CELLBREAK | Regular cell break.
SO_EOFBREAK | End of file (EOF) break, which implies a section break.
SO_PARABREAK | Regular paragraph break.
SO_RECORDBREAK | Regular record break.
SO_SECTIONBREAK | Section break.
SO_SUBDOCBEGINBREAK | Subdocument's begin break.
SO_SUBDOCENDBREAK | Subdocument's end break.
dwInfo
Data to save for each record. This data is for database section breaks. For all other section types, this parameter should be zero.

dwInfo is saved after every SOPutBreak function and, like the regular save information, should represent the next record, not the one just read.

reserved
Reserved; do not use.

Return Value

Returns the SO_STOP value to direct the file parser to stop processing and return, or the SO_CONTINUE value to direct the file parser to continue processing.

Remarks

In spreadsheet sections, the last cell in a section must have an associated SO_CELLBREAK break before the SO_SECTIONBREAK or SO_EOFBREAK break.

In database sections, the last record in a section must have an associated SO_RECORDBREAK break before the SO_SECTIONBREAK or SO_EOFBREAK break.

In word processing sections, the last paragraph does not need an SO_PARABREAK break before the SO_SECTIONBREAK or SO_EOFBREAK break.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutChar

Outputs a character, applying the current font, height, and attributes. The character is assumed to belong to the character set selected by the open function and is countable and within the range of displayable characters.

VOID SOPutChar(
    WORD wCh,
    HPROC reserved
);

Parameters

wCh
Character value. This parameter must be within the range specified by the current character set.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutCharAttr

Sets the style attributes for characters in text.

VOID SOPutCharAttr(
    WORD wAttr,
    WORD wState,
    HPROC reserved
);

Parameters

wAttr
Style attribute type. This parameter can be one of these values:
SO_BOLD | Bold
SO_CAPS | All uppercase letters
SO_DOTUNDERLINE | Dotted underline
SO_DUNDERLINE | Double underline
SO_ITALIC | Italic
SO_OUTLINE | Outline rather than solid
SO_SHADOW | Shadow slightly beneath and to the side
SO_SMALLCAPS | Lowercase letters
SO_STRIKEOUT | Strikeout
SO_SUBSCRIPT | Subscript
SO_SUPERSCRIPT | Superscript
SO_UNDERLINE | Single underline
SO_WORDUNDERLINE | Underline
wState
Style attribute state. This parameter can be the SO_ON or SO_OFF value.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutCharFontById

Sets the font for characters in text.

Syntax

VOID SOPutCharFontById(
    DWORD dwFontId,
    HPROC reserved
);

Parameters

dwFontId
Font identifier, relative to the previously given font table.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutCharFontByName

Sets the font for characters in text by specifying the name of the font.

VOID SOPutCharFontByName(
    WORD wFontType,
    WORD pFontName,
    HPROC reserved
);

Parameters

wFontType
Font family. This parameter can be one of these values:
SO_FAMILYDECORATIVE | Fancy display font
SO_FAMILYMODERN | Fixed width
SO_FAMILYROMAN | Variable width with serifs
SO_FAMILYSCRIPT | Handwriting
SO_FAMILYSWISS | Variable width without serifs
SO_FAMILYSYMBOL | Symbol font
SO_FAMILYUNKNOWN | Not known
pFontName
Address of a null-terminated string specifying the name of the font.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutCharHeight

Sets the height, in half points, of a character in text.

Syntax

VOID SOPutCharHeight(
    WORD wHeight,
    HPROC reserved
);

Parameters

wHeight
Height, in half points, of the character.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutCharX

Outputs a character, applying the specified character type. The character is assumed to belong to the character set selected by the open function.

Syntax

VOID SOPutCharX(
    WORD wCh,
    WORD wType,
    HPROC reserved
);

Parameters

wCh
Character value. This parameter must be within the range specified by the current character set.
wType
Type flag. This parameter can be one or more of these values:
SO_COUNT | The character is countable and may be deleted. Characters without this value are for display purposes and do not enter into character count calculations for write-back.
SO_HIDDEN | The character is not visible on the display.
SO_LIMITEDIT | Consecutive characters of this type will be deleted as a group. No write-back command will begin on one of these characters, but it may encompass a group of these characters.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutColumnInfo

Sets column information.

VOID SOPutColumnInfo(
    PSOCOLUMN pColumn,
    HPROC reserved
);

Parameters

pColumn
Address of the SOCOLUMN structure containing the column information.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call the SOStartColumnInfo function before calling this function.

The SOPutColumnInfo function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutDataCell

Outputs data for a cell.

VOID SOPutDataCell(
    PSODATACELL pCell,
    HPROC reserved
);

Parameters

pCell
Address of a SODATACELL structure that contains the cell data information.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutEmbeddedObject

Sets an embedded graphics object.

Syntax

VOID SOPutEmbeddedObject(
    PSOEMBEDDEDOBJECT pObject,
    HPROC reserved
);

Parameters

pObject
Address of the SOEMBEDDEDOBJECT structure that contains information about the object to be embedded.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must set the SOEMBEDDEDOBJECT structure with the appropriate values.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutField

Outputs data for a field.

Syntax

VOID SOPutField(
    void VWPTR *pData,
    HPROC reserved
);

Parameters

pData
Address of the data for the field.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function is used for all storage types except the SO_FIELDTEXTVAR value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutFieldInfo

Sets field information.

VOID SOPutFieldInfo(
    PSOFIELD pField,
    HPROC reserved
);

Parameters

pField
Address of the SOFIELD structure containing the field information.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call the SOStartFieldInfo function before calling this function.

The SOPutFieldInfo function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutFontTableEntry

Sets a font table entry.

VOID SOPutFontTableEntry(
    DWORD dwFontId,
    WORD wFontType,
    Char VWPTR *pFontName,
    HPROC reserved
);

Parameters

dwFontId
Font identifier. This parameter can be any number, but it must be unique within the font table.
wFontType
Font family. This parameter can be one of these values:
SO_FAMILYDECORATIVE | Fancy display font
SO_FAMILYMODERN | Fixed width
SO_FAMILYROMAN | Variable width with serifs
SO_FAMILYSCRIPT | Handwriting
SO_FAMILYSWISS | Variable width without serifs
SO_FAMILYSYMBOL | Symbol font
SO_FAMILYUNKNOWN | Not known
pFontName
Address of a null-terminated string specifying the name of the font.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call the SOStartFontTable function before calling this function. SOPutFontTableEntry must be called once for each font to be added to the table. Font identifiers must be unique, but they can be given in any order.

This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutHdrEntry

Sets strings for the header information.

Syntax

VOID SOPutHdrEntry(
    char VWPTR *pLabel,
    char VWPTR *pData,
    WORD wId,
    HPROC reserved
);

Parameters

pLabel
Label that the display engine should use when presenting this value.
pData
Value to display.
wId
Identifier for this item that the display engine and filter agree upon.
reserved
Reserved; do not use.

Return Values

No return value.

Remarks

This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutMoreText

Outputs the text for a cell and indicates whether there is more text to be output for the cell.

Syntax

VOID SOPutMoreText(
    WORD wCount,
    char VWPTR *pText,
    WORD bMore,
    HPROC reserved
);

Parameters

wCount
Number of characters pointed to by pText. The number must not exceed 128 bytes.
pText
Address of the string of text characters to output.
bMore
Flag that indicates there is more. This parameter can be the SO_YES value to indicate more text to be output, or the SO_NO value to indicate none.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function is used to output a sequence of text initially started by using the SOPutText function.

If there is more text to output, the file parser must use a subsequent call or calls to the SOPutMoreText function to output the text. The 128-byte limit is for the convenience of the function processing SOPutMoreText.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutMoreVarField

Outputs data for a variable field and indicates whether there is more data to be output for the field.

Syntax

VOID SOPutMoreVarField(
    VOID VWPTR *pData,
    WORD wCount,
    WORD bMore,
    HPROC reserved
);

Parameters

pData
Address of the data for the field.
wCount
Number of bytes pointed to by pData. The number must not exceed 128 bytes.
bMore
Flag that indicates there is more data. This parameter can be the SO_YES value to indicate more data to be output, or the SO_NO value to indicate none.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function can be called any number of times.

If there is more data to output, the file parser must use a subsequent call or calls to SOPutMoreVarField to output the data. The 128-byte limit is for the convenience of the function processing SOPutMoreVarField.

This function is used to output a sequence of data initially started using the SOPutVarField function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutPaletteEntry

Sets the colors for a palette entry.

Syntax

VOID SOPutPaletteEntry(
    unsigned char Red,
    unsigned char Green,
    unsigned char Blue,
    HPROC reserved
);

Parameters

Red
Relative red intensity in the range 0 to 255.
Green
Relative green intensity in the range 0 to 255.
Blue
Relative blue intensity in the range 0 to 255.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call the SOStartPalette function before calling this function.

The order of calls to this function determines the order of entries in the color table for an image. The first palette entry is color 0—the color displayed for pixels with a value of 0. The second palette entry is color 1, and so on.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutParaAlign

Sets the alignment for a paragraph.

Syntax

VOID SOPutParAlign(
    WORD wType,
    HPROC reserved
);

Parameters

wType
Type of alignment. This parameter can be the SO_ALIGNLEFT, SO_ALIGNRIGHT, SO_ALIGNCENTER, or SO_ALIGNJUSTIFY value.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutParaIndents

Sets indents for a paragraph.

Syntax

VOID SOPutParaIndents(
    LONG dwLeft,
    LONG dwRight,
    LONG dwFirst,
    HPROC reserved
);

Parameters

dwLeft
Width, in TWIPs, of the left indent. The indent is measured from the left page margin.
dwRight
Width, in TWIPs, of the right indent. The indent is measured from the right page margin.
dwFirst
Width, in TWIPs, of the left indent for the first line in the paragraph. The indent is measured from the left page margin.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutParaMargins

Sets paragraph margins.

Syntax

VOID SOPutParaMargins(
    LONG dwLeft,
    LONG dwRight,
    HPROC reserved
);

Parameters

dwLeft
Width, in TWIPs, of the left margin.
dwRight
Width, in TWIPs, of the right margin.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutParaSpacing

Sets the spacing for a paragraph.

Syntax

VOID SOPutParaSpacing(
    WORD wLineHeightType,
    DWORD dwLineHeight,
    DWORD dwSpaceBefore,
    DWORD dwSpaceAfter,
    HPROC reserved
);

Parameters

wLineHeightType
Type of line height. This parameter can be one of these values:
SO_HEIGHTATLEAST | Sets the line height to the height given by dwLineHeight or sets it to fit the tallest character in the line, whichever height is greater.
SO_HEIGHTAUTO | Sets the line height automatically to fit the tallest character in the line.
SO_HEIGHTEXACTLY | Sets the line height to the height given by dwLineHeight.
dwLineHeight
Baseline to baseline height, in TWIPs.
dwSpaceBefore
Space before the paragraph, in TWIPs.
dwSpaceAfter
Space after the paragraph, in TWIPs.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutScanLineData

Sets the bit values in a single scan line of a bitmap.

Syntax

VOID SOPutScanLineData(
    U_BYTE VWPTR *pScanLineData,
    HPROC reserved
);

Parameters

pScanLineData
Address of the bitmap data for the current scan line.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The bitmap format must have been previously defined by using the SOPutBitmapHeader function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutSectionName

Sets the name of a section.

Syntax

VOID SOPutSectionName(
    char VWPTR *pName,
    HPROC reserved
);

Parameters

pName
Address of a null-terminated string specifying the name of the section.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutSectionType

Outputs a section type.

Syntax

VOID SOPutSectionType(
    WORD wType,
    HPROC reserved
);

Parameters

wType
Section type. This parameter can be one of these values:
SO_BITMAP | Sets the section type to be a bitmap. When generating output for the section, the file parser should use only general and bitmap stream output functions.
SO_CELLS | Sets the section type to be a spreadsheet consisting of cells. When generating output for the section, the file parser should use only the general and spreadsheet stream output functions.
SO_FIELDS | Sets the section type to be a database consisting of fields. When generating output for the section, the file parser should use only the general and database stream output functions.
SO_PARAGRAPHS | Sets the section type to be a word processing document consisting of paragraphs. When generating output for the section, the file parser should use only general and word processing stream output functions.
SO_VECTOR | Sets the section type to be a vector graphics section consisting of graphics objects. When generating output for the section, the file parser should use only the general and vector graphics stream output functions.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutSpecialCharX

Outputs a special character, applying the specified character type.

Syntax

VOID SOPutSpecialCharX(
    WORD wCh,
    WORD wType,
    HPROC reserved
);

Parameters

wCh
Character value. This parameter can be one of these values:
SO_CHDATE | Automatic current date
SO_CHHHYPHEN | Nonbreaking hyphen
SO_CHHLINE | Hard line break
SO_CHHPAGE | Hard page break
SO_CHHSPACE | Nonbreaking space
SO_CHPAGENUMBER | Automatic page number
SO_CHSHYPHEN | Hyphen
SO_CHTAB | Tab
SO_CHTIME | Automatic current time
SO_CHUNKNOWN | Default character
wType
Type flag. This parameter can be one or more of these values:
SO_COUNT | The character is countable and may be deleted. Characters without this value are for display purposes and do not enter into character count calculations for write-back.
SO_HIDDEN | The character is not visible on the display.
SO_LIMITEDIT | Consecutive characters of this type will be deleted as a group. No write-back command will begin on one of these characters, but it may encompass a group of these characters.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutSubdocInfo

Outputs subdocument data.

Syntax

VOID SOPutSubdocInfo(
    WORD wType,
    WORD wSubType,
    HPROC reserved
);

Parameters

wType
Type of data. This parameter can be one of these values:
SO_COMMENT | The data is a comment.
SO_FOOTER | The data applies to the document footer.
SO_FOOTNOTE | The data applies to a footnote.
SO_HEADER | The data applies to the document header.
wSubType
Subtype of data. This parameter can be one of these values:
SO_BOTH | The data is for a header or footer on both left and right pages. This value is used with SO_HEADER or SO_FOOTER.
SO_LEFT | The data is for a header or footer on even pages only. This value is used with SO_HEADER or SO_FOOTER.
SO_RIGHT | The data is for a header or footer on odd pages only. This value is used with SO_HEADER or SO_FOOTER.
0 through 65535 | The data is a footnote number. This value is used with SO_FOOTNOTE only.
If wType is SO_COMMENT, no subtype is needed.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutTableCellInfo

Sets cell information.

Syntax

VOID SOPutTableCellInfo(
    PSOTABLECELLINFO pCellInfo,
    HPROC reserved
);

Parameters

pCellInfo
Address of a SOTABLECELLINFO structure containing information about the cell.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutTableRowFormat

Sets the format of a row in a table.

Syntax

VOID SOPutTableRowFormat(
    WORD wLeftEdge,
    WORD wRowHeight,
    WORD wRowHeightType,
    WORD wCellMargin,
    WORD wRowAlignment,
    WORD wNumCells,
    HPROC reserved
);

Parameters

wLeftEdge
Position, in TWIPs, of the left edge of the table, relative to the left margin.
wRowHeight
Row height, in TWIPs.
wRowHeightType
Type of height for the row. This parameter can be one of these values:
SO_HEIGHTATLEAST | Sets the row height at least as high as that given by wRowHeight.
SO_HEIGHTAUTO | Sets the row height automatically to fit text in the row.
SO_HEIGHTEXACTLY | Sets the row height exactly as given by wRowHeight.
wCellMargin
White space on either side of text in a cell within the specified cell width. It is equal to half the total white space between adjacent cells.
wRowAlignment
Alignment of row within margins. This parameter can be the SO_ALIGNLEFT, SO_ALIGNRIGHT, or SO_ALIGNCENTER value.
wNumCells
Number of cells in the row.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutTabStop

Sets a tab stop for the paragraph.

Syntax

VOID SOPutTabStop(
    PSOTAB pTabs,
    HPROC reserved
);

Parameters

pTabs
Address of the SOTAB structure containing the tab stop information.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call the SOStartTabStops function before calling this function and can set multiple tab stops for a paragraph by calling it multiple times. The file parser must not call any other output function while setting tab stops and must call the SOEndTabStops function after setting the last tab stop.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutTextCell

Outputs the text for a cell and indicates whether there is more text to be output for the cell.

Syntax

VOID SOPutTextCell(
    PSOTEXTCELL pCell,
    WORD wCount,
    char VWPTR *pText,
    HPROC reserved
);

Parameters

pCell
Address of a SOTEXTCELL structure.
wCount
Number of characters pointed to by pText. The number must not exceed 128 bytes.
pText
Address of the string of text characters to be output.
bMore
Flag that indicates there is more data. This parameter can be the SO_YES value to indicate more text to be output, or the SO_NO value to indicate none.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

If there is more text to be output, the file parser must use a subsequent call or calls to the SOPutMoreText function to output the text.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutVarField

Outputs data for a variable field and indicates whether there is more data to be output for the field.

Syntax

VOID SOPutVarField(
    void VWPTR *pData,
    WORD wCount,
    WORD *bMore,
    HPROC reserved
);

Parameters

pData
Address of the data for the variable field.
wCount
Number of bytes pointed to by pData. The number must not exceed 128 bytes.
bMore
Flag that indicates there is more data. This parameter can be the SO_YES value to indicate more data to be output, or the SO_NO value to indicate none.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

If there is more data to be output, the file parser must use a subsequent call or calls to the SOPutMoreVarField function to output the data.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPutVectorHeader

Outputs the vector header, specifying the display resolution, x- and y-axis orientation, background color, and color value type (RGB or palette).

Syntax

VOID SOPutVectorHeader(
    PSOVECTORHEADER pVectorHeader,
    HPROC reserved
);

Parameters

pVectorHeader
Address of a SOVECTORHEADER structure.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOSetDateBase

Sets the base date. All subsequent dates are calculated as the sum of the base date and the given date value.

Syntax

VOID SOSetDataBase(
    DWORD dwBase,
    WORD wFlags,
    HPROC reserved
);

Parameter

dwBase
Base number of Julian days to be automatically added to dates. All dates are entered in Julian day format in the following manner:
Jan. 1, 4713 B.C. | Julian Day 1
Jan. 1, 1 A.D. | Julian Day 1721424
Jan. 1, 1900 | Julian Day 2415021
Jan. 1, 1904 | Julian Day 2416481
Formats supporting dates before 1582 are not supported.
wFlags
Action flag. This parameter can be the SO_LOTUSHELL value to correct for the Lotus 1-2-3® 1990 leap year bug.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOStartColumnInfo

Starts the definition of column information.

Syntax

VOID SOStartColumnInfo(
    HPROC reserved
);

Parameter

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call this function immediately before setting the information. This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOStartFieldInfo

Starts the definition of field information.

Syntax

VOID SOStartFieldInfo(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser calls this function immediately before setting field information. This function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOStartFontTable

Starts the definition of a font table.

Syntax

VOID SOStartFontTable(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser must call this function immediately before setting font entries. The function can only be called from the VwStreamSectionFunc function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOStartPalette

Starts the definition of a color palette.

Syntax

VOID SOStartPalette(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

The file parser calls this function immediately before defining palette entries.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOStartTabStops

Starts the definition of tab stops for a paragraph.

Syntax

VOID SOStartTabStops(
    HPROC reserved
);

Parameters

reserved
Reserved; do not use.

Return Value

No return value.

Remarks

To set tab stops, use the SOPutTabStop function.

The file parser calls this function immediately before setting the first tab stop for the paragraph.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOVectorAttr

Sets attributes related to drawing vector graphics objects.

Syntax

VOID SOVectorAttr(
    INT nItemId,
    DWORD wDataSize,
    VOID VWPTR *pData,
    HPROC reserved
);

Parameters

nItemId
Action identifier. This parameter, which specifies the action to carry out and determines the appropriate values for wDataSize and pData, can be one of the vector attribute values in "Constants" later in this topic.
wDataSize
Size, in bytes, of data pointed to by pData.
pData
Address of a buffer containing the information used to carry out the requested action. The meaning and format of the buffer depends on the value of nItemId.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOVectorObject

Draws or defines the given vector graphics object.

Syntax

VOID SOVectorObject(
    INT nItemId,
    DWORD wDataSize,
    VOID VWPTR *pData,
    HPROC reserved
);

Parameters

nItemId
Action flag. This parameter, which specifies the action to carry out and determines the appropriate values for wDataSize and pData, can be one of the vector object values in "Constants" later in this topic.
wDataSize
Size, in bytes, of the data pointed to by pData.
pData
Address of a buffer containing the information used to carry out the requested action. The meaning and format of the buffer depends on the value of nItemId.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SUUserPopData

Pops user data. The data must have been pushed previously by using the SUUserPushData function.

Syntax

VOID SUUserPopData(
    VOID VWPTR *pData,
    HPROC reserved
);

Parameters

pData
Address of the VwStreamUserSaveType structure receiving the data.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SUUserPushData

Pushes user data. The data can be retrieved by using the SUUserPopData function.

Syntax

VOID SUUserPushData(
    VOID VWPTR *pData,
    HPROC reserved
);

Parameters

pData
Address of a VwStreamUserSaveType structure containing the data to be saved.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SUUserRetrieveData

Retrieves user data. The data must have been previously saved by using the SUUserSaveData function.

This function should not be used. The SUUserPopData function should be used instead.

Syntax

VOID SUUserRetrieveData(
    WORD wIndex,
    VOID VWPTR *pData,
    HPROC reserved
);

Parameters

wIndex
Index value specifying the data to retrieve. This value must have been previously returned by the SUUserSaveData function.
pData
Address of the VwStreamUserSaveType structure receiving the data.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SUUserSaveData

Saves user data.

This function should not be used. The SUUserPushData function should be used instead.

Syntax

VOID SUUserSaveData(
    VOID VWPTR *pData,
    HPROC reserved
);

Parameters

pData
Address of a VwStreamUserSaveType structure containing the data to be saved.
reserved
Reserved; do not use.

Return Value

Returns the index used to retrieve the data. Indexes are guaranteed to be zero-based and sequential.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamCloseFunc

Closes the file. The file parser must carry out any necessary cleanup, such as closing any other open files related to the given file.

VOID VwStreamCloseFunc(
    SOFILE hFile,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
reserved
Reserved; do not use.

Return Value

No return value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamOpenFunc

Checks the validity of the specified file and returns information about the file parser.

Syntax

INT VwStreamOpenFunc(
    SOFILE hFile,
    INT wFileId,
    U_BYTE VWPTR *pFileName,
    SOFILTERINFO VWPTR *pFilterInfo,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
wFileId
Identifier for the file.
pFileName
Address of the null-terminated string specifying the base name of the file. This string does not include path information.
pFilterInfo
Address of the SOFILTERINFO structure that receives information about the file parser.
reserved
Reserved; do not use.

Return Values

Returns the VWERR_OK value if successful, or one of the following error values otherwise:
VWERR_BADFILE | Corrupt or unreadable file
VWERR_EMPTYFILE | Empty file
VWERR_PROTECTEDFILE | Password-protected or encrypted file
VWERR_SUPFILEOPENFAILS | Supplementary file failed to open

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamReadFunc

Outputs characters, cells, or fields, depending on the current section type and file contents.

Syntax

INT VwStreamReadFunc(
    SOFILE hFile,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
reserved
Reserved; do not use.

Return Values

Returns zero if successful, or -1 if the end of the file is reached.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamReadRecordFunc

Outputs a single record by calling various stream output functions.

Syntax

VOID VwStreamReadRecordFunc(
    SOFILE hFile,
    DWORD dwData,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
dwData
Data to be saved for the record.
reserved
Reserved; do not use.

Return Value

No return value.

Remarks

This function should output a single record and then call the SOPutBreak function with the SO_RECORDBREAK value before returning. The SO_EOFBREAK and SO_SECTIONBREAK conditions do not need to be trapped by this function.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamSectionFunc

Sets the parameters for a section.

Syntax

INT VwStreamSectionFunc(
    SOFILE hFile,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
reserved
Reserved; do not use.

Return Value

Always returns zero.

Remarks

At a minimum, this function should call the SOPutSectionType and SOPutSectionName functions to set the section type and name. The function should also set the cell width if the section is a spreadsheet or the field format if the section is a database.

The display engine calls the function after calling the VwStreamOpenFunc function but before calling the VwStreamReadFunc function. It is also called after any VwStreamReadFunc that ends with a call to the SOPutBreak function with the SO_SECTIONBREAK value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamSeekFunc

Same definition as the line filters Seek function.

Syntax

INT VwStreamSeekFunc(
    SOFILE hFile,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
reserved
Reserved; do not use.

Return Value

Returns zero if successful, or -1 otherwise.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


VwStreamTellFunc

Same definition as the line filters Tell function.

Syntax

INT VwStreamTellFunc(
    SOFILE hFile,
    HPROC reserved
);

Parameters

hFile
Handle to the file for execute input and output (XIO) routines.
reserved
Reserved; do not use.

Return Value

Returns zero if successful, or -1 if the function fails.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


BrowseCallbackProc

Specifies an application-defined callback function used with the SHBrowseForFolder function. The browse dialog box calls this function to notify it about events.

int CALLBACK BrowseCallbackProc(
    HWND hwnd,
    UINT uMsg,
    LPARAM lParam,
    LPARAM lpData
    );

Parameters

hwnd
Window handle to the browse dialog box. BrowseCallbackProc can use this handle to send the following messages to the dialog box:
BFFM_ENABLEOK
Enables or disables the browse dialog box's OK button. To enable the OK button, set the message's lParam to a nonzero value. To disable the OK button, set message's lParam to zero.
BFFM_SETSELECTION
Selects the specified folder. To use a PIDL to specify the folder, set the message's lParam to the PIDL, and set wParam to FALSE. To specify the folder's path, set the message's lParam value to point to a NULL-terminated string with the path, and set wParam to TRUE.
BFFM_SETSTATUSTEXT
Sets the status text. Set the message's lParam value to point to a NULL-terminated string with the desired text.
uMsg
Value identifying the event. This can be one of the following values:
BFFM_INITIALIZED
Indicates the browse dialog box has finished initializing. The lParam value is zero.
BFFM_SELCHANGED
Indicates the selection has changed. The lParam parameter points to the item identifier list for the newly selected item.
BFFM_VALIDATEFAILED
Version 4.71. Indicates the user typed an invalid name into the edit box of the browse dialog box. The lParam parameter is the address of a character buffer that contains the invalid name. An application can use this message to inform the user that the name entered was not valid. Return zero to allow the dialog to be dismissed or nonzero to keep the dialog displayed.
lParam
Value dependent upon the message contained in the uMsg parameter.
lpData
Application-defined value that was specified in the lParam member of the BROWSEINFO structure.

Return Values

Returns zero.

See Also

SHBrowseForFolder

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: None.
Import Library: user-defined.


FMExtensionProc

Application-defined callback function called by File Manager to communicate with a File Manager extension.

LONG FMExtensionProc(
    HWND hwnd,
    WORD wMsg,
    LONG lParam
);

Parameters

hwnd
Window handle to File Manager. An extension should use this handle to specify the parent window for any dialog box or message box it must display; it should also use this handle to send query messages to File Manager.
wMsg
One of the following File Manager messages:
1 through 99 | User selected an item from the extension-supplied menu. The value is the identifier of the selected menu item.
FMEVENT_HELPMENUITEM | User pressed F1 while selecting an extension menu or toolbar command item. File Manager wants the extension to call WinHelp appropriately for the command item.
FMEVENT_HELPSTRING | User selected an extension menu or toolbar command item. File Manager wants the extension to supply a Help string.
FMEVENT_INITMENU | User selected the extension's menu. The extension should initialize items in the menu.
FMEVENT_LOAD | File Manager is loading the extension DLL and prompts the DLL for information about the menu that the DLL supplies.
FMEVENT_SELCHANGE | Selection in the File Manager directory window or Search Results window has changed.
FMEVENT_TOOLBARLOAD | File Manager is creating the toolbar and prompts the extension DLL for information about any buttons the DLL adds to the toolbar.
FMEVENT_UNLOAD | File Manager is unloading the extension DLL.
FMEVENT_USER_REFRESH | User selected the Refresh command from the Window menu. The extension should update items in the menu, if necessary.
lParam
Message-specific value.

Return Values

Returns a value dependent upon the wMsg parameter message.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.
Import Library: user-defined.


UndeleteFile

Application-defined callback function called by File Manager when the user chooses the Undelete command from the File menu.

DWORD UndeleteFile(
    HWND hwndOwner,
    LPSTR lpszDir
);

Parameters

hwndOwner
Window handle to File Manager. An undelete dynamic-link library (DLL) should use this handle to specify the owner window for any dialog box or message box the DLL might display.
lpszDir
Address of a null-terminated string that contains the name of the initial directory.

Return Values

Returns one of the following values:
-1 | An error occurred.
IDOK | A file was undeleted. File Manager repaints its window.
IDCANCEL | No file was undeleted.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in wfext.h.
Import Library: user-defined.


MAKEDLLVERULL

Used to pack DLL version information into a ULONGLONG value.

ULONGLONG MAKEDLLVERULL(
  WORD wMajorVersion,
  WORD wMinorVersion,
  WORD wBuild,
  WORD wQFE
);

Parameters

wMajorVersion
The major version number.
wMinorVersion
The minor version number.
wBuild
The build number.
wQFE
The QFE number that identifies the service pack.

Return Values

Returns the version information packed into a ULONGLONG value

Remarks

This macro is used in conjunction with DllGetVersion to pack version information into a form that can easily be compared to the ullVersion member of a DLLVERSIONINFO2 structure. It is defined as:

#define MAKEDLLVERULL(major, minor, build, qfe) \
        (((ULONGLONG)(major) << 48) | \
         ((ULONGLONG)(minor) << 32) | \
         ((ULONGLONG)(build) << 16) | \
         ((ULONGLONG)(  qfe) <<  0))

For most purposes, you only need to assign values to the major and minor version numbers. The remaining two parameters can be set to zero. The following code fragment illustrates how to use MAKEDLLVERULL to determine whether a DLL is version 4.71 or later. The VersionInfo structure is the DLLVERSIONINFO2 structure returned by DllGetVersion.

if(VersionInfo.ullVersion >= MAKEDLLVERULL(4, 71, 0,0))
{
    ...
}

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.


SOANGLETENTHS

Sets the angle in tenths of a degree.

Syntax

SOANGLETENTHS(AngleInTenthsOfADegree)

Parameters

AngleInTenthsOfADegree
New angle, in tenths of a degree.

Requirements

Windows NT: Not supported by version 5.0 or later.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPALETTEINDEX

Creates a palette-index color value.

Syntax

SOPALETTEINDEX(Index)

Parameters

Index
Valid palette entry index. When this color value is used, the system uses the color from the given palette entry.

Requirements

Windows NT: Not supported by version 5.0 or later.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPALETTERGB

Creates a palette-relative RGB color value. When this color value is specified, the system uses the palette entry that has the color that most closely matches this value.

Syntax

SOPALETTERGB(Red, Green, Blue)

Parameters

Red
Red color intensity in the range 0 to 255.
Green
Green color intensity in the range 0 to 255.
Blue
Blue color intensity in the range 0 to 255.

Requirements

Windows NT: Not supported by version 5.0 or later.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SORGB

Creates an RGB color value.

Syntax

SORGB(Red, Green, Blue)

Parameters

Red
Red color intensity in the range 0 to 255.
Green
Green color intensity in the range 0 to 255.
Blue
Blue color intensity in the range 0 to 255.

Requirements

Windows NT: Not supported by version 5.0 or later.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOSETRATIO

Sets the ratio.

Syntax

SOSETRATIO(Numerator, Denominator)

Parameters

Numerator
Numerator of the ratio factor. This value must be in the range 0 to 65,535.
Denominator
Denominator of the ratio factor. This value must be in the range 0 to 65,535.

Requirements

Windows NT: Not supported by version 5.0 or later.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


ChrCmpI

Performs a comparison between two characters. The comparison is not case sensitive.

BOOL ChrCmpIW(
    WCHAR w1,
    WCHAR w2
    );

BOOL ChrCmpIA(
    WORD w1,
    WORD w2
    );

Parameters

w1
First character to be compared.
w2
Second character to be compared.

Return Values

Returns zero if the two characters are the same, or nonzero otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IntlStrEqN

Performs a case-sensitive comparison of a specified number of characters from the beginning of two localized strings.

BOOL IntlStrEqN(
  LPCTSTR pszStr1,
  LPCTSTR pszStr2,
  int nChar
);

Parameters

pszStr1
[in] Pointer to a NULL-terminated string.
pszStr2
[in] Pointer to a NULL-terminated string.
nChar
[in] Number of characters to be compared, starting from the beginning of the strings.

Return Values

Returns TRUE if the first nChar characters are identical, or FALSE otherwise.

Remarks

This function retrieves the thread locale and uses CompareString to do a case-sensitive comparison of the first nChar characters. It is equivalent to:

IntlStrEqWorker( TRUE, pszStr1, pszStr2, nChar)

See Also

IntlStrEqWorker

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IntlStrEqNI

Performs a case-insensitive comparison of a specified number of characters from the beginning of two localized strings.

BOOL IntlStrEqNI(
  LPCTSTR pszStr1,
  LPCTSTR pszStr2,
  int nChar
);

Parameters

pszStr1
[in] Pointer to a NULL-terminated string.
pszStr2
[in] Pointer to a NULL-terminated string.
nChar
[in] Number of characters to be compared, starting from the beginning of the strings.

Return Values

Returns TRUE if the first nChar characters are identical, or FALSE otherwise.

Remarks

This function retrieves the thread locale and uses CompareString to do a case-insensitive comparison of the first nChar characters. It is equivalent to:

IntlStrEqWorker( FALSE, pszStr1, pszStr2, nChar)

See Also

IntlStrEqWorker

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


IntlStrEqWorker

Compares a specified number of characters from the beginning of two localized strings.

BOOL IntlStrEqWorker(
  BOOL fCaseSens,
  LPCTSTR pszStr1,
  LPCTSTR pszStr2,
  int nChar
);

Parameters

fCaseSens
[in] Value that is set to TRUE for a case-sensitive comparison, or to FALSE for a case-insensitive comparison.
pszStr1
[in] Pointer to a NULL-terminated string.
pszStr2
[in] Pointer to a NULL-terminated string.
nChar
[in] Number of characters to be compared, starting from the beginning of the strings.

Return Values

Returns TRUE if the first nChar characters are identical, or FALSE otherwise.

Remarks

This function retrieves the thread locale and uses CompareString to determine whether the first nChar characters are identical.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


MLLoadLibrary

Maps an executable module, specified by its file name and registry subkey, into the address space of the calling function. It supports multilanguage applications by determining the LCID and loading the appropriate DLL or EXE.

HINSTANCE MLLoadLibrary(
    LPCTSTR lpLibFileName,
    HANDLE hFile,
    DWORD dwFlags,
    LPCTSTR lpComponent,
    BOOL bCrossCodePage
);

Parameters

lpszLibFileName
Null-terminated string with the file name of the EXE or DLL to be loaded. It should not include any path information. MLLoadLibrary will extract that from the registry.
hFile
Reserved. NULL must be passed.
dwFlags
Action to be taken when loading the module. This can be one of the following:
DONT_RESOLVE_DLL_REFERENCE | If the executable module is a DLL, the system does not call DllMain for process and thread initialization and termination.
LOAD_LIBRARY_AS_DATAFILE | The system maps the file into the calling process's virtual address space as if it were a data file.
lpComponent
Name of the component's subkey. The function assumes that the component is located under HKEY_LOCAL_MACHINE\\Software\\Microsoft\\Windows\\CurrentVersion\\App Paths.
bCrossCodePage
Reserved. Null must be passed.

Return Values

Returns a handle to the module if successful, or NULL otherwise.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.


SHRegGetInt Function

Reads a numeric string value from the registry and converts it to an integer.

Syntax

int SHRegGetInt(
    HKEY hk,
    LPCWSTR szKey,
    int nDefault
);

Parameters

hk
[in] Handle to the registry key that specifies the value to be read.
szKey
[in] Pointer to a string value that specifies the name of the value to be read. The string must be null-terminated.
nDefault
[in] Integer that specifies the value returned if the registry value cannot be retrieved successfully.

Return Value

Returns the converted string as an integer, or the default value specified by nDefault.

Function Information

Stock Implementation | shlwapi.dll version 5.00 or later
Custom Implementation | No
Header | shlwapi.h
Import library | shlwapi.lib
Minimum operating systems | Windows NT 2000


SHStrDup

Makes a copy of a string in newly allocated memory.

HRESULT SHStrDup(
  LPCTSTR pszSource,
  LPWSTR *ppwszTarget
);

Parameters

pszSource
[in] Pointer to the string to be copied.
ppwszTarget
[out] Pointer to an allocated Unicode string containing the result. SHStrDup allocates memory for this string with CoTaskMemAllocate. You should free the string with CoTaskMemFree when it is no longer needed.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This function will take either Unicode or ANSI strings as input, but the copied string is always Unicode.

This function uses CoTaskMemAlloc to allocate memory for the copied string. You must free this memory with CoTaskMemFree when it is no longer needed.

See Also

StrDup

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCat

Appends one string to another.

LPTSTR StrCat(
    LPTSTR psz1,
    LPCTSTR psz2,
);

Parameters

psz1
[in/out] Address of a null-terminated string to be appended to. It must be large enough to hold both strings.
psz2
[in] Address of the string to be appended to psz1.

Return Values

Returns a pointer to psz1, which holds the combined strings.

Security Remarks

The first argument, psz1, must be large enough to hold psz2 and the closing '\0', otherwise a buffer overrun may occur. Buffer overruns may lead to a denial of service attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker to inject executable code into your process, especially if psz1 is a stack-based buffer.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCatBuff

Copies and appends characters from one string to the end of another.

LPTSTR StrCatBuff(
  LPTSTR pszDestination,
  LPCTSTR pszSource,
  int cchDestBuffSize
);

Parameters

pszDestination
[in/out] Pointer to a null-terminated string. When the function returns, the characters from pszSource will be appended to it.
pszSource
Pointer to the string to be appended to pszDestination.
cchDestBuffSize
Size of the buffer pointed to by pszDestination. This value must be greater than the length of the combined string, or it will be truncated to fit.

Return Values

Returns a pointer to the destination string.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrChr

Searches a string for the first occurrence of a character that matches the specified character. The comparison is case sensitive.

LPWSTR StrChrW(
    LPCWSTR lpStart,
    WCHAR wMatch
    );

LPSTR StrChrA(
    LPCSTR lpStart,
    WORD wMatch
    );

Parameters

lpStart
Address of the string to be searched.
wMatch
Character to be used for comparison.

Return Values

Returns the address of the first occurrence of the character in the string if successful, or NULL otherwise.

Remarks

The comparison assumes lpStart points to the start of a null-terminated string.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrChrI

Searches a string for the first occurrence of a character that matches the specified character. The comparison is not case sensitive.

LPWSTR StrChrIW(
    LPCWSTR lpStart,
    WCHAR wMatch
    );

LPSTR StrChrIA(
    LPCSTR lpStart,
    WORD wMatch
    );

Parameters

lpStart
Address of the string to be searched.
wMatch
Character to be used for comparison.

Return Values

Returns the address of the first occurrence of the character in the string if successful, or NULL otherwise.

Remarks

The comparison assumes lpStart points to the start of a null-terminated string.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCmp

Compares two strings to determine if they are the same. The comparison is case-sensitive.

int StrCmp(
    LPCTSTR lpStr1,
    LPCTSTR lpStr2
);

Parameters

lpStr1
[in] Pointer to the first string to be compared.
lpStr2
[in] Pointer to the second string to be compared.

Return Values

Returns zero if the strings are identical. Returns a positive value if the string pointed to by lpStr1 is greater than that pointed to by lpStr2. Returns a negative value if the string pointed to by lpStr1 is less than that pointed to by lpStr2.

Remarks

This function returns the difference in value of the first unequal characters it encounters, or zero if they are all equal. For example, if lpStr1="abczb" and lpStr2 = "abcdefg", StrCmp determines that "abczb" is greater than "abcdefg" and returns z - d.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCmpI

Compares two strings to determine if they are the same. The comparison is not case-sensitive.

int StrCmpI(
    LPCTSTR lpStr1,
    LPCTSTR lpStr2
);

Parameters

lpStr1
[in] Address of the first string to be compared.
lpStr2
[in] Address of the second string to be compared.

Return Values

Returns zero if the strings are identical. Returns a positive value if the string pointed to by lpStr1 is greater than that pointed to by lpStr2. Returns a negative value if the string pointed to by lpStr1 is less than that pointed to by lpStr2.

Remarks

This function returns the difference in value of the first unequal characters it encounters, or zero if they are all equal. For example, if lpStr1="Abczb" and lpStr2 = "abCdefg", StrCmpI determines that "Abczb" is greater than "abCdefg" and returns z - d.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCmpN

Compares a specified number of characters from the beginning of two strings to determine if they are the same. The comparison is case-sensitive.

int StrCmpN(
    LPCTSTR lpStr1,
    LPCTSTR lpStr2,
    int nChar
);

Parameters

lpStr1
[in] Pointer to the first string to be compared.
lpStr2
[in] Pointer to the second string to be compared.
nChar
[in] Number of characters from the beginning of each string to be compared.

Return Values

Returns zero if the strings are identical. Returns a positive value if the first nChar characters of the string pointed to by lpStr1are greater than those from the string pointed to by lpStr2. It returns a negative value if the first nChar characters of the string pointed to by lpStr1 are less than those from the string pointed to by lpStr2.

Remarks

The StrNCmp macro differs from this function in name only.

This function compares the first nChar characters of the two strings. It returns zero if they are all equal or the difference in value of the first unequal characters it encounters. For example, if lpStr1="Abczb", lpStr2 = "abCdefg", and nChar = 4, StrCmpN determines that "abCdefg" is greater than "Abczb" and returns A-a.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCmpNI

Compares a specified number of characters from the beginning of two strings to determine if they are the same. The comparison is not case-sensitive.

int StrCmpNI(
    LPCTSTR lpStr1,
    LPCTSTR lpStr2,
    int nChar
);

Parameters

lpStr1
[in] Pointer to the first string to be compared.
lpStr2
[in] Pointer to the second string to be compared.
nChar
[in] Number of characters from the beginning of each string to be compared.

Return Values

Returns zero if the strings are identical. Returns a positive value if the first nChar characters of the string pointed to by lpStr1are greater than those from the string pointed to by lpStr2. It returns a negative value if the first nChar characters of the string pointed to by lpStr1 are less than those from the string pointed to by lpStr2.

Remarks

The StrNCmpI macro differs from this function in name only.

This function compares the first nChar characters of the two strings. It returns zero if they are all equal or the difference in value of the first unequal characters it encounters. For example, if lpStr1="Abczb", lpStr2 = "abCdefg", and nChar = 4, StrCmpNI determines that "Abczb" is greater than "abCdefg" and returns z - d.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCpy

Copies one string to another.

LPTSTR StrCpy(
    LPTSTR psz1,
    LPCTSTR psz2,
);

Parameters

psz1
[out] Address of the destination string.
psz2
[in] Address of the source string.

Return Values

Returns a pointer to psz1.

Security Remarks

The first argument, psz1, must be large enough to hold psz2 and the closing '\0', otherwise a buffer overrun may occur. Buffer overruns may lead to a denial of service attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker to inject executable code into your process, especially if psz1 is a stack-based buffer. Consider using StrCpyN instead of StrCpy.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCpyN

Copies a specified number of characters from the beginning of one string to another. The StrNCpy macro differs from this function in name only.

LPTSTR StrCpyN(
    LPTSTR psz1,
    LPCTSTR psz2,
    int cchMax
    );

#define StrNCpy StrCpyN

Parameters

psz1
[out] Pointer to a NULL-terminated string to hold the copied characters.
psz2
[in] Pointer to the source string.
cchMax
[in] Number of characters to be copied, including the terminating NULL character.

Return Values

Returns a pointer to psz1.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
  //String one
  char buffer_1[ ] = "ABCDEFG";
  char *lpStr1;
  lpStr1 = buffer_1;

  //String two
  char buffer_2[ ] = "HIJKLMN";
  char *lpStr2;
  lpStr2 = buffer_2;

  cout  <<  "The function StrCpyN will allow you to copy (n) numbers"
  <<  "\nof characters from the string 2 to string 1."
  <<  "\nString 1 is : "<< lpStr1
  <<  "\nString 2 is : "<< lpStr2
  <<  "\nCopy (n) from 2 onto 1" << endl;
cout  <<  StrCpyN(lpStr1,lpStr2,8)
}

OUTPUT:
- - - - - -
The function StrCpyN will allow you to copy (n) numbers
of characters from the string 2 to string 1.
String 1 is : ABCDEFG
String 2 is : HIJKLMN
Copy (n) from 2 onto 1
HIJKLMN

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCSpn

Searches a string for the first occurrence of any of a group of characters. The search method is case-sensitive, and the NULL terminator is included within the search pattern match.

int StrCSpn(
    LPCTSTR lpStr,
    LPCTSTR lpSet
);

Parameters

lpStr
[in] Pointer to the null-terminated string to be searched.
lpSet
[in] Pointer to a null-terminated string containing the characters to search for.

Return Values

Returns the index of the first occurrence in lpStr of any character from lpSet, or the length of lpStr if no match is found.

Remarks

The return value of this function is equal to the length of the initial substring in lpStr that does not include any characters from lpSet.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrCSpnI

Searches a string for the first occurrence of any of a group of characters. The search method is not case-sensitive, and the NULL terminator is included within the search pattern match.

int StrCSpnI(
    LPCTSTR lpStr,
    LPCTSTR lpSet
);

Parameters

lpStr
[in] Pointer to the null-terminated string to be searched.
lpSet
[in] Pointer to a null-terminated string containing the characters to search for.

Return Values

Returns the index of the first occurrence in lpStr of any character from lpSet, or the length of lpStr if no match is found.

Remarks

The return value of this function is equal to the length of the initial substring in lpStr that does not include any characters from lpSet.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrDup

Duplicates a string.

LPTSTR StrDup(
    LPCTSTR lpsz
);

Parameters

lpsz
Address of a constant null-terminated character string.

Return Values

Returns the address of the string that was copied, or NULL if the string cannot be copied.

Example

This simple console application illustrates the use of StrDup.

#include <windows.h>
#include <shlwapi.h>
#include <stdio.h>

void main( void )
{
   char buffer[ ] = "This is the buffer text";
   char *newstring;
   printf( "Original: %s\n", buffer );
   newstring = StrDup( buffer );
   printf( "Copy:     %s\n", newstring );
   LocalFree( newstring );
}

   OUTPUT:
   - - - - - -
   Original: This is the buffer text
   Copy:     This is the buffer text

Remarks

Note This function uses LocalAlloc to allocate storage space for the copy of the string. The calling application must free this memory by calling the LocalFree function on the pointer returned by the call to StrDup.

StrDup will allocate storage the size of the original string. If storage allocation is successful, the original string is copied to the duplicate string.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrFormatByteSize

Converts a numeric value into a string that represents the number expressed as a size value in bytes, kilobytes, megabytes, or gigabytes, depending on the size.

LPTSTR StrFormatByteSizeA(
    DWORD dw,
    LPSTR pszBuf,
    UINT cchBuf
);

LPTSTR StrFormatByteSizeW(
    LONGLONG qdw,
    LPWSTR pwszBuf,
    UINT cchBuf
);

Parameters

dw / qdw
[in] Numeric value to be converted.
pszBuf / pwszBuf
[out] Pointer to the converted string.
cchBuf
[in] Size of pszBuf, in characters.

Return Values

Returns the address of the converted string, or NULL if the conversion fails.

Example

       532 -> 532 bytes
      1340 -> 1.3KB
     23506 -> 23.5KB
   2400016 -> 2.4MB
2400000000 -> 2.4GB

Remarks

The first parameter of this function has a different type for the ANSI and Unicode versions. If your numeric value is a DWORD, you can use StrFormatByteSize with text macros for both cases. The compiler will cast the numerical value to a LONGLONG for the Unicode case. If your numerical value is a LONGLONG, you should use StrFormatByteSizeW explicitly.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrFormatByteSize64A

StrFormatByteSize64

Converts a numeric value into a string that represents the number expressed as a size value in bytes, kilobytes, megabytes, or gigabytes, depending on the size.

LPSTR StrFormatByteSize64(
  LONGLONG qdw,
  LPTSTR pszBuf,
  UINT uiBufSize
);

Parameters

qdw
[in] Numeric value to be converted.
pszBuf
[out] Pointer a buffer to hold the converted number.
uiBufSize
[in] Size of pszBuf, in characters.

Return Values

Returns the address of the converted string, or NULL if the conversion fails.

Remarks

The following table illustrates how this function converts a numeric value into a text string.

Numeric value | Text string
532 | 532 bytes
1340 | 1.30KB
23506 | 22.9KB
2400016 | 2.29MB
2400000000 | 2.23GB

See Also

StrFormatByteSize

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrFormatKBSize

Converts a numeric value into a string that represents the number expressed as a size value in kilobytes.

LPTSTR StrFormatKBSize(
  LONGLONG qdw,
  LPTSTR pszBuf,
  UINT uiBufSize
);

Parameters

qdw
[in] Numeric value to be converted.
pszBuf
[out] Pointer to a buffer to hold the converted number.
uiBufSize
[in] Size of pszBuf, in characters.

Return Values

Returns a pointer to the converted string, or NULL if the conversion fails.

See Also

StrFormatByteSize

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrFromTimeInterval

Converts a time interval, specified in milliseconds, to a string.

int StrFromTimeInterval(
    LPTSTR pszOut,
    UINT cchMax,
    DWORD dwTimeMS,
    int digits
    );

Parameters

pszOut
[out] Pointer to a character buffer that receives the converted string.
cchMax
[in] Size of pszOut, in characters. If cchMax is set to zero, StrFromTimeInterval will return the minimum size of the character buffer needed to hold the converted string. In this case, pszOut will not contain the converted string.
dwTimeMS
[in] Time interval, in milliseconds.
digits
[in] Maximum number of digits to be represented in pszOut. Some examples are:
dwTimeMS | digits | pszOut
34000 | 3 | 34 sec
34000 | 2 | 34 sec
34000 | 1 | 30 sec
74000 | 3 | 1 min 14 sec
74000 | 2 | 1 min 10 sec
74000 | 1 | 1 min

Return Values

Returns the number of characters in pszOut, excluding the NULL terminator.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
char TimeString[256];
char *pszOut;
pszOut = TimeString;

cout << "The return value from the call to"
 << "\nthe function StrFromTimeInterval will"
 << "\nreturn the number of elements in the buffer: " << endl;

cout << "\nThe return from StrFromTimeInterval is "
     << StrFromTimeInterval(pszOut,30, 34000,30);
cout << "\nThe contents of the TimeString Buffer " << pszOut << endl;

cout << "The return from StrFromTimeInterval is "
     << StrFromTimeInterval(pszOut,30, 74000,3);
cout << "\nThe contents of the TimeString Buffer " << pszOut << endl;

cout << "The return from StrFromTimeInterval is "
     << StrFromTimeInterval(pszOut,30, 74000,2);
cout << "\nThe contents of the TimeString Buffer " << pszOut << endl;

cout << "The return from StrFromTimeInterval is "
     << StrFromTimeInterval(pszOut,30, 74000,1)
     << "\nThe contents of the TimeString Buffer " << pszOut << endl;

}

OUTPUT:
- - - - -
The return value from the call to
the function StrFromTimeInterval will
return the number of elements in the buffer:

The return from StrFromTimeInterval is 7
The contents of the TimeString Buffer  34 sec
The return from StrFromTimeInterval is 13
The contents of the TimeString Buffer  1 min 14 sec
The return from StrFromTimeInterval is 13
The contents of the TimeString Buffer  1 min 10 sec
The return from StrFromTimeInterval is 6
The contents of the TimeString Buffer  1 min

Remarks

The time value returned in pzsOut will always be in the form hh hours mm minutes ss second. Times that exceed twenty four hours are not converted to days or months. Fractions of seconds are ignored.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrIsIntlEqual

Compares a specified number of characters from the beginning of two strings to determine if they are equal.

BOOL StrIsIntlEqual(
    BOOL fCaseSens,
    LPCTSTR lpString1,
    LPCTSTR lpString2,
    int nChar
);

Parameters

fCaseSens
Determines the case sensitivity of the comparison. If this value is nonzero, the comparison is case-sensitive. If this value is zero, the comparison is not case-sensitive.
lpString1
Pointer to the first string to be compared.
lpString2
Pointer to the second string to be compared.
nChar
Number of characters from the beginning of each string to be compared.

Return Values

Returns TRUE if the first nChar characters from the two strings are equal, or FALSE otherwise.

Remarks

You can set case sensitivity with the StrIntlEqN and StrIntlEqNI macros. StrIntlEqN performs a case-sensitive comparison, and StrIntlEqNI performs a case-insensitive comparison.

The syntax of the two macros is:
#define StrIntlEqN(s1, s2, nChar) StrIsIntlEqual(TRUE, s1, s2, nChar)
#define StrIntlEqNI(s1, s2, nChar) StrIsIntlEqual(FALSE, s1, s2, nChar)

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrNCat

Appends a specified number of characters from the beginning of one string to the end of another. The StrCatN macro is identical to this function.

LPTSTR StrNCat(
    LPTSTR pszFront,
    LPCTSTR pszBack,
    int cchMax
    );

Parameters

pszFront
[in/out] Address of a NULL-terminated string to which the characters from pszBack will be appended. It must be large enough to hold the combined strings.
pszBack
[in] Address of the string to be appended.
cchMax
[in] Number of characters to be appended to pszFront from the beginning of pszBack.

Return Values

Returns a pointer to pszFront, which holds the combined string.

Security Remarks

The first argument, pszFront, must be large enough to hold pszBack and the closing '\0', otherwise a buffer overrun may occur. Buffer overruns may lead to a denial of service attack against the application if an access violation occurs. In the worst case, a buffer overrun may allow an attacker to inject executable code into your process, especially if psz1 is a stack-based buffer. Be aware that the last argument, cchMax, is the number of bytes to copy into pszFront, not the size of the pszFront.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrPBrk

Searches a string for the first occurrence of a character contained in a specified buffer. This search does not include the null terminator.

LPTSTR StrPBrk(
    LPCTSTR psz,
    LPCTSTR pszSet
    );

Parameters

psz
Address of the string to be searched.
pszSet
Address of a null-terminated character buffer that contains the characters for which to search.

Return Values

Returns the address in psz of the first occurrence of a character contained in the buffer at pszSet, or NULL if no match is found.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrRChr

Searches a string for the last occurrence of a specified character. The comparison is case-sensitive.

LPWSTR StrRChrW(
    LPCWSTR lpStart,
    LPCWSTR lpEnd,
    WCHAR wMatch
);

LPSTR StrRChrA(
    LPCSTR lpStart,
    LPCSTR lpEnd,
    WORD wMatch
);

Parameters

lpStart
[in] Pointer to the null-terminated string to be searched.
lpEnd
[in] Pointer into the source string that defines the range of the search. Set lpEnd to point to a character in the string and the search will stop with the preceding character. Set lpEnd to NULL to search the entire string.
wMatch
[in] Character to search for.

Return Values

Returns a pointer to the last occurrence of the character in the string, if successful, or NULL if not.

Remarks

The comparison assumes that lpEnd points to the end of the string.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrRChrI

Searches a string for the last occurrence of a specified character. The comparison is not case-sensitive.

LPWSTR StrRChrIW(
    LPCWSTR lpStart,
    LPCWSTR lpEnd,
    WCHAR wMatch
);

LPSTR StrRChrIA(
    LPCSTR lpStart,
    LPCSTR lpEnd,
    WORD wMatch
);

Parameters

lpStart
[in] Pointer to the NULL-terminated string to be searched.
lpEnd
[in] Pointer into the source string that defines the range of the search. Set lpEnd to point to a character in the string and the search will stop with the preceding character. Set lpEnd to NULL to search the entire string.
wMatch
[in] Character to search for.

Return Values

Returns a pointer to the last occurrence of the character in the string if successful, or NULL if not.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrRetToBuf

Takes a STRRET structure returned by IShellFolder::GetDisplayNameOf, converts it to a string, and places the result in a buffer.

HRESULT StrRetToBuf(
    LPSTRRET pstr,
    LPCITEMIDLIST pidl,
    LPTSTR pszBuf,
    UINT cchBuf
);

Parameters

pstr
[in] Pointer to the STRRET structure. When the function returns, this pointer will no longer be valid.
pidl
[in] Pointer to the item's ITEMIDLIST structure.
pszBuf
[out] Buffer to hold the display name. It will be returned as a null-terminated string. If cchBuf is too small, the name will be truncated to fit.
cchBuf
[in] Size of pszBuf, in characters. If cchBuf is too small, the string will be truncated to fit.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

Remarks

If the uType member of the structure pointed to by pstr is set to STRRET_WSTR, the pOleStr member of that structure will be freed on return.

See Also

StrRetToStr

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrRetToStr

Takes a STRRET structure returned by IShellFolder::GetDisplayNameOf and returns a pointer to an allocated string containing the display name.

HRESULT StrRetToStr(
  LPSTRRET pstr,
  LPCITEMIDLIST pidl,
  LPTSTR *ppszName
);

Parameters

pstr
[in] Pointer to the STRRET structure. When the function returns, this pointer will no longer be valid.
pidl
[in] Pointer to the item's ITEMIDLIST structure.
ppszName
[out] Pointer to an allocated string containing the result. StrRetToStr allocates memory for this string with CoTaskMemAllocate. You should free the string with CoTaskMemFree when it is no longer needed.

Return Values

Returns S_OK if successful, or an OLE error code otherwise.

See Also

StrRetToBuf

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrRStrI

Searches for the last occurrence of a specified substring within a string. The comparison is not case sensitive.

LPTSTR StrRStrI(
    LPCTSTR pszSource,
    LPCTSTR pszLast,
    LPCTSTR pszSrch
    );

Parameters

pszSource
[in] Pointer to a NULL-terminated source string.
pszLast
[in] Pointer into the source string that defines the range of the search. Set pszLast to point to a character in the source string, and the search will stop with the preceding character. Set pszLast to NULL to search the entire source string.
pszSrch
[in] Pointer to the substring to search for.

Return Values

Returns the address of the last occurrence of the substring if successful, or NULL otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrSpn

Obtains the length of a substring within a string that consists entirely of characters contained in a specified buffer.

int StrSpn(
    LPCTSTR psz,
    LPCTSTR pszSet
    );

Parameters

psz
Address of the string that is to be searched.
pszSet
Address of a null-terminated character buffer that contains the set of characters for which to search.

Return Values

Returns the length, in characters, of the matching string or zero if no match is found.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrStr

Finds the first occurrence of a substring within a string. The comparison is case sensitive.

LPTSTR StrStr(
    LPCTSTR lpFirst,
    LPCTSTR lpSrch
    );

Parameters

lpFirst
Address of the string being searched.
lpSrch
Substring to search for.

Return Values

Returns the address of the first occurrence of the matching substring if successful, or NULL otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrStrI

Finds the first occurrence of a substring within a string. The comparison is not case sensitive.

LPTSTR StrStrI(
    LPCTSTR lpFirst,
    LPCTSTR lpSrch
    );

Parameters

lpFirst
Address of the string being searched.
lpSrch
Substring to search for.

Return Values

Returns the address of the first occurrence of the matching substring if successful, or NULL otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrToInt

Converts a decimal string to an integer. The StrToLong macro differs from this function in name only.

int StrToInt(
    LPCTSTR lpSrc
    );

#define StrToLong StrToInt

Parameters

lpSrc
Address of the null-terminated string to be converted.

Return Values

Returns the INT value of a string.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrToIntEx

Converts a decimal or hexadecimal string to an integer.

BOOL StrToIntEx(
    LPCTSTR pszString,
    DWORD dwFlags,
    int FAR * piRet
    );

Parameters

pszString
Address of a null-terminated string to be converted.
dwFlags
Specifies if pszString contains a decimal or hexadecimal value. This can be one of the following values:
STIF_DEFAULT | pszString contains a decimal value.
STIF_SUPPORT_HEX | pszString contains a hexadecimal value.
piRet
Address of an integer variable that receives the converted string.

Return Values

Returns TRUE if the string is converted, or FALSE otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrToInt64Ex

Converts a decimal or hexadecimal string to a 64-bit integer.

BOOL StrToInt64Ex(
    LPCTSTR pszString,
    DWORD dwFlags,
    LONGLONG * pllRet
    );

Parameters

pszString
Address of a null-terminated string that is to be converted.
dwFlags
Variable of type DWORD that specifies if pszString contains a decimal or hexadecimal value. This can be one of the following values:
STIF_DEFAULT | pszString contains a decimal value.
STIF_SUPPORT_HEX | pszString contains a hexadecimal value.
pllRet
Address of a variable of type LONGLONG that receives the converted string.

Return Values

Returns TRUE if the string is converted, or FALSE otherwise.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


StrTrim

Removes (trims) specified leading and trailing characters from a string.

BOOL StrTrim(
    LPTSTR pszSource,
    LPCTSTR pszTrimChars
    );

Parameters

pszSource
[in/out] Pointer to the string to be trimmed. On return, pszSource will hold the trimmed string.
pszTrimChars
[in] Pointer to a null-terminated string containing the characters that will be trimmed from psz.

Return Values

Returns TRUE if any characters were removed, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
  //String one
  TCHAR buffer[ ] = TEXT("_!ABCDEFG#");
  TCHAR trim[ ] = TEXT("#A!_\0");

  cout  <<  "The string before calling StrTrim: ";
  cout  <<  buffer;
  cout  <<  "\n";

  StrTrim(buffer, trim);

  cout  <<  "The string after calling StrTrim: ";
  cout  <<  buffer;
  cout  <<  "\n";

}

OUTPUT:
- - - - - -
The string before calling StrTrim: _!ABCDEFG#
The string after calling StrTrim: BCDEFG

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


wnsprintf

Takes a variable-length argument list and returns the values of the arguments as a printf-style formatted string.

int wnsprintf(
    LPTSTR lpOut,
    int cchLimitIn
    LPCTSTR pszFmt,
    ...
);

Parameters

lpOut
[out] Buffer to hold the output string.
cchLimitIn
[in] Maximum number of characters allowed in lpOut.
pszFmt
[in] printf-style format string.

Return Values

Returns the number of characters written to the buffer, excluding any terminating NULL characters. A negative value is returned if an error occurs.

Remarks

This is a Microsoft® Windows® version of sprintf. It does not support floating point or pointer types. It supports only the left alignment flag.

The Unicode version of wsprintf () is not implemented for Windows 95. Use the Unicode version of this function (wnsprintfW) instead of wsprintfW.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


wvnsprintf

Takes list of arguments and returns the values of the arguments as a printf-style formatted string.

int wvnsprintf(
    LPTSTR lpOut,
    int cchLimitIn,
    LPCTSTR pszFmt,
    va_list arglist
);

Parameters

lpOut
[out] Buffer to hold the output string.
cchLimitIn
[in] Maximum number of characters allowed in lpOut.
pszFmt
[in] printf-style format string.
arglist
[in] Pointer to a list of parameters.

Return Values

Returns the number of characters written to the buffer, excluding any terminating NULL characters. A negative value is returned if an error occurs.

Remarks

This is a Microsoft® Windows® version of vsprintf(). It does not support floating point or pointer types. It supports only the left alignment flag.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathAddBackslash

Adds a backslash to the end of a string to create the correct syntax for a path. If the source path already has a trailing backslash, no backslash will be added.

LPTSTR PathAddBackslash(
    LPTSTR lpszPath
    );

Parameters

lpszPath
[in/out] Pointer to a buffer with a string that represents a path. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.

Return Values

Returns the address of the NULL that terminates the string.

Example
#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
    // String for path name without backslash.
    char buffer_1[MAX_PATH] = "C:\\dir_name\\dir_name\\file_name";
    char *lpStr1;
    lpStr1 = buffer_1;

    // String for path name with backslash.
    char buffer_2[MAX_PATH] = "C:\\dir_name\\dir_name\\file_name\\";
    char *lpStr2;
    lpStr2 = buffer_2;

    cout << "The original path string 1 is " << lpStr1 << endl;
    cout << "The modified path string 1 is "
        <<  PathAddBackslash(lpStr1)   << lpStr1 << endl;

    cout << "\nThe original path string 2 is " << lpStr2 << endl;
    cout << "The modified path string 2 is "
        <<  PathAddBackslash(lpStr2)   << lpStr2 << endl;

}
OUTPUT:
---------
The original path string 1 is C:\dir_name\dir_name\file_name
The modified path string 1 is C:\dir_name\dir_name\file_name\

The original path string 2 is C:\dir_name\dir_name\file_name\
The modified path string 2 is C:\dir_name\dir_name\file_name\

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathAddExtension

Adds a file extension to a path string.

BOOL PathAddExtension(
    LPTSTR  pszPath,
    LPCTSTR pszExtension
    );

Parameters

pszPath
[in/out] Pointer to a buffer with the NULL-terminated string to which the file extension will be appended. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
pszExtension
[in] Pointer to the string that contains the file extension.

Return Values

Returns TRUE if an extension was added, or FALSE otherwise.

Example
#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
     // String for path name without file extension.
     char buffer_1[MAX_PATH] = "file";
     char *lpStr1;
     lpStr1 = buffer_1;

     // String for path name with file extension.
     char buffer_2[ ] = "file.doc";
     char *lpStr2;
     lpStr2 = buffer_2;

     // String for extension name.
     char F_Ext[MAX_PATH] = ".txt";
     char *lpStr3;
     lpStr3 = F_Ext;

     // Null string as path.
     char N_String[MAX_PATH] = "\0";
     char *lpStr4;
     lpStr4 = N_String;

     // Path 1 without the file extension.
     cout << "The original path string 1 is  " << lpStr1 << endl;

     int ret_1 = PathAddExtension(lpStr1,lpStr3);
     cout << "The modified path string 1 is  " << lpStr1 << endl;

    // Path 2 with the file extension already there.
    cout << "The original path string 2 is  " << lpStr2 << endl;
    int ret_2 = PathAddExtension(lpStr2,lpStr3);
    cout << "The modified path string 2 is  " << lpStr2<< endl;

    // Path 3 null string as a path.
    int ret_3 = PathAddExtension(lpStr4,lpStr3);
    cout << "The return value is " << ret_3<< endl;
    cout << "The modified path on a null string is " << lpStr4<< endl;

}
OUTPUT:
-----------------------
The original path string 1 is  file
The modified path string 1 is  file.txt
The original path string 2 is  file.doc
The modified path string 2 is  file.doc
The return value is 1
The modified path on a null string is .txt
The return value is 1

Remarks

If there is already a file extension present, no extension will be added. If the pszPath points to a NULL string, the result will be the file extension only. If pszExtension points to a NULL string, an ".exe" extension will be added.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathAppend

Appends one path to the end of another.

BOOL PathAppend(
    LPTSTR  pszPath,
    LPCTSTR pszMore
    );

Parameters

pszPath
[in/out] Pointer to a buffer with the NULL-terminated string to which the file name will be appended. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
pszMore
[in] Address of the string that represents the file name.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
    // String for path name.
    char buffer_1[MAX_PATH] = "name_1\\name_2";
    char *lpStr1;
    lpStr1 = buffer_1;

    // String of what is being added.
    char buffer_2[ ] = "name_3";
    char *lpStr2;
    lpStr2 = buffer_2;

    cout << "The original path string is    " << lpStr1 << endl;
    cout << "The part to append to end is   " << lpStr2 << endl;
    bool ret = PathAppend(lpStr1,lpStr2);
    cout << "The appended path string is    " << lpStr1 << endl;
}

OUTPUT:
---------
The original path string is    name_1\name_2
The part to append to end is   name_3
The appended path string is    name_1\name_2\name_3

Remarks

This function automatically inserts a backslash between the two strings, if one is not already present.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathBuildRoot

Creates a root path from a given drive number.

LPTSTR PathBuildRoot(
    LPTSTR szRoot,
    int iDrive
    );

Parameters

szRoot
Pointer to the string that receives the constructed root path. This buffer must be at least four characters in size.
iDrive
Integer that indicates the desired drive number. It should be between 0 and 25.

Return Values

Returns the address of the constructed root path. If the call fails for any reason (for example, an invalid drive number), szRoot is returned unchanged.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
    // String for root name
    char buffer_1[4];
    char *lpStr1;
    lpStr1 = buffer_1;

    // Generate a root path based on the drive number (0/25)
    // "Example: 0=A: to 25=Z:"
    cout << "The root path for 0 is     " << PathBuildRoot(lpStr1,0)  << endl;
    cout << "The root path for 1 is     " << PathBuildRoot(lpStr1,1)  << endl;
    cout << "The root path for 25 is     " << PathBuildRoot(lpStr1,25) << endl;

}
OUTPUT:
---------------
The root path for 0 is     A:\
The root path for 1 is     B:\
The root path for 25 is     Z:\

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathCanonicalize

Canonicalizes a path.

BOOL PathCanonicalize(
    LPTSTR  lpszDst,
    LPCTSTR lpszSrc
    );

Parameters

lpszDst
Address of a string that receives the canonicalized path. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string..
lpszSrc
Address of the path to be canonicalized.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Path_1 destination buffer.
char buffer_1[ ] = "JustABufferToHoldTheCanonicalizedPathForAnExample";
char *lpStr1;
lpStr1 = buffer_1;

// Path_2 to be Canonicalized.
char buffer_2[ ] = "A:\\name_1\\.\\name_2\\..\\name_3";
char *lpStr2;
lpStr2 = buffer_2;

// Path_3 to be Canonicalized.
char buffer_3[ ] = "A:\\name_1\\..\\name_2\\.\\name_3";
char *lpStr3;
lpStr3 = buffer_3;

// Path_4 to be Canonicalized.
char buffer_4[ ] = "A:\\name_1\\name_2\\.\\name_3\\..\\name_4";
char *lpStr4;
lpStr4 = buffer_4;

// Path_5 to be Canonicalized.
char buffer_5[ ] = "A:\\name_1\\.\\name_2\\.\\name_3\\..\\name_4\\..";
char *lpStr5;
lpStr5 = buffer_5;

    // Path_6 to be Canonicalized.
char buffer_6[ ] = "C:\\..";
char *lpStr6;
lpStr6 = buffer_6;

    cout << "The un-canonicalized path 2 is : " << lpStr2
         << "\nThe return value is            : "
         << PathCanonicalize(lpStr1,lpStr2)
         << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

    cout << "\nThe un-canonicalized path 3 is : " << lpStr3
         << "\nThe return value is            : "
         << PathCanonicalize(lpStr1,lpStr3)
         << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

    cout << "\nThe un-canonicalized path 4 is : " << lpStr4
         << "\nThe return value is            : "
         << PathCanonicalize(lpStr1,lpStr4)
         << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

    cout << "\nThe un-canonicalized path 5 is : " << lpStr5
         << "\nThe return value is            : "
         << PathCanonicalize(lpStr1,lpStr5)
         << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;

    cout << "\nThe un-canonicalized path 6 is : " << lpStr6
         << "\nThe return value is            : "
         << PathCanonicalize(lpStr1,lpStr6)
         << "\nThe canonicalized path 1 is    : " << lpStr1 << endl;
}
OUTPUT:
---------
The un-canonicalized path 2 is : A:\name_1\.\name_2\..\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_3

The un-canonicalized path 3 is : A:\name_1\..\name_2\.\name_3
The return value is            : 1
The canonicalized path 1 is    : A:\name_2\name_3

The un-canonicalized path 4 is : A:\name_1\name_2\.\name_3\..\name_4
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2\name_4

The un-canonicalized path 5 is : A:\name_1\.\name_2\.\name_3\..\name_4\..
The return value is            : 1
The canonicalized path 1 is    : A:\name_1\name_2

The un-canonicalized path 6 is : C:\..
The return value is            : 1
The canonicalized path 1 is    : C:\

Remarks

This function allows the user to specify what to remove from a path by inserting special character sequences into the path. The ".." sequence indicates to remove the path part from the current position to the previous path part. The "." sequence indicates to skip over the next path part to the following path part. The root part of the path cannot be removed.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathCombine

Concatenates two strings that represent properly formed paths into one path, as well as any relative path pieces.

LPTSTR PathCombine(
    LPTSTR  lpszDest,
    LPCTSTR lpszDir,
    LPCTSTR lpszFile
    );

Parameters

lpszDest
[out] Pointer to a buffer with the NULL-terminated string to hold the combined path string. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
lpszDir
[in]Address of the string that represents the directory path.
lpszFile
[in]Address of the string that represents the file path.

Return Values

Returns a pointer to a string with the concatenated path if successful, or NULL otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Buffer to hold combined path.
char buffer_1[MAX_PATH] = "";
char *lpStr1;
lpStr1 = buffer_1;

// String for balance of path name.
char buffer_2[ ] = "One\\Two\\Three";
char *lpStr2;
lpStr2 = buffer_2;

// String for directory name.
char buffer_3[ ] = "C:";
char *lpStr3;
lpStr3 = buffer_3;

cout << "The file path to be combined is  "
     << lpStr2<< endl;
cout << "The directory name path is       "
     << lpStr3<< endl;
cout << "The combined path is             "
     << PathCombine(lpStr1,lpStr3,lpStr2) << endl;

}
------------
INPUT:
------------
Path for directory part: "C:"
Path for file part: "One\Two\Three"
------------
OUTPUT:
------------
The file path to be combined is  One\Two\Three
The directory name path is       C:
The combined path is             C:\One\Two\Three

Remarks

The directory path should be in the form of A:,B:, ..., Z:. The file path should be in a correct form that represents the file part of the path. The file path must not be null, and if it ends with a backslash, the backslash will be maintained.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathCommonPrefix

Compares two paths to determine if they share a common prefix. A prefix is one of these types: "C:\\", ".", "..", "..\\".

int PathCommonPrefix(
    LPCTSTR pszFile1,
    LPCTSTR pszFile2,
    LPTSTR  pszPath
    );

Parameters

pszFile1
[in] Pointer to the first path name.
pszFile2
[in] Pointer to the second path name.
pszPath
[out] Pointer to a buffer that receives the common prefix. If there is no common prefix, it will be set to NULL.

Return Values

Returns the count of common prefix characters in the path. If the output buffer pointer is not NULL, then these characters are copied to the output buffer.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
    // String path name 1.
    char buffer_1[ ] = "C:\\win\\desktop\\temp.txt";
    char *lpStr1;
    lpStr1 = buffer_1;

    // String path name 2.
    char buffer_2[ ] = "c:\\win\\tray\\sample.txt";
    char *lpStr2;
    lpStr2 = buffer_2;

    // String path out buffer.
    char buffer_3[ ] = "abcdef";
    char *lpStr3;
    lpStr3 = buffer_3;

    // Variable to get the return.
    // from "PathCommonPrefix"
    int retval;
    retval = PathCommonPrefix(lpStr1,lpStr2,lpStr3);
    cout << "The contents of String 1:            " << lpStr1 << endl;
    cout << "The contents of String 2:            " << lpStr2 << endl;
    cout << "The length of the output buffer is : "
         << retval << endl;
    cout << "The contents of Output buffer:       " << lpStr3 << endl;
}
OUTPUT:
-----------
The contents of String 1:            C:\win\desktop\temp.txt
The contents of String 2:            c:\win\tray\sample.txt
The length of the output buffer is : 6
The contents of Output buffer:       C:\win

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathCompactPath

Truncates a file path to fit within a given pixel width by replacing path components with ellipses.

BOOL PathCompactPath(
    HDC hDC,
    LPTSTR lpszPath,
    UINT dx
);

Parameters

hDC
Handle to the device context used for font metrics.
lpszPath
Address of a buffer containing the path string to be modified. The buffer must be at least MAX_PATH characters long. On return, this buffer will contain the modified string.
dx
Width, in pixels, within which the string will be forced to fit.

Return Values

Returns TRUE if the path was successfully compacted to the specified width. Returns FALSE on failure, or if the base portion of the path would not fit the specified width.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"
HDC hdc;  /* display DC handle for current font metrics */

void main( void )
{

// String path name 1.
char buffer_1[MAX_PATH] = "C:\\path1\\path2\\sample.txt";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[MAX_PATH] = "C:\\path1\\path2\\sample.txt";
char *lpStr2;
lpStr2 = buffer_2;

// String path name 3.
char buffer_3[MAX_PATH] = "C:\\path1\\path2\\sample.txt";
char *lpStr3;
lpStr3 = buffer_3;

// String path name 4.
char buffer_4[MAX_PATH] = "C:\\path1\\path2\\sample.txt";
char *lpStr4;
lpStr4 = buffer_4;

// Variable to get the return from "PathCompactPath".
int retval;

cout << "The un-truncated path is                " << lpStr1 << endl;

retval = PathCompactPath(hdc,lpStr1,125);
cout << "The truncated path at 125 pixels is :   " << lpStr1 << endl;

retval = PathCompactPath(hdc,lpStr2,120);
cout << "The truncated path at 120 pixels is :   " << lpStr2 << endl;

retval = PathCompactPath(hdc,lpStr3,110);
cout << "The truncated path at 110 pixels is :   " << lpStr3 << endl;

retval = PathCompactPath(hdc,lpStr4,25);
cout << "The truncated path at  25 pixels is :   " << lpStr4 << endl;

}
OUTPUT:
===========
The un-truncated path is                C:\path1\path2\sample.txt
The truncated path at 125 pixels is :   C:\path1\...\sample.txt
The truncated path at 120 pixels is :   C:\pat...\sample.txt
The truncated path at 110 pixels is :   C:\p...\sample.txt
The truncated path at  25 pixels is :   ...\sample.txt

Remarks

This function uses the font currently selected in hDC to calculate the width of the text. This function will not compact the path beyond the base file name preceded by ellipses.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathCompactPathEx

Truncates a path to fit within a certain number of characters by replacing path components with ellipses.

BOOL PathCompactPathEx(
    LPTSTR  pszOut,
    LPCTSTR pszSrc,
    UINT    cchMax,
    DWORD   dwFlags
);

Parameters

pszOut
[out] Address of the string that has been altered.
pszSrc
[in] Address of the string to be altered.
cchMax
[in] Maximum number of characters to be contained in the new string, including the terminating NULL character. For example, if cchMax = 8, the resulting string can contain a maximum of 7 characters plus the NULL terminator.
dwFlags
Reserved.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The '/' separator will be used instead of '\' if the original string used it. If pszSource points to a file name that is too long, rather than a path, the file name will be truncated to cchMax characters, including the ellipsis and the terminating NULL character. For example, if the input file name is "My Filename" and cchMax is 10, PathCompactPathEx will return "My Fil...".

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathCreateFromUrl

Takes a file URL and converts it to a DOS path.

HRESULT PathCreateFromUrl(
  LPCTSTR pszUrl,
  LPTSTR pszPath,
  LPDWORD pcchPath,
  DWORD dwReserved
);

Parameters

pszUrl
Pointer to the string with the URL.
pszPath
Value used to return the DOS path. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
pcchPath
Length of pszPath.
dwReserved
Reserved. Set this parameter to NULL.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathFileExists

Determines whether a path to a file system object such as a file or directory is valid.

BOOL PathFileExists(
    LPCTSTR pszPath
    );

Parameters

pszPath
Full path of the object to verify.

Return Values

Returns TRUE if the file exists, or FALSE otherwise. Call GetLastError for extended error information.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Valid file path name (file is there).
char buffer_1[ ] = "C:\\TEST\\file.txt";
char *lpStr1;
lpStr1 = buffer_1;

// Invalid file path name (file is not there).
char buffer_2[ ] = "C:\\TEST\\file.doc";
char *lpStr2;
lpStr2 = buffer_2;

// Return value from "PathFileExists".
int retval;

// Search for the presence of a file with a true result.
retval = PathFileExists(lpStr1);
if(retval == 1)
{
cout << "Search for the file path of : " << lpStr1 << endl;
cout << "The file requested \"" << lpStr1 << "\" is a valid file" << endl;
cout << "The return from function is : " << retval << endl;
}

else{
cout << "\nThe file requested " << lpStr1 << " is not a valid file" << endl;
cout << "The return from function is : " << retval << endl;
}

// Search for the presence of a file with a false result.
retval = PathFileExists(lpStr2);
if(retval == 1)
{
cout << "\nThe file requested " << lpStr2 << "is a valid file" << endl;
cout << "Search for the file path of : " << lpStr2 << endl;
cout << "The return from function is : " << retval << endl;
}

else{
cout << "\nThe file requested \"" << lpStr2 << "\" is not a valid file" << endl;
cout << "The return from function is : " << retval << endl;
}
}
OUTPUT
==============
Search for the file path of : C:\TEST\file.txt
The file requested "C:\TEST\file.txt" is a valid file
The return from function is : 1

The file requested "C:\TEST\file.doc" is not a valid file
The return from function is : 0

Remarks

This function tests the validity of the path. It works only on the local file system or on a remote drive that has been mounted to a drive letter. It will return FALSE for remote file paths that begin with the UNC names \\server or \\server\share. It will also return FALSE if a mounted remote drive is out of service.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathFindExtension

Searches a path for an extension.

LPTSTR PathFindExtension(
    LPCTSTR pPath
    );

Parameters

pPath
Address of the path that contains the extension for which to search.

Return Values

Returns the address of the "." preceding the extension within pPath if an extension is found, or the address of the trailing NULL character otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathFindFileName

Searches a path for a file name.

LPTSTR PathFindFileName(
    LPCTSTR pPath
    );

Parameters

pPath
Address of the file name for which to search.

Return Values

Returns a pointer to the address of the string if successful, or a pointer to the beginning of the path otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
    // Path that contains a file part.
    char buffer_1[ ] = "c:\\path\\file";
    char *lpStr1;
    lpStr1 = buffer_1;

    cout << "Search for the file in path        " << lpStr1
         << "\nReturns the file part of the path \""
         <<  PathFindFileName(lpStr1) << "\"" << endl;

    cout << "\nSearch for the file in path       \"c:\\path\"" << endl;
    cout << "Returns the file part of the path \""
         <<  PathFindFileName("c:\\path") << "\"" << endl;

    cout << "\nSearch for the file in path       \"c:\\path\\\"" << endl;
    cout << "Returns the file part of the path \""
         <<  PathFindFileName("c:\\path\\") << "\"" << endl;

    cout << "\nSearch for the file in path       \"c:\\\"" << endl;
    cout << "Returns the file part of the path \""
         <<  PathFindFileName("c:\\") << "\"" << endl;

    cout << "\nSearch for the file in path       \"c:\"" << endl;
    cout << "Returns the file part of the path \""
         <<  PathFindFileName("c:") << "\"" << endl;

    cout << "\nSearch for the file in path       \"path\"" << endl;
    cout << "Returns the file part of the path \""
         <<  PathFindFileName("path") << "\"" << endl;
}
OUTPUT:
==========
Search for the file in path        c:\path\file
Returns the file part of the path "file"

Search for the file in path       "c:\path"
Returns the file part of the path "path"

Search for the file in path       "c:\path\"
Returns the file part of the path "path\"

Search for the file in path       "c:\"
Returns the file part of the path "c:\"

Search for the file in path       "c:"
Returns the file part of the path "c:"

Search for the file in path       "path"
Returns the file part of the path "path"

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathFindNextComponent

Parses a path for the next path component.

LPTSTR PathFindNextComponent(
    LPCTSTR pszPath
    );

Parameters

pszPath
[in] Pointer to a NULL-terminated string with the path. Paths are delimited by backslashes or by the NULL at the end of the path.

Return Values

Returns a pointer to a NULL-terminated string with the next path component if successful, or NULL otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Path to find the next part.
char buffer_1[ ] = "c:\\path1\\path2\\test";
char *lpStr1;
lpStr1 = buffer_1;

cout << "Search a path for the next path component "
 << "after the root " << lpStr1 << endl;
cout << "Return the next path component: \""
         <<  PathFindNextComponent(lpStr1) << "\"" << endl;

cout << "\nSearch a path for the next path component "
 << "after the root \"c:\\path1\\path2\"" << endl;
cout << "Return the next path component: \""
         <<  PathFindNextComponent("c:\\path1\\path2") << "\"" << endl;

cout << "\nSearch a path for the next path component "
     << "after the root \"c:\\path1\"" << endl;
cout << "Return the next path component: \""
         <<  PathFindNextComponent("c:\\path1") << "\"" << endl;

}
OUTPUT:
===========
Search a path for the next path component after the root c:\path1\path2\test
Return the next path component: "path1\path2\test"

Search a path for the next path component after the root "c:\path1\path2"
Return the next path component: "path1\path2"

Search a path for the next path component after the root "c:\path1"
Return the next path component: "path1"

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathFindOnPath

Searches for a file.

BOOL PathFindOnPath(
    LPTSTR pszFile,
    LPCTSTR * ppszOtherDirs
);

Parameters

pszFile
File name for which to search. If the search is successful, this parameter is used to return the fully qualified path name.
ppszOtherDirs
Optional null-terminated array of directories to be searched first.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

PathFindOnPath searches for the file specified by pszFile. If no directories are specified in ppszOtherDirs, it attempts to find the file by searching standard directories such as System32 and the directories specified in the PATH environment variable. To expedite the process or enable PathFindOnPath to search a wider range of directories, use the ppszOtherDirs parameter to specify one or more directories to be searched first. If more than one file has the name specified by pszFile, PathFindOnPath returns the first instance it finds.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathFindSuffixArray

Determines if a given file name has one of a list of suffixes.

LPCTSTR PathFindSuffixArray(
    LPCTSTR pszPath,
    LPCTSTR *apszSuffix,
    int iArraySize
);

Parameters

pszPath
[in] File name to be tested. A full path can also be used.
apszSuffix
[in] Array of suffixes to be tested for.
iArraySize
[in] Number of elements in apszSuffix.

Return Values

Returns a pointer to a string with the matching suffix if successful, or NULL if pszPath does not end with one of the specified suffixes.

Remarks

This function does a case-sensitive comparison. The suffix must match exactly.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathGetArgs

Finds the command line arguments within a given path.

LPTSTR PathGetArgs(
    LPCTSTR pszPath
    );

Parameters

pszPath
A pointer to a string containing the path to be searched.

Return Values

Returns a pointer to a null-terminated string containing the arguments portion of the path if successful; if there are no arguments the function returns a pointer to the end of the input string. If the function is given a NULL agrument it returns NULL.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

// Path_1 to search for file arguments (2-Args):
char buffer_1[ ] = "test.exe temp.txt sample.doc";
char *lpStr1;
lpStr1 = buffer_1;

// Path_2 to search for file arguments (3-Args):
char buffer_2[ ] = "test.exe 1 2 3";
char *lpStr2;
lpStr2 = buffer_2;

// Path_3 to search for file arguments (3-Args):
char buffer_3[ ] = "test.exe sample All 15";
char *lpStr3;
lpStr3 = buffer_3;

// Path_4 to search for file arguments (zero args):
char buffer_4[ ] = "test.exe";
char *lpStr4;
lpStr4 = buffer_4;

cout << "The path passed to the function was : " << lpStr1 <<
        "\nThe arg(s)found in path 1 were      : " << PathGetArgs(lpStr1) << endl;

cout << "\nThe path passed to the function was : " << lpStr2 <<
        "\nThe arg(s)found in path 2 were      : " << PathGetArgs(lpStr2) << endl;

cout << "\nThe path passed to the function was : " << lpStr3 <<
        "\nThe arg(s)found in path 3 were      : " << PathGetArgs(lpStr3) << endl;

cout << "\nThe path passed to the function was : " << lpStr4 <<
        "\nThe arg(s)found in path 4 were      : " << PathGetArgs(lpStr4) << endl;

}

OUTPUT:
===========
The path passed to the function was : test.exe temp.txt sample.doc
The arg(s)found in path 1 were      : temp.txt sample.doc

The path passed to the function was : test.exe 1 2 3
The arg(s)found in path 2 were      : 1 2 3

The path passed to the function was : test.exe sample All 15
The arg(s)found in path 3 were      : sample All 15

The path passed to the function was : test.exe
The arg(s)found in path 4 were      :
===========

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathGetCharType

Determines the type of character with respect to a path.

UINT PathGetCharType(
    TUCHAR ch
    );

Parameters

ch
Character for which to determine the type.

Return Values

Returns one or more of the following values that define the type of character:
GCT_INVALID | The character is not valid in a path.
GCT_LFNCHAR | The character is valid in a long file name.
GCT_SEPARATOR | The character is a path separator.
GCT_SHORTCHAR | The character is valid in a short (8.3) file name.
GCT_WILD | The character is a wildcard character.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathGetDriveNumber

Searches a path for a drive letter within the range of 'A' to 'Z' and returns the corresponding drive number.

int PathGetDriveNumber(
    LPCTSTR lpsz
    );

Parameters

lpsz
Address of a string that contains the path to be searched.

Return Values

Returns 0 through 25 (corresponding to 'A' through 'Z') if the path has a drive letter, or -1 otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Paths to search for drive IDs.
char buffer_1[ ] = "A:\\TEST\\bar.txt";
char *lpStr1;
lpStr1 = buffer_1;

char buffer_2[ ] = "B:\\TEST\\bar.txt";
char *lpStr2;
lpStr2 = buffer_2;

char buffer_3[ ] = "Z:\\TEST\\bar.txt";
char *lpStr3;
lpStr3 = buffer_3;

char buffer_4[ ] = "%:\\TEST\\bar.txt";
char *lpStr4;
lpStr4 = buffer_4;

cout << "The path passed to the function was  : " << lpStr1 <<
        "\nThe path contains a drive identifier : " << PathGetDriveNumber(lpStr1) << endl;

cout << "The path passed to the function was  : " << lpStr2 <<
        "\nThe path contains a drive identifier : " << PathGetDriveNumber(lpStr2) << endl;

cout << "The path passed to the function was  : " << lpStr3 <<
        "\nThe path contains a drive identifier : " << PathGetDriveNumber(lpStr3) << endl;

cout << "The path passed to the function was  : " << lpStr4 <<
        "\nThe path contains a drive identifier : " << PathGetDriveNumber(lpStr4) << endl;
}
OUTPUT:
===========
The path passed to the function was  : A:\TEST\bar.txt
The path contains a drive identifier : 0
The path passed to the function was  : B:\TEST\bar.txt
The path contains a drive identifier : 1
The path passed to the function was  : Z:\TEST\bar.txt
The path contains a drive identifier : 25
The path passed to the function was  : %:\TEST\bar.txt
The path contains a drive identifier : -1

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsContentType

Determines if a file's registered content type matches the specified content type. This function obtains the content type for the specified file type and compares that string with the pszContentType. The comparison is not case sensitive.

BOOL PathIsContentType(
    LPCTSTR pszPath,
    LPCTSTR pszContentType
    );

Parameters

pszPath
Address of a character buffer that contains the file whose content type will be compared.
pszContentType
Address of a character buffer that contains the content type string to which the file's registered content type will be compared.

Return Values

Returns nonzero if the file's registered content type matches pszContentType, or zero otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsDirectory

Verifies that a path is a valid directory.

BOOL PathIsDirectory(
    LPCTSTR pszPath
    );

Parameters

pszPath
Address of the path to verify.

Return Values

Returns TRUE if the path is a valid directory, or FALSE otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsDirectoryEmpty

Determines whether or not a specified path is an empty directory.

BOOL PathIsDirectoryEmpty(
    LPCTSTR pszPath
);

Parameters

pszPath
[in] NULL-terminated string with the path to be tested.

Return Values

Returns TRUE if pszPath is an empty directory. Returns FALSE if pszPath is not a directory, or if it contains at least one file other than "." or "..".

Remarks

"C:\" is considered a directory.

See Also

PathIsDirectory

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsFileSpec

Searches a path for any path delimiting characters (for example, ':' or '\' ). If there are no path delimiting characters present, the path is considered to be a File Spec path.

BOOL PathIsFileSpec(
    LPCTSTR lpszPath
    );

Parameters

lpszPath
Address of the path to be searched.

Return Values

Returns TRUE if there are no path delimiting characters within the path, or FALSE if there are path delimiting characters.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path 1 string.
char buffer_1[ ] = "sample";
char *lpStr1;
lpStr1 = buffer_1;

// Path 2 string.
char buffer_2[ ] = "C:\\TEST\\sample";
char *lpStr2;
lpStr2 = buffer_2;

//Return value from "PathIsFileSpec".
int retval;

// Test path 1 for file spec.
retval = PathIsFileSpec(lpStr1);
cout << "The path to verify file spec is     : " << lpStr1 << endl;
    cout << "PathIsFileSpec returns TRUE and is  : " << retval << endl;

// Test path 2 for file spec.
retval = PathIsFileSpec(lpStr2);
cout << "\nThe path to verify file spec is     : " << lpStr2 << endl;
cout << "PathIsFileSpec returns FALSE and is : " << retval << endl;

}
OUTPUT:
==============
The path to verify file spec is     : sample
PathIsFileSpec returns TRUE and is  : 1

The path to verify file spec is     : C:\TEST\sample
PathIsFileSpec returns FALSE and is : 0

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsHTMLFile

Determines if a file is an HTML file. The determination is made based on the content type that is registered for the file's extension.

BOOL PathIsHTMLFile(
    LPCTSTR pszFile
    );

Parameters

pszFile
Address of a character buffer that contains the path and name of the file.

Return Values

Returns nonzero if the file is an HTML file, or zero otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsLFNFileSpec

Determines whether or not a file name is in long format.

BOOL PathIsLFNFileSpec(
    LPCTSTR pszName
);

Parameters

pszName
[in] NULL-terminated string with the file name to be tested.

Return Values

Returns TRUE if pszName exceeds the number of characters allowed by the 8.3 format, or FALSE otherwise.

See Also

PathIsFileSpec

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsNetworkPath

Determines whether a path string represents a network resource.

BOOL PathIsNetworkPath(
  LPCTSTR pszPath
);

Parameters

pszPath
[in] NULL-terminated string that contains the path.

Return Values

Returns TRUE if the string represents a network resource, or FALSE otherwise.

Remarks

PathIsNetwork interprets two types of paths as network paths:

  • Paths that begin with two backslash (\) characters are interpreted as UNC paths.
  • Paths that begin with a letter followed by a colon (:) are interpreted as a mounted network drive.

The path is not checked to see if it refers to an actual network server.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsPrefix

Searches a path to determine if it contains a valid prefix of the type passed by pszPrefix. A prefix is one of these types: "C:\\", ".", "..", "..\\".

BOOL PathIsPrefix(
    IN LPCTSTR  pszPrefix,
    IN LPCTSTR  pszPath
    );

Parameters

pszPrefix
Address of the prefix for which to search.
pszPath
Address of the path to be searched.

Return Values

Returns TRUE if the compared path is the full prefix for the path, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Path prefix 1.
char buffer_1[ ] = "C:\\";
char *lpStr1;
lpStr1 = buffer_1;

// Path prefix 2.
char buffer_2[ ] = "C:\\test\\Some\\sample";
char *lpStr2;
lpStr2 = buffer_2;

// Path prefix 3.
char buffer_3[ ] = "sample";
char *lpStr3;
lpStr3 = buffer_3;

// Search a path prefix with result true.
    cout << "The contents of path 1 is : " << lpStr1
         << "\nThe contents of path 2 is : " << lpStr2
         << "\nThe return from the function is : "
         <<  PathIsPrefix(lpStr1,lpStr2)
         << "\nPathIsPrefix returns TRUE   "
         << "\nand Path lpStr1 and lpStr2"
         << "\nhave the same prefix :" << endl;

// Search a path prefix with result false.
    cout << "\nThe contents of path 1 is : " << lpStr1
         << "\nThe contents of path 3 is : " << lpStr3
         << "\nThe return from the function is : "
         <<  PathIsPrefix(lpStr1,lpStr3)
         << "\nPathIsPrefix returns FALSE   "
         << "\nand Path lpStr1 and lpStr3"
         << "\nhave different prefixes :" << endl;
}
OUTPUT:
==============
The contents of path 1 is : C:\
The contents of path 2 is : C:\test\Some\sample
The return from the function is : 1
PathIsPrefix returns TRUE
and Path lpStr1 and lpStr2
have the same prefix :

The contents of path 1 is : C:\
The contents of path 3 is : sample
The return from the function is : 0
PathIsPrefix returns FALSE
and Path lpStr1 and lpStr3
have different prefixes :

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsRelative

Searches a path and determines if it is relative.

BOOL PathIsRelative(
    LPCTSTR lpszPath
    );

Parameters

lpszPath
Address of the path to search.

Return Values

Returns TRUE if the path is relative, or FALSE if it is absolute.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "test.exe";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "C:\\test.exe";
char *lpStr2;
lpStr2 = buffer_2;

// Variable to get the return from "PathIsRelative".
int retval;

// Test case with path not absolute.
retval = PathIsRelative(lpStr1);
cout << "The return from function is :" << retval << endl;
cout << "The path is not absolute :   " << lpStr1 << endl;

// Test case with path absolute.
retval = PathIsRelative(lpStr2);
cout << "\nThe return from function is :" << retval << endl;
cout << "The path is absolute :       " << lpStr2 << endl;

}
OUTPUT:
==========
The return from function is :1
The path is not absolute :   test.exe

The return from function is :0
The path is absolute :       C:\test.exe

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsRoot

Parses a path to determine if it is a directory root.

BOOL PathIsRoot(
    LPCTSTR pPath
    );

Parameters

pPath
Address of the path to be validated.

Return Values

Returns TRUE if the specified path is a root, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "C:\\";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "path\\file";
char *lpStr2;
lpStr2 = buffer_2;

// Variable to get the return from "PathIsRoot".
int retval;

// Test case with path not absolute.
retval = PathIsRoot(lpStr1);
cout << "The return from function is       :" << retval << endl;
cout << "The path does contain a root part :" << lpStr1 << endl;

// Test case with path absolute.
retval = PathIsRoot(lpStr2);
cout << "The return from function is       :" << retval << endl;
cout << "The path does not contain part    :" << lpStr2 << endl;

}
OUTPUT:
============
The return from function is       :1
The path does contain a root part :C:\
The return from function is       :0
The path does not contain part    :path\file
============

Remarks

Returns TRUE for paths such as "\", "X:\", "\\server\share", or "\\server\". Paths such as "..\path2" will return FALSE.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsSameRoot

Compares two paths to determine if they have a common root component.

BOOL PathIsSameRoot(
    LPCTSTR pszPath1,
    LPCTSTR pszPath2
    );

Parameters

pszPath1
Address of the first path to be compared.
pszPath2
Address of the second path to be compared.

Return Values

Returns TRUE if both strings have the same root component, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "C:\\path1\\one";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "C:\\path2\\two";
char *lpStr2;
lpStr2 = buffer_2;

// Variable to get the
// return from "PathIsSameRoot".
int retval;
// Compare paths with same root.
    retval = PathIsSameRoot(lpStr1,lpStr2);

    cout << "The return from function is : "
         << retval << endl;
    cout << "The contents of String 1:  " << lpStr1
         << "\nThe contents of String 2:  " << lpStr2
         << "\nThese both have the same root part" << endl;

//compare paths with different roots
    retval = PathIsSameRoot(lpStr1,"E:\\acme\\three");

    cout << "\nThe return from function is : "
         << retval << endl;
    cout << "The contents of String 1:  " << lpStr1
         << "\nThe contents of String 3:  E:\\acme\\three"
         << "\nThese do not have the same root part" << endl;
}
OUTPUT:
==================
The return from function is : 1
The contents of String 1:  C:\path1\one
The contents of String 2:  C:\path2\two
These both have the same root part

The return from function is : 0
The contents of String 1:  C:\path1\one
The contents of String 3:  E:\acme\three
These do not have the same root part

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsSystemFolder

Determines if an existing folder contains the attributes that make it a system folder. Alternately indicates if certain attributes qualify a folder to be a system folder.

BOOL PathIsSystemFolder(
    LPCTSTR pszPath,
    DWORD dwAttrb
    );

Parameters

pszPath
[in] Address of a character buffer that contains the name of an existing folder. The attributes for this folder will be retrieved and compared with those that define a system folder. If this folder contains the attributes to make it a system folder, the function returns nonzero. If this value is NULL, this function determines if the attributes passed in dwAttrb qualify it to be a system folder.
dwAttrb
[in] Contains the file attributes to be compared. If pszPath is not NULL, this value is ignored. If pszPath is NULL, the attributes passed in this value are compared with those that qualify a folder as a system folder. If the attributes are sufficient to make this a system folder, this function returns nonzero. These attributes are the attributes that are returned from GetFileAttributes.

Return Values

Returns nonzero if the pszPath or dwAttrb represent a system folder, or zero otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsUNC

Determines if the string is a valid UNC (universal naming convention) for a server and share path.

BOOL PathIsUNC(
    LPCTSTR pszPath
    );

Parameters

pszPath
Address of the path to validate.

Return Values

Returns TRUE if the string is a valid UNC path, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "\\\\path1\\path2";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "\\\\path3";
char *lpStr2;
lpStr2 = buffer_2;

// String path name 3.
char buffer_3[ ] = "acme\\path4\\path5";
char *lpStr3;
lpStr3 = buffer_3;

// Variable to get the return
// from "PathIsUNC".
    int retval;

// Test path name 1.
    retval = PathIsUNC(lpStr1);
    cout << "The contents of String 1: " << lpStr1
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 2.
retval = PathIsUNC(lpStr2);
    cout << "The contents of String 2: " << lpStr2
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 3.
retval = PathIsUNC(lpStr3);
    cout << "The contents of String 3: " << lpStr3
 << "\nThe return value from the function is " << retval << " = FALSE"<< endl;
}
OUTPUT:
==============
The contents of String 1: \\path1\path2
The return value from the function is 1 = TRUE
The contents of String 2: \\path3
The return value from the function is 1 = TRUE
The contents of String 3: acme\path4\path5
The return value from the function is 0 = FALSE

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsUNCServer

Determines if a string is a valid UNC (universal naming convention) for a server path only.

BOOL PathIsUNCServer(
    LPCTSTR pszPath
    );

Parameters

pszPath
Address of the path to validate.

Return Values

Returns TRUE if the string is a valid UNC path for a server only (no share name), or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "\\\\path1";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "\\\\";
char *lpStr2;
lpStr2 = buffer_2;

// String path name 3.
char buffer_3[ ] = "acme\\path2\\path3";
char *lpStr3;
lpStr3 = buffer_3;

// Variable to get the return
// from "PathIsUNCServer".
    int retval;

// Test path name 1.
    retval = PathIsUNCServer(lpStr1);
    cout << "The contents of String 1: " << lpStr1
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 2.
retval = PathIsUNCServer(lpStr2);
    cout << "The contents of String 2: " << lpStr2
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 3.
retval = PathIsUNCServer(lpStr3);
    cout << "The contents of String 3: " << lpStr3
 << "\nThe return value from the function is " << retval << " = FALSE"<< endl;
}
OUTPUT:
The contents of String 1: \\path1
The return value from the function is 1 = TRUE
The contents of String 2: \\
The return value from the function is 1 = TRUE
The contents of String 3: acme\path2\path3
The return value from the function is 0 = FALSE

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsUNCServerShare

Determines if a string is a valid universal naming convention (UNC) share path, \\server\share.

BOOL PathIsUNCServerShare(
    LPCTSTR pszPath
    );

Parameters

pszPath
Pointer to a string with the path to be validated.

Return Values

Returns TRUE if the string is in the form \\server\share, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "\\\\path1\\path2";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "\\\\path3";
char *lpStr2;
lpStr2 = buffer_2;

// String path name 3.
char buffer_3[ ] = "acme\\path4\\path5";
char *lpStr3;
lpStr3 = buffer_3;

// Variable to get the return
// from "PathIsUNCServerShare".
int retval;

// Test path name 1.
retval = PathIsUNCServerShare(lpStr1);
cout << "The contents of String 1: " << lpStr1
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 2.
retval = PathIsUNCServerShare(lpStr2);
cout << "The contents of String 2: " << lpStr2
 << "\nThe return value from the function is " << retval << " = FALSE" << endl;
// Test path name 3.
retval = PathIsUNCServerShare(lpStr3);
cout << "The contents of String 3: " << lpStr3
 << "\nThe return value from the function is " << retval << " = FALSE"<< endl;
}
OUTPUT:
=================
The contents of String 1: \\path1\path2
The return value from the function is 1 = TRUE
The contents of String 2: \\path3
The return value from the function is 0 = FALSE
The contents of String 3: acme\path4\path5
The return value from the function is 0 = FALSE

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathIsURL

Tests a given string to determine if it conforms to a valid URL format.

BOOL PathIsURL(
    LPCTSTR pszPath
    );

Parameters

pszPath
[in] Address of the URL path to validate.

Return Values

Returns TRUE if pszPath has a valid URL format, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "http://www.microsoft.com/software/index.html";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "http://www.microsoft.com";
char *lpStr2;
lpStr2 = buffer_2;

// String path name 3.
char buffer_3[ ] = "microsoft.com";
char *lpStr3;
lpStr3 = buffer_3;

// Variable to get the return
// from "PathIsURL".
int retval;

// Test path name 1.
retval = PathIsURL(lpStr1);
cout << "The contents of String 1: " << lpStr1
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 2.
retval = PathIsURL(lpStr2);
cout << "The contents of String 2: " << lpStr2
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;
// Test path name 3.
retval = PathIsURL(lpStr3);
cout << "The contents of String 3: " << lpStr3
 << "\nThe return value from the function is " << retval << " = FALSE"<< endl;
}

OUTPUT:
=============
The contents of String 1: http://www.microsoft.com/software/index.html
The return value from the function is 1 = TRUE
The contents of String 2: http://www.microsoft.com
The return value from the function is 1 = TRUE
The contents of String 3: microsoft.com
The return value from the function is 0 = FALSE

Remarks

This function does not verify that the path points to an existing site—only that it has a valid URL format.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathMakePretty

Converts a path to all lowercase characters to give the path a consistent appearance.

BOOL PathMakePretty(
    LPTSTR lpPath
    );

Parameters

lpPath
Address of the path to be converted.

Return Values

Returns TRUE if the path has been converted, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// Path name 1.
char buffer_1[ ] = "C:\\TEST\\FILE";
char *lpStr1;
lpStr1 = buffer_1;

// Path name 2.
char buffer_2[ ] = "c:\\test\\file";
char *lpStr2;
lpStr2 = buffer_2;

// Test path name 1.
    cout << "The content of the unconverted path is : " << lpStr1 << endl;
    cout << "The \"PathMakePretty\" function returns the value "
         << PathMakePretty(lpStr1) << "  = TRUE & converts"  << endl;
    cout << "The content of the converted path is   : " << lpStr1 << endl;

// Test path name 2.
    cout << "\nThe content of the unconverted path is : " << lpStr2 << endl;
    cout << "The \"PathMakePretty\" function returns the value "
         << PathMakePretty(lpStr2) << "  = FALSE & no conversion"  << endl;
    cout << "The content of the converted path is   : " << lpStr2 << endl;

}
OUTPUT:
=============
The content of the unconverted path is : C:\TEST\FILE
The "PathMakePretty" function returns the value 1  = TRUE & converts
The content of the converted path is   : C:\test\file

The content of the unconverted path is : c:\test\file
The "PathMakePretty" function returns the value 0  = FALSE & no conversion
The content of the converted path is   : c:\test\file

Remarks

This function only operates on paths that are entirely uppercase. For example: C:\WINDOWS will be converted to c:\windows, but c:\Windows will not be changed.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathMakeSystemFolder

Gives an existing folder the proper attributes to become a system folder.

BOOL PathMakeSystemFolder(
    LPTSTR pszPath
    );

Parameters

pszPath
Address of a character buffer that contains the name of an existing folder that will be made into a system folder.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathMatchSpec

Searches a string using a DOS wild card match type.

BOOL PathMatchSpec(
    LPCTSTR pszFileParam,
    LPCTSTR pszSpec
    );

Parameters

pszFileParam
Pointer to the string to be searched.
pszSpec
Pointer to a NULL-terminated string with the file type for which to search. For example, to test whether or not pszFileParam is a DOC file, pszSpec should be set to "*.doc".

Return Values

Returns TRUE if the string matches, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
// String path name 1.
char buffer_1[ ] = "C:\\Test\\File.txt";
char *lpStr1;
lpStr1 = buffer_1;

// String path name 2.
char buffer_2[ ] = "C:\\Test\\File.bmp";
char *lpStr2;
lpStr2 = buffer_2;

// String path name 3.
char buffer_3[ ] = "*.txt";
char *lpStr3;
lpStr3 = buffer_3;

// String path name 4.
char buffer_4[ ] = "C:\\Test\\File";
char *lpStr4;
lpStr4 = buffer_4;

// Variable to get the return.
// from "PathMatchSpec"
int retval;

// Test path name 1.
retval = PathMatchSpec(lpStr1,lpStr3);
cout << "The contents of String 1: " << lpStr1
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;

// Test path name 2.
retval = PathMatchSpec(lpStr2,"*.bmp");
cout << "The contents of String 2: " << lpStr2
 << "\nThe return value from the function is " << retval << " = TRUE" << endl;

// Test path name 4.
retval = PathMatchSpec(lpStr4,lpStr2);
cout << "The contents of String 4: " << lpStr4
 << "\nThe return value from the function is " << retval << " = FALSE"<< endl;
}
OUTPUT:
==========
The contents of String 1: C:\Test\File.txt
The return value from the function is 1 = TRUE
The contents of String 2: C:\Test\File.bmp
The return value from the function is 1 = TRUE
The contents of String 4: C:\Test\File
The return value from the function is 0 = FALSE

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathParseIconLocation

Parses a file location string containing a file location and icon index, and returns separate values.

int PathParseIconLocation(
    LPTSTR pszIconFile
    );

Parameters

pszIconFile
[in/out] Pointer to a file location string. It should be in the form "pathname,iconindex". When the function returns, pszIconFile will point to the file's pathname.

Return Values

Returns the valid icon index value.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

// Path to parse for file and icon index.
char buffer_1[ ] = "C:\\TEST\\sample.txt,3";
char *lpStr1;
lpStr1 = buffer_1;

// Return value from "PathParseIconLocation".
int retval;

// Search a path to parse for file and icon index.
retval = PathParseIconLocation(lpStr1);
cout << "The path to parse for file and icon index is   : " << lpStr1 << endl;
cout << "PathParseIconLocation returns the icon index of: " << retval << endl;

}
OUTPUT:
==========
The path to parse for file and icon index is   : C:\TEST\sample.txt
PathParseIconLocation returns the icon index of: 3

Remarks

This function is useful for taking a DefaultIcon value retrieved from the registry by SHGetValue and separating the icon index from the pathname.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathQuoteSpaces

Searches a path for spaces. If spaces are found, the entire path is enclosed in quotation marks.

void PathQuoteSpaces(
    LPTSTR lpsz
    );

Parameters

lpsz
[in/out] Pointer to a buffer with a string containing the path to search. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.

Return Values

No return value.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path with spaces.
char buffer_1[MAX_PATH] = "C:\\sample_one\\sample two";
char *lpStr1;
lpStr1 = buffer_1;

// Path before quote spaces.
cout << "The path before PathQuoteSpaces: " << lpStr1 << endl;

// Call "PathQuoteSpaces".
    PathQuoteSpaces(lpStr1);

// Path after quote spaces.
cout << "The path after PathQuoteSpaces: " << lpStr1 << endl;

}
OUTPUT:
==================
The path before PathQuoteSpaces: C:\sample_one\sample two
The path after PathQuoteSpaces: "C:\sample_one\sample two"

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRelativePathTo

Creates a relative path from one file or folder to another.

BOOL PathRelativePathTo(
    LPTSTR  pszPath,
    LPCTSTR pszFrom,
    DWORD   dwAttrFrom,
    LPCTSTR pszTo,
    DWORD   dwAttrTo
    );

Parameters

pszPath
Pointer to a string that receives the relative path. This buffer is assumed to be at least MAX_PATH characters in size.
pszFrom
Pointer to a string that contains the path that defines the start of the relative path.
dwAttrFrom
File attributes of pszFrom. If this value contains FILE_ATTRIBUTE_DIRECTORY, pszFrom is assumed to be a directory; otherwise, pszFrom is assumed to be a file.
pszTo
Pointer to a string that contains the path that defines the endpoint of the relative path.
dwAttrTo
File attributes of pszTo. If this value contains FILE_ATTRIBUTE_DIRECTORY, pszTo is assumed to be directory; otherwise, pszTo is assumed to be a file.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{
    char szOut[MAX_PATH] = "";
    char szFrom[ ] = "c:\\a\\b\\path";
    char szTo[ ] = "c:\\a\\x\\y\\file";

    cout  <<  "The relative path is relative from: ";
    cout  <<  szFrom;
    cout  <<  "\n";

    cout  <<  "The relative path is relative to: ";
    cout  <<  szTo;
    cout  <<  "\n";

    PathRelativePathTo(  szOut,
                         szFrom,
                         FILE_ATTRIBUTE_DIRECTORY,
                         szTo,
                         FILE_ATTRIBUTE_NORMAL);

    cout  <<  "The relative path is: ";
    cout  <<  szOut;
    cout  <<  "\n";
}
OUTPUT:
==================
The relative path is relative from: c:\a\b\path
The relative path is relative to: c:\a\x\y\file
The relative path is: ..\..\x\y\file

Remarks

This function takes a pair of paths and generates a relative path from one to the other. The paths do not have to be fully-qualified, but they must have a common prefix, or the function will fail and return FALSE.

For example, let the starting point, pszFrom, be "c:\FolderA\FolderB\FolderC", and the ending point, pszTo, be "c:\FolderA\FolderD\FolderE". PathRelativePathTo will return the relative path from pszFrom to pszTo as: "..\..\FolderD\FolderE". You will get the same result if you set pszFrom to "\FolderA\FolderB\FolderC" and pszTo to "\FolderA\FolderD\FolderE". On the other hand, "c:\FolderA\FolderB" and "a:\FolderA\FolderD do not share a common prefix, and the function will fail. Note that "\\" is not considered a prefix and is ignored. If you set pszFrom to "\\FolderA\FolderB", and pszTo to "\\FolderC\FolderD", the function will fail.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRemoveArgs

Removes any arguments from a given path.

void PathRemoveArgs(
    LPTSTR pszPath
    );

Parameters

pszPath
Address of the path from which to remove arguments.

Return Values

No return value.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path with arguments.
char buffer_1[ ] = "c:\\a\\b\\FileA Arg1 Arg2";
char *lpStr1;
lpStr1 = buffer_1;

    // Path before "PathRemoveArgs".
cout << "Path before calling \"PathRemoveArgs\": " << lpStr1 << endl;

    // Call function "PathRemoveArgs".
PathRemoveArgs(lpStr1);

    // Path after "PathRemoveArgs".
cout << "Path before calling \"PathRemoveArgs\": " << lpStr1 << endl;
}
OUTPUT:
==================
Path before calling "PathRemoveArgs": c:\a\b\FileA Arg1 Arg2
Path before calling "PathRemoveArgs": c:\a\b\FileA

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRemoveBackslash

Removes the trailing backslash from a given path.

LPTSTR PathRemoveBackslash(
    LPTSTR lpszPath
    );

Parameters

lpszPath
Address of the string from which to remove the backslash.

Return Values

Returns the address of the NULL that replaced the backslash, or the address of the last character if it's not a backslash.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path with backslash.
char buffer_1[ ] = "c:\\a\\b\\File\\";
char *lpStr1;
lpStr1 = buffer_1;

    // Path before "PathRemoveBackslash".
cout << "Path before calling \"PathRemoveBackslash\": " << lpStr1 << endl;

    // Call function "PathRemoveBackslash".
PathRemoveBackslash(lpStr1);

    // Path after "PathRemoveBackslash".
cout << "Path after calling \"PathRemoveBackslash\": " << lpStr1 << endl;

}
OUTPUT:
==================
Path before calling "PathRemoveBackslash": c:\a\b\File\
Path after calling "PathRemoveBackslash": c:\a\b\File

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRemoveBlanks

Removes all leading and trailing spaces from a string.

void PathRemoveBlanks(
    LPTSTR lpszString
    );

Parameters

lpszString
Address of the string from which to strip all leading and trailing spaces.

Return Values

No return value.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path with leading and trailing spaces.
char buffer_1[ ] = "  c:\\TEST\\File1\\File2  ";
char *lpStr1;   // |--------- leading   &   |-------- trailing spaces
lpStr1 = buffer_1;

    // Path before "PathRemoveBlanks".
cout << "Path before calling \"PathRemoveBlanks\": " << lpStr1 << endl;
cout << "Dashes are only to indicate path width :"
         <<"\n---->|" << lpStr1 << "|<----" << endl;

    // Call function "PathRemoveBlanks".
PathRemoveBlanks(lpStr1);

    // Path after "PathRemoveBlanks".
cout << "\nPath after calling \"PathRemoveBlanks\": " << lpStr1 << endl;
cout << "Dashes are only to indicate path width :"
         << "\n---->|" << lpStr1 << "|<----" << endl;

}
OUTPUT:
==================
Path before calling "PathRemoveBlanks":   c:\TEST\File1\File2
Dashes are only to indicate path width :
---->|  c:\TEST\File1\File2  |<----

Path after calling "PathRemoveBlanks": c:\TEST\File1\File2
Dashes are only to indicate path width :
---->|c:\TEST\File1\File2|<----

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRemoveExtension

Removes the file extension from a path, if there is one.

void PathRemoveExtension(
    LPTSTR pszPath
    );

Parameters

pszPath
Address of the path from which to remove the extension.

Return Values

No return value.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path to include file spec.
char buffer_1[ ] = "C:\\TEST\\sample.txt";
char *lpStr1;
lpStr1 = buffer_1;

    // Print the path with the extension.
cout << "The path with extension is          : " << lpStr1 << endl;

    // Call to "PathRemoveExtension".
PathRemoveExtension(lpStr1);

// Print the path without the extension.
cout << "\nThe path without extension is       : " << lpStr1 << endl;

}
OUTPUT:
==================
The path with extension is          : C:\TEST\sample.txt

The path without extension is       : C:\TEST\sample

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRemoveFileSpec

Removes the trailing file name and backslash from a path, if it has them.

BOOL PathRemoveFileSpec(
    LPTSTR pszPath
);

Parameters

pszPath
Address of the path from which to remove the file name.

Return Values

Returns nonzero if something was removed, or zero otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path to include file spec.
char buffer_1[ ] = "C:\\TEST\\sample.txt";
char *lpStr1;
lpStr1 = buffer_1;

    // Print the path with the file spec.
cout << "The path with file spec is          : " << lpStr1 << endl;

    // Call to "PathRemoveFileSpec".
PathRemoveFileSpec(lpStr1);

// Print the path without the file spec.
cout << "\nThe path without file spec is       : " << lpStr1 << endl;

}
OUTPUT:
==================
The path with file spec is          : C:\TEST\sample.txt

The path without file spec is       : C:\TEST

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathRenameExtension

Replaces the extension of a file name with a new extension. If the file name does not contain an extension, the extension will be attached to the end of the string.

BOOL PathRenameExtension(
    LPTSTR pszPath,
    LPCTSTR pszExt
);

Parameters

pszPath
Address of the path for which to replace the extension. This buffer must be at least MAX_PATH characters in size.
pszExt
Address of a character buffer that contains a '.' followed by the new extension.

Return Values

Returns nonzero if successful, or zero if the new path and extension would exceed MAX_PATH characters.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathSearchAndQualify

Determines if a given path is correctly formatted and fully qualified.

BOOL PathSearchAndQualify(
    LPCTSTR pcszPath,
    LPTSTR  pszFullyQualifiedPath,
    UINT    cchFullyQualifiedPath
    );

Parameters

pcszPath
Address of the path to search.
pszFullyQualifiedPath
Address of the path to be referenced. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
cchFullyQualifiedPath
Width of the path, in characters, to be qualified.

Return Values

Returns TRUE if the path is qualified, or FALSE otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathSetDlgItemPath

Sets the text of a child control in a window or dialog box, using PathCompactPath to make sure the path fits in the control.

void PathSetDlgItemPath(
    HWND hDlg,
    int id,
    LPCSTR pszPath,
    );

Parameters

hDlg
Handle to the dialog box or window.
id
Identifier of the control.
pszPath
Address of a string that contains the path to set in the control.

Return Values

No return value.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathSkipRoot

Parses a path, ignoring the drive letter or UNC server/share path parts.

LPTSTR PathSkipRoot(
    LPCTSTR pszPath
    );

Parameters

pszPath
Address of the path to parse.

Return Values

Returns the address of the beginning of the subpath that follows the root (drive letter or UNC server/share).

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path to convert.
char buffer_1[ ] = "C:\\path1\\path2";
char *lpStr1;
lpStr1 = buffer_1;

cout << "The path before is : " << lpStr1 << endl;
cout << "The path after is :  " << PathSkipRoot(lpStr1) << endl;
}
OUTPUT:
==================
The path before is : C:\path1\path2
The path after is : path1\path2

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathStripPath

Removes the path portion of a fully qualified path and file.

void PathStripPath(
    LPTSTR pszPath
    );

Parameters

pszPath
Address of a string that contains the path and file name that will have the path portion removed.

Return Values

No return value.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathStripToRoot

Removes all parts of the path except for the root information.

BOOL PathStripToRoot(
    LPTSTR szRoot
    );

Parameters

szRoot
Address of the path to be converted.

Return Values

Returns TRUE if a valid drive letter was found in the path, or FALSE otherwise.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path to convert.
char buffer_1[ ] = "C:\\path1\\path2";
char *lpStr1;
lpStr1 = buffer_1;

// Print the path before the root is stripped.
cout << "The contents of the path before is :      " << lpStr1 << endl;

// Print the return value from the function.
cout << "The return from \"PathStripToRoot\" is :  "
 << PathStripToRoot(lpStr1) << endl;

// Print the path before the root is stripped.
cout << "The contents of the path after is :       " << lpStr1 << endl;
}
OUTPUT:
==================
The path before is :      C:\path1\path2
The return from "PathStripToRoot" is :  1
The path after is :       C:\

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathUndecorate

Removes the decoration from a path string.

VOID PathUndecorate(
  LPTSTR pszPath
);

Parameters

pszPath
[in] NULL-terminated string that contains the path. When the function returns, pszPath points to the undecorated string.

Example

The following table illustrates how strings are modified by PathUndecorate.

Initial String | Undecorated String
C:\Path\File[5].txt | C:\Path\File.txt
C:\Path\File[12] | C:\Path\File
C:\Path\File.txt | C:\Path\File.txt
C:\Path\[3].txt | C:\Path\[3].txt

Return Values

None.

Remarks

A decoration consists of a pair of square brackets with one or more digits in between, inserted immediately after the base name and before the file name extension.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathUnExpandEnvStrings

Takes a fully qualified path, and replaces several folder names with their associated environment string.

BOOL PathUnExpandEnvStrings(
    LPCTSTR pszPath,
    LPTSTR pszBuf,
    UINT cchBuf
);

Parameters

pszPath
[in] Path to be unexpanded.
pszBuf
[out] Buffer to receive the unexpanded string. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
cchBuf
[in] Number of characters in the buffer.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

The following folders' paths will be replaced by their equivalent environment string.

Folder | Environment String
The current user's profile folder | %USERPROFILE%
The All Users profile folder | %ALLUSERSPROFILE%
The Program Files folder | %ProgramFiles%
The system root folder | %SystemRoot%
The system drive letter | %SystemDrive%

Note: %USERPROFILE% is relative to the user making the call. This function does not work if the user is being impersonated from a service. For further discussion of access control issues, see Access Control.

The environment variables listed in the above table might not all be set on any particular system. If an environment variable is not set, it will not be unexpanded. In particular, none of these variables are set for the default environment of Windows® 95 or Windows® 98. The %ProgramFiles% variable is new for Windows® 2000, and will typically not be set on Windows NT® 4.0 systems.

See Also

DoEnvironmentSubst

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4 with Internet Explorer 5 or later installed).
Windows 95/98/Me: Requires Windows 98 or Windows 95 with Internet Explorer 5 or later.
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathUnmakeSystemFolder

Removes the attributes from a folder that make it a system folder. This folder must actually exist in the file system.

BOOL PathUnmakeSystemFolder(
    LPTSTR pszPath
    );

Parameters

pszPath
Address of a character buffer that contains the name of an existing folder that will have the system folder attributes removed.

Return Values

Returns nonzero if successful, or zero otherwise.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


PathUnquoteSpaces

Removes quotes from the beginning and end of a path.

void PathUnquoteSpaces(
    LPTSTR lpsz
    );

Parameters

lpsz
Address of the path from which to remove the quotes.

Return Values

No return value.

Example

#include <windows.h>
#include <iostream.h>
#include "Shlwapi.h"

void main( void )
{

    // Path to convert.
char buffer_1[ ] = "\"C:\\path1\\path2\"";
char *lpStr1;
lpStr1 = buffer_1;

    // Print the path before quotes are stripped.
cout << "The contents of the path before is :  " << lpStr1 << endl;

    // Call the "PathUnquoteSpaces".
PathUnquoteSpaces(lpStr1);

// Print the path after quotes are stripped.
cout << "The contents of the path after is :  " << lpStr1 << endl;
}
OUTPUT:
==================
The path before is :  "C:\path1\path2"
The path after is  :   C:\path1\path2

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHSkipJunction

Checks a bind context to see if it is safe to bind to a particular component object.

BOOL SHSkipJunction(
    IBindCtx *pbc,
    const CLSID *pclsid
);

Parameters

pbc
[in] Pointer to an IBindCtx interface that specifies the bind context you want to check.
pclsid
[in] Pointer to a variable of type CLSID that specifies the CLSID of the object being tested to see if it must be skipped. Typically, this is the CLSID of the object that IShellFolder::BindToObject is about to create.

Return Values

Returns TRUE if the object specified by CLSID must be skipped, or FALSE otherwise.

Remarks

This function can be used to avoid infinite cycles in namespace binding. For example, a folder shortcut that refers to a folder above it in the namespace tree can produce an infinitely recursive loop.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlApplyScheme

Takes a URL string, determines a scheme for it, and returns a string with an appropriate prefix.

HRESULT UrlApplyScheme(
  LPCTSTR pszIn,
  LPTSTR pszOut,
  LPDWORD pcchOut,
  DWORD dwFlags
);

Parameters

pszIn
[in] A NULL-terminated URL string.
pszOut
[out] A buffer to receive a NULL-terminated string, set to the URL specified by pszIn, converted to the standard scheme://URL_string format.
pcchOut
[in/out] Address of a value set to the number of characters in the pszOut buffer. When the function returns, the value depends on whether the function is successful or returns E_POINTER. For other return values, the value of this parameter is meaningless.
dwFlags
[in] Flags that specify how to determine the scheme. The following flags can be combined.
URL_APPLY_DEFAULT
Apply the default scheme if UrlApplyScheme can't determine one. The default prefix is stored in the registry but is typically "http".
URL_APPLY_GUESSSCHEME
Attempt to determine the scheme by examining pszIn.
URL_APPLY_GUESSFILE
Attempt to determine a file URL from pszIn.
URL_APPLY_FORCEAPPLY
Force UrlApplyScheme to determine a scheme for pszIn.

Return Values

S_OK
A scheme was determined. pszOut points to a string containing the URL with the scheme's prefix. The value of pcchOut is set to the number of characters in the string, not counting the terminating NULL character.
S_FALSE
There were no errors, but no prefix was prepended.
E_POINTER
The buffer was too small. The value of pcchOut is set to the minimum number of characters that the buffer must be able to contain, including the terminating NULL character.
Other errors
A standard OLE error value is returned.

Remarks

If the URL has a valid scheme, the string will not be modified. However, almost any combination of two or more characters followed by a colon will be parsed as a scheme. Valid characters include some common punctuation marks, such as ".". If your input string fits this description, UrlApplyScheme may treat it as valid and not apply a scheme. To force the function to apply a scheme to a URL, set the URL_APPLY_FORCEAPPLY and URL_APPLY_DEFAULT flags in dwFlags. This combination of flags forces the function to apply a scheme to the URL. Typically, the function will not be able to determine a valid scheme. The second flag guarantees that, if no valid scheme can be determined, the function will apply the default scheme to the URL.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlCanonicalize

Takes a URL string and converts it into canonical form.

HRESULT UrlCanonicalize(
  LPCTSTR pszUrl,
  LPTSTR pszCanonicalized,
  LPDWORD pcchCanonicalized,
  DWORD dwFlags
);

Parameters

pszUrl
[in] Pointer to a URL string. If it does not refer to a file, it must include a valid scheme such as "http://".
pszCanonicalized
[out] A pointer to a NULL-terminated string used to return the converted URL.
pcchCanonicalized
[out] The number of characters in pszCanonicalized.
dwFlags
[in] Flags that specify how the URL will be converted to canonical form. The following flags can be combined.
URL_DONT_SIMPLIFY
Treat '/./' and '/../' in a URL string as literal characters, not as shorthand for navigation. See Remarks for further discussion.
URL_ESCAPE_PERCENT
Convert any occurrence of '%' to its escape sequence.
URL_ESCAPE_SPACES_ONLY
Replace only spaces with escape sequences. This flag takes precedence over URL_ESCAPE_UNSAFE, but does not apply to opaque URLs.
URL_ESCAPE_UNSAFE
Replace unsafe values with their escape sequences. This flag applies to all URLs, including opaque URLs.
URL_PLUGGABLE_PROTOCOL
Combine URLs with client-defined pluggable protocols, according to the W3C specification. This flag does not apply to standard protocols such as ftp, http, gopher, and so on. If this flag is set, UrlCombine will not simplify URLs, so there is no need to also set URL_DONT_SIMPLIFY.
URL_UNESCAPE
Unescape any escape sequences that the URLs contain, with two exceptions. The escape sequences for '?' and '#' will not be unescaped. If one of the URL_ESCAPE_XXX flags is also set, the two URLs will unescaped, then combined, then escaped.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Remarks

This function will do such tasks as replacing unsafe characters with their escape sequences and collapsing sequences like "..\...".

If a URL string contains '/../' or '/./', UrlCanonicalize will normally treat the characters as indicating navigation in the URL hierarchy. The function will simplify the URLs before combining them. For instance "/hello/cruel/../world" will be simplified to "/hello/world". If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function will not simplify URLs. In this case, "/hello/cruel/../world" will be left as is.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlCombine

Takes a relative URL and its base and returns a URL in canonical form.

HRESULT UrlCombine(
  LPCTSTR pszBase,
  LPCTSTR pszRelative,
  LPTSTR pszCombined,
  LPDWORD pcchCombined,
  DWORD dwFlags
);

Parameters

pszBase
[in] Pointer to a string with the base URL.
pszRelative
[in] Pointer to a string with the relative URL.
pszCombined
[out] Pointer to a buffer to receive a NULL-terminated string containing the combined URL.
pcchCombined
[in/out] Pointer to a value set to the number of characters in the pszCombined buffer. When the function returns, the value depends on whether the function is successful or returns E_POINTER. For other return values, the value of this parameter is meaningless.
dwFlags
[in] Flags that specify how the URL will be converted to canonical form. The following flags can be combined.
URL_DONT_SIMPLIFY
Treat '/./' and '/../' in a URL string as literal characters, not as shorthand for navigation. See Remarks for further discussion.
URL_ESCAPE_PERCENT
Convert any occurrence of '%' to its escape sequence.
URL_ESCAPE_SPACES_ONLY
Replace only spaces with escape sequences. This flag takes precedence over URL_ESCAPE_UNSAFE, but does not apply to opaque URLs.
URL_ESCAPE_UNSAFE
Replace unsafe values with their escape sequences. This flag applies to all URLs, including opaque URLs.
URL_PLUGGABLE_PROTOCOL
Combine URLs with client-defined pluggable protocols, according to the W3C specification. This flag does not apply to standard protocols such as ftp, http, gopher, and so on. If this flag is set, UrlCombine will not simplify URLs, so there is no need to also set URL_DONT_SIMPLIFY.
URL_UNESCAPE
Unescape any escape sequences that the URLs contain, with two exceptions. The escape sequences for '?' and '#' will not be unescaped. If one of the URL_ESCAPE_XXX flags is also set, the two URLs will be unescaped, then combined, then escaped.

Return Values

S_OK
pszCombined points to a string containing the combined URLs. The value of pcchCombined is set to the number of characters in the string, not counting the terminating NULL character.
E_POINTER
The buffer was too small. The value of pcchCombined is set to the minimum number of characters that the buffer must be able to contain, including the terminating NULL character.
Other errors
A standard OLE error value is returned.

Remarks

Items between slashes are treated as hierarchical identifiers; the last item specifies the document itself. You must enter a slash (/) after the document name to append more items; otherwise, UrlCombine exchanges one document for another. For example:

hRetVal = UrlCombine (TEXT ("http://xyz/test/abc"),
TEXT ("bar"), lpszCombined, &dwLength, 0);
The preceding code returns the URL http://xyz/test/bar. If you want the combined URL to be http://xyz/test/abc/bar, use the following call to UrlCombine:

hRetVal = UrlCombine (TEXT ("http://xyz/test/abc/"),
TEXT ("bar"), lpszCombined, &dwLength, 0);

If a URL string contains '/../' or '/./', UrlCombine will usually treat the characters as if they indicated navigation in the URL hierarchy. The function will simplify the URLs before combining them. For instance, "/hello/cruel/../world" will be simplified to "/hello/world". If the URL_DONT_SIMPLIFY flag is set in dwFlags, the function will not simplify URLs. In this case, "/hello/cruel/../world" will be left as it stands.

See Also

UrlCanonicalize

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlCompare

Makes a case-sensitive comparison of two URL strings.

int UrlCompare(
  LPCTSTR pszURL1,
  LPCTSTR pszURL2,
  BOOL fIgnoreSlash
);

Parameters

pszURL1
[in] NULL-terminated string with the first URL.
pszURL2
[in] NULL-terminated string with the second URL.
fIgnoreSlash
[in] Value that is set to TRUE to have UrlCompare ignore a trailing '/' character on either or both URLs.

Return Values

Returns zero if the two strings are equal, apart from a trailing '\' character if fIgnoreSlash is set to TRUE. Returns a negative integer if the string pointed to by pszURL1 is less than the string pointed to by pszURL2. Otherwise, it returns a positive integer.

Remarks

For best results, you should first canonicalize the URLs with UrlCanonicalize. Then, compare the canonicalized URLs with UrlCompare.

See Also

StrCmp

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlCreateFromPath

Takes a DOS path and converts it to a canonicalized URL.

HRESULT UrlCreateFromPath(
  LPCTSTR pszPath,
  LPTSTR pszUrl,
  LPDWORD pcchUrl,
  DWORD dwReserved
);

Parameters

pszPath
Pointer to the string with the DOS path.
pszUrl
Value used to return the URL.
pcchPath
Length of pszUrl.
dwReserved
Reserved. Set this parameter to NULL.

Return Values

Returns S_FALSE if pszPath is already in URL format. In this case, pszPath will simply be copied to pszUrl. Otherwise, it returns S_OK if successful or a standard OLE error value if not.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlEscape

Converts unsafe characters, such as spaces, into their corresponding escape sequences.

HRESULT UrlEscape(
  LPCTSTR pszURL,
  LPTSTR pszEscaped,
  LPDWORD pcchEscaped,
  DWORD dwFlags
);

Parameters

pszURL
[in] Pointer to a NULL-terminated string with the URL.
pszEscaped
[out] Pointer to a NULL-terminated string containing the string pointed to by pszURL, with unsafe characters converted to their escape sequences.
pcchEscaped
[in/out] Number of characters in the buffer pointed to by pszEscaped. On entry, the value pcchEscaped points to is set to the size of the buffer. When the function returns, the value pcchEscaped points to is set to the number of characters written to that buffer, not counting the terminating NULL character. If an E_POINTER error code is returned, the buffer was too small, and the value pcchEscaped points to is set to the required number of characters in the buffer. If any other errors are returned, the value that pcchEscaped points to is undefined.
dwFlags
[in] Flags that control which characters are escaped. It can be a combination of the following flags.
Flag | Description
URL_DONT_ESCAPE_EXTRA_INFO | Don't convert the # or ? character, or any characters following them in the string.
URL_ESCAPE_SPACES_ONLY | Only escape space characters. This flag cannot be combined with URL_ESCAPE_PERCENT or URL_ESCAPE_SEGMENT_ONLY.
URL_ESCAPE_PERCENT | Escape the % character. By default, this character is not escaped.
URL_ESCAPE_SEGMENT_ONLY | Escape the sections following the server component, but not the extra information sections following a # or ? character.

Return Values

Returns an OLE success code if successful. The value pointed to by pcchEscaped will be set to the number of characters written to the output buffer, excluding the terminating NULL. If the buffer was too small, E_POINTER is returned, and the value pointed to by pcchEscaped will be set to the required buffer size. Otherwise, an OLE error value is returned.

Remarks

Unsafe characters are those characters that may be altered during transport across the internet. This functions converts unsafe characters into their equivalent "%xy" escape sequences.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlEscapeSpaces

A macro that converts space characters into their corresponding escape sequence.

HRESULT UrlEscapeSpaces(
  LPCTSTR pszURL,
  LPTSTR pszEscaped,
  LPDWORD pcchEscaped
);

Parameters

pszURL
[in] Pointer to a URL string. If it does not refer to a file, it must include a valid scheme such as "http://".
pszEscaped
[out] Pointer to a NULL-terminated string containing the string pointed to by pszURL, with space characters converted to their escape sequence.
pcchEscaped
[out] Number of characters in pszEscaped.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Remarks

UrlEscapeSpaces is equivalent to:

UrlCanonicalize(pszUrl, pszEscaped, pcchEscaped, URL_ESCAPE_SPACES_ONLY
  |URL_DONT_ESCAPE_EXTRA_INFO )

See Also

UrlCanonicalize

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlGetLocation

Retrieves the location from a URL.

LPCTSTR UrlGetLocation(
  LPCTSTR pszURL,
);

Parameters

pszURL
[in] Pointer to a NULL-terminated string that contains the location.

Return Values

Returns a pointer to a NULL-terminated string with the location, or NULL otherwise.

Remarks

The location is the segment of the URL starting with a ? or # character. If a file URL has a query string, the returned string includes the query string.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlGetPart

Takes a URL string and returns a specified part.

HRESULT UrlGetPart(
  LPCTSTR pszIn,
  LPTSTR pszOut,
  LPDWORD pcchOut,
  DWORD dwPart,
  DWORD dwFlags
);

Parameters

pszIn
[in] NULL-terminated string that contains the URL.
pszOut
[out] A buffer that will receive a NULL-terminated string with the specified part.
pcchOut
[in/out] Address of a value set to the number of characters in the pszOut buffer. When the function returns, the value depends on whether the function is successful or returns E_POINTER. For other return values, the value of this parameter is meaningless.
dwPart
[in] Flags that specify which part of the URL to retrieve. It can have one of the following values.
Flag | Description
URL_PART_HOSTNAME | The host name.
URL_PART_PASSWORD | The password.
URL_PART_PORT | The port number.
URL_PART_QUERY | The query portion of the URL.
URL_PART_SCHEME | The URL scheme.
URL_PART_USERNAME | The username.
dwFlags

[in] Flag that can be set to keep the URL scheme, in addition to the part that is specified by dwPart.

Flag | Description
URL_PARTFLAG_KEEPSCHEME | Keep the URL scheme.

Return Values

Returns an OLE success code if successful. The value pointed to by pcchOut will be set to the number of characters written to the output buffer, excluding the terminating NULL. If the buffer was too small, E_POINTER is returned, and the value pointed to by pcchOut will be set to the minimum number of characters that the buffer must be able to contain, including the terminating NULL character. Otherwise, an OLE error value is returned.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlHash

Hashes a URL string.

HRESULT UrlHash(
  LPCTSTR pszURL,
  LPBYTE pbHash,
  DWORD cbHash
);

Parameters

pszURL
[in] Pointer to a NULL-terminated string with the URL.
pbHash
[out] Buffer to receive the hashed array.
cbHash
[in] Number of elements in pbHash. It should be no larger than 256.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Remarks

For example, to hash a URL into a single byte, set cbHash = sizeof(BYTE) and pbHash = (LPBYTE)&bHashedValue, where bHashedValue is a one-byte buffer. To hash a URL into a DWORD, set cbHash = sizeof(DWORD) and pbHash = (LPBYTE)&dwHashedValue, where dwHashedValue is a DWORD buffer.

See Also

HashData

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlIs

Tests whether or not a URL is a specified type.

BOOL UrlIs(
    LPCTSTR pszUrl,
    URLIS UrlIs
);

Parameters

pszUrl
[in] Pointer to a string containing the URL.
UrlIs
[in] Type of URL to be tested for. UrlIs can take one of the following values:
URLIS_APPLIABLE
Attempt to determine a valid scheme for the URL.
URLIS_DIRECTORY
Does the URL string end with a directory?
URLIS_FILEURL
Is the URL a file URL?
URLIS_HASQUERY
Does the URL have an appended query string?
URLIS_NOHISTORY
Is the URL a "No History" URL?
URLIS_OPAQUE
Is the URL opaque?
URLIS_URL
Is the URL valid?

Return Values

For all but one of the URL types, UrlIs returns TRUE if the URL is the specified type, or FALSE if not. If UrlIs is set to URLIS_APPLIABLE, UrlIs will attempt to determine the URL scheme. If the function is able to determine a scheme, it returns TRUE, or FALSE otherwise.

See Also

UrlIsFileUrl, UrlIsNoHistory, UrlIsOpaque

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlIsFileUrl

Tests a URL to determine if it is a file URL.

BOOL UrlIsFileUrl(
    LPCTSTR pszUrl
);

Parameters

pszUrl
Pointer to a NULL-terminated string containing the URL.

Return Values

Returns a non-zero value if the URL is a file URL, or zero otherwise.

Remarks

A file URL has the form "File://xxx". UrlIsFileUrl is actually one of the following macros, depending on whether ANSI or Unicode is selected.

#define  UrlIsFileUrlA(pszURL) UrlIsA(pszURL, URLIS_FILEURL)
#define  UrlIsFileUrlW(pszURL) UrlIsW(pszURL, URLIS_FILEURL)

See Also

UrlIs

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlIsNoHistory

Returns whether or not a URL is a No History URL.

BOOL UrlIsNoHistory(
  LPCTSTR pszURL,
);

Parameters

pszURL
[in] NULL-terminated string with the URL.

Return Values

Returns a non-zero value if the URL is a No History URL, or zero otherwise.

Remarks

A No History URL is a URL that browsers typically do not include in their navigation history. This function is equivalent to:

UrlIs(pszURL, URLIS_NOHISTORY)

See Also

UrlIs

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlIsOpaque

Returns whether a URL is opaque.

BOOL UrlIsOpaque(
  LPCTSTR pszURL,
);

Parameters

pszURL
[in] NULL-terminated string with the URL.

Return Values

Returns a non-zero value if the URL is opaque, or zero otherwise.

Remarks

A URL that has a scheme that is not followed by two slashes (//) is opaque. For example, mailto:xyz@somecompany.com is an opaque URL. Opaque URLs cannot be separated into the standard URL heirarchy. UrlIsOpaque is equivalent to:

UrlIs(pszURL, URLIS_OPAQUE)

See Also

UrlIs

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlUnescape

Converts escape sequences back into ordinary characters.

HRESULT UrlUnescape(
  LPTSTR pszURL,
  LPTSTR pszUnescaped,
  LPDWORD pcchUnescaped,
  DWORD dwFlags
);

Parameters

pszURL
[in/out] Pointer to a NULL-terminated string with the URL. If dwFlags is set to URL_UNESCAPE_INPLACE, the converted string is returned through this parameter.
pszUnescaped
[out] Pointer to a buffer that will receive a NULL-terminated string containing the unescaped version of pszURL. If URL_UNESCAPE_INPLACE is set in dwFlags, this parameter is ignored.
pcchUnescaped
[in/out] Number of characters in the buffer pointed to by pcchUnescaped. On entry, the value pcchUnescaped points to is set to the size of the buffer. If the function returns a success code, the value that pcchUnescaped points to is set to the number of characters written to that buffer, not counting the terminating NULL character. If an E_POINTER error code is returned, the buffer was too small, and the value pcchUnescaped points to is set to the required number of characters that the buffer must be able to contain. If any other errors are returned, the value that pcchUnescaped points to is undefined.
dwFlags
[in] Flags that control which characters are unescaped. It can be a combination of the following flags.
Flag | Description
URL_DONT_UNESCAPE_EXTRA_INFO | Don't convert the # or ? character, or any characters following them in the string.
URL_UNESCAPE_INPLACE | Use pszURL to return the converted string instead of pszUnescaped.

Return Values

Returns an OLE success code if successful. If the URL_UNESCAPE_INPLACE flag is not set, the value pointed to by pcchUnescaped will be set to the number of characters in the output buffer pointed to by pszUnescaped. Returns E_POINTER if the URL_UNESCAPE_INPLACE flag is not set and the output buffer is too small. The pcchUnescaped parameter will be set to the required buffer size. Otherwise, returns an OLE error value.

Remarks

An escape sequence has the form "%xy".

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


UrlUnescapeInPlace

A macro that converts escape sequences back into ordinary characters and overwrites the original string.

HRESULT UrlUnescapeInPlace(
  LPTSTR pszURL,
  DWORD dwFlags
);

Parameters

pszURL
[in/out] Pointer to a NULL-terminated string that contains the URL. The converted string is returned through this parameter.
dwFlags
[in] Flags that control which characters are unescaped.
URL_DONT_UNESCAPE_EXTRA_INFO Don't convert the # or ? character, or any characters following them in the string.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Remarks

UrlUnescapeInPlace is equivalent to:

UrlUnescape(pszUrl, NULL, NULL, dwFlags | URL_UNESCAPE_INPLACE)

See Also

UrlUnescape

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


AssocCreate

Returns a pointer to an IQueryAssociations interface.

HRESULT AssocCreate(
    CLSID clsid,
    REFIID riid,
    LPVOID *pqa
);

Parameters

clsid
[in] CLSID of the object that exposes the interface. This parameter must be set to CLSID_QueryAssociations.
riid
[in] REFIID of the interface. This parameter must be set to IID_IQueryAssociations.
pqa
[out] Pointer to the interface.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


AssocQueryKey

Searches for and retrieves a file association-related key from the registry.

HRESULT AssocQueryKey(
    ASSOCF flags,
    ASSOCKEY key,
    LPCTSTR pszAssoc,
    LPCTSTR pszExtra,
    HKEY *phkeyOut
);

Parameters

flags
[in] Flags that can be used to control the search. It can be any combination of ASSOCF values, except that only one ASSOCF_INIT value can be included.
key
[in] ASSOCKEY value that specifies the type of key that is to be returned.
pszAssoc

[in] Pointer to a NULL-terminated string that is used to determine the root key. Four types of strings can be used.

String type | Description
File name extension | A file name extension, such as .txt.
CLSID | A CLSID GUID in the standard "{GUID}" format.
ProgID | An application's ProgID, such as Word.Document.8.
Executable name | The name of an application's .exe file. The ASSOCF_OPEN_BYEXENAME flag must be set in flags.
pszExtra
[in] Pointer to an optional NULL-terminated string with additional information about the location of the string. It is normally set to a Shell verb such as open. Set this parameter to NULL if it is not used.
phkeyOut
[out] Pointer to the key's HKEY value.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

This function is a wrapper for the IQueryAssociations interface. It is intended to simplify the process of using the interface. For further discussion of how the file association functions work, see IQueryAssociations.

Requirements

Version 5.00 and later of Shlwapi.dll
Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


AssocQueryString

Searches for and retrieves a file association-related string from the registry.

HRESULT AssocQueryString(
    ASSOCF flags,
    ASSOCSTR str,
    LPCTSTR pszAssoc,
    LPCTSTR pszExtra,
    LPTSTR pszOut,
    DWORD *pcchOut
);

Parameters

flags
[in] Flags that can be used to control the search. It can be any combination of ASSOCF values, except that only one ASSOCF_INIT value can be included.
str
[in] ASSOCSTR value that specifies the type of string that is to be returned.
pszAssoc

[in] Pointer to a NULL-terminated string that is used to determine the root key. Four types of strings can be used.

String type | Description
File name extension | A file name extension, such as .txt.
CLSID | A CLSID GUID in the standard "{GUID}" format.
ProgID | An application's ProgID, such as Word.Document.8.
Executable name | The name of an application's .exe file. The ASSOCF_OPEN_BYEXENAME flag must be set in flags.
pszExtra
[in] Optional NULL-terminated string with additional information about the location of the string. It is normally set to a Shell verb such as open. Set this parameter to NULL if it is not used.
pszOut
[out] NULL-terminated string used to return the requested string.
pcchOut
[in/out] Pointer to a value that is set to the number of characters in the pszOut buffer. When the function returns, it will be set to the number of characters actually placed in the buffer. If the ASSOCF_NOTRUNCATE flag is set in flags and the buffer specified in pcchOut is too small, the function returns E_POINTER and the value is set to the required size of the buffer.

Return Values

Returns S_OK if successful, E_POINTER if the buffer is too small, or an OLE error value otherwise.

Remarks

This function is a wrapper for the IQueryAssociations interface. It is intended to simplify the process of using this interface. For further discussion of how the file association functions work, see IQueryAssociations.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


AssocQueryStringByKey

Searches for and retrieves a file association-related string from the registry starting from a specified key.

HRESULT AssocQueryStringByKey(
    ASSOCF flags,
    ASSOCSTR str,
    HKEY hkAssoc,
    LPCTSTR pszExtra,
    LPTSTR pszOut,
    DWORD *pcchOut
);

Parameters

flags
[in] Flags that can be used to control the search. It can be any combination of ASSOCF values, except that only one ASSOCF_INIT value can be included.
str
[in] ASSOCSTR value that specifies the type of string that is to be returned.
hkAssoc
[in] HKEY value of the key that will be used as a root key. The search will look only below this key.
pszExtra
[in] Pointer to an optional NULL-terminated string with additional information about the location of the string. It is normally set to a Shell verb such as open. Set this parameter to NULL if it is not used.
pszOut
[out] Pointer to a NULL-terminated string used to return the requested string.
pcchOut
[in/out] Pointer to a value that is set to the number of characters in the pszOut buffer. When the function returns, it will be set to the number of characters actually placed in the buffer. If the ASSOCF_NOTRUNCATE flag is set in flags and the buffer specified in pcchOut is too small, the function returns E_POINTER and the value is set to the required size of the buffer.

Return Values

Returns S_OK if successful, E_POINTER if the buffer is too small, or an OLE error value otherwise.

Remarks

This function is a wrapper for the IQueryAssociations interface. It is intended to simplify the process of using this interface. For further discussion of how the file association functions work, see IQueryAssociations.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHCopyKey

Recursively copies the subkeys and values of the source subkey to the destination key.

DWORD SHCopyKey(
    HKEY hkeySrc,
    LPCTSTR szSrcSubKey,
    HKEY hkeyDest,
    DWORD fReserved
);

Parameters

hkeySrc
Handle to the source key (for example, HKEY_CURRENT_USER).
szSrcSubKey
Subkey whose subkeys and values are to be copied.
hkeyDest
Destination key.
fReserved
Reserved. Pass NULL.

Return Values

Returns ERROR_SUCCESS if successful, or one of the nonzero error codes defined in Winerror.h otherwise. Use FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHDeleteEmptyKey

Deletes an empty key.

DWORD SHDeleteEmptyKey(
    HKEY     hkey,
    LPCTSTR  pszSubKey
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Microsoft® Windows® 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Microsoft® Windows NT® only)
HKEY_USERS
pszSubKey
Address of a null-terminated string specifying the name of the key to delete.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

Note: SHDeleteEmptyKey will not delete a key if it contains any subkeys or values. Use SHDeleteKey instead.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHDeleteKey

Deletes a subkey and all its descendants. The function will remove the key and all of the key's values from the registry.

DWORD SHDeleteKey(
    HKEY     hkey,
    LPCTSTR  pszSubKey
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pszSubKey
Address of a null-terminated string specifying the name of the key to delete.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHDeleteValue

Deletes a named value from the specified registry key.

DWORD SHDeleteValue(
    HKEY    hkey,
    LPCTSTR pszSubKey,
    LPCTSTR pszValue
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pszSubKey
Address of a null-terminated string specifying the name of the subkey for which to change the value.
pszValue
Address of the value to be deleted.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHEnumKeyEx

Enumerates the subkeys of the specified open registry key.

DWORD SHEnumKeyEx(
    HKEY hkey,
    DWORD dwIndex,
    LPTSTR pszName,
    LPDWORD pcchName
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
dwIndex
Index of the subkey to retrieve. This parameter should be zero for the first call and incremented for subsequent calls.
pszName
Address of a character buffer that receives the enumerated key name.
pcchName
Address of a DWORD that, on entry, contains the size of the buffer at pszName. On exit, this contains the number of characters that were copied to pszName.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a textual description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHEnumValue

Enumerates the values of the specified open registry key.

DWORD SHEnumValue(
    HKEY hkey,
    DWORD dwIndex,
    LPTSTR pszValueName,
    LPDWORD pcchValueName,
    LPDWORD pdwType,
    LPVOID pvData,
    LPDWORD pcbData
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
dwIndex
Index of the value to retrieve. This parameter should be zero for the first call and incremented for subsequent calls.
pszValueName
Address of a character buffer that receives the enumerated value name. The size of this buffer is specified in pcchVlaueName.
pcchValueName
Address of a DWORD that, on entry, contains the size of the buffer at pszValueName. On exit, this contains the number of characters that were copied to pszValueName.
pdwType
Address of a DWORD that receives the data type of the value. These are the same values as those described under the lpType parameter of RegEnumValue.
pvData
Address of a buffer that receives the data for the value entry. The size of this buffer is specified in pcbData. This parameter can be NULL if the data is not required.
pcbData
Address of a DWORD that, on entry, contains the size of the buffer at pvData. On exit, this contains the number of bytes that were copied to pvData.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a textual description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHGetValue

Retrieves a registry value.

DWORD SHGetValue(
    HKEY     hkey,
    LPCTSTR  pszSubKey,
    LPCTSTR  pszValue,
    LPDWORD  pdwType,
    LPVOID   pvData,
    LPDWORD  pcbData
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pszSubKey
Address of a null-terminated string that specifies the name of the subkey from which to retrieve the value.
pszValue
Address of the value.
pdwType
Type of value. For more information, see Registry Data Types.
pvData
Address of the destination data buffer.
pcbData
Size of the destination data buffer.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

Note If your application must set/retrieve a series of values in the same key, it is better to open the key once and set/retrieve the values with the regular Microsoft® Win32® registry functions rather than use this function repeatedly.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHQueryInfoKey

Retrieves information about a specified registry key.

DWORD SHQueryInfoKey(
    HKEY hkey,
    LPDWORD pcSubKeys,
    LPDWORD pcchMaxSubKeyLen,
    LPDWORD pcValues,
    LPDWORD pcchMaxValueNameLen
);

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pcSubKeys
Address of a DWORD that receives the number of subkeys under the specified key.
pcchMaxSubKeyLen
Address of a DWORD that receives the number of characters in the name of the subkey with the largest name.
pcValues
Address of a DWORD that receives the number of values under the specified key.
pcchMaxValueNameLen
Address of a DWORD that receives the number of characters in the name of the value with the largest name.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a textual description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHQueryValueEx

Opens a registry key and queries it for a specific value.

DWORD SHQueryValueEx(
    HKEY     hkey,
    LPCTSTR  pszValue,
    LPDWORD  pdwReserved,
    LPDWORD  pdwType,
    LPVOID   pvData,
    LPDWORD  pcbData
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pszValue
Address of the null-terminated string that contains the name of the value to be queried.
pdwReserved
Reserved; must be null.
pdwType
Address of the variable that receives the key's value type. For more information, see Registry Data Types.
pvData
Address of the buffer that receives the value's data. This parameter can be NULL if the data is not required.
pcbData
Address of the variable that specifies the size, in bytes, of the buffer pointed to by the pvData parameter. When the function returns, this variable contains the size of the data copied to pvData.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegCloseUSKey

Closes a handle to a user-specific registry key.

DWORD SHRegCloseUSKey(
    HUSKEY hUSKey,
);

Parameters

hUSKey
Handle to a user-specific key that is currently open.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. Use FormatMessage with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegCreateUSKey

Creates or opens a user-specific registry key.

LONG SHRegCreateUSKey(
    LPCTSTR   pszPath,
    REGSAM    samDesired,
    HUSKEY    hRelativeUSKey,
    PHUSKEY   phNewUSKey,
    DWORD     dwFlags
    );

Parameters

pszPath
[in] Address of NULL-terminated string that contains the registry path of the key to be created or opened.
samDesired
[in] Desired security access. For more information on security access, see REGSAM.
hRelativeUSKey
[in] Key to be used as a base for relative paths. If pszPath is a relative path, the key it specifies will be relative to hRelativeUSKey. If pszPath is an absolute path, set hRelativeUSKey to NULL. The key will then be created under HKLM or HKCU, depending the value of dwFlags.
phNewUSKey
[out] Address of an HUSKEY that receive the handle to the new key.
dwFlags
[in] Base key under which the key should be opened. This can be one or more of the following values:
SHREGSET_HKCU | Create/open the key under HKEY_CURRENT_USER. Only creates a key if it is empty.
SHREGSET_FORCE_HKCU | Create/open the key under HKEY_CURRENT_USER. Creates a key even if it is not empty.
SHREGSET_HKLM | Create/open the key under HKEY_LOCAL_MACHINE. Only creates a key if it is empty.
SHREGSET_FORCE_HKLM | Create/open the key under HKEY_LOCAL_MACHINE. Creates a key even if it is not empty.
SHREGSET_DEFAULT | Create/open the key under both HKEY_CURRENT_USER (forced) and HKEY_LOCAL_MACHINE (only if empty). This flag is the equivalent of (SHREGSET_FORCE_HKCU | SHREGSET_HKLM).

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

If you want to write values to the new key, use SHRegWriteUSValue to write each value, passing the HUSKEY handle that is returned through phNewUSKey. When you have finished, close the user-specific registry key with SHRegCloseUSKey.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegDeleteEmptyUSKey

Deletes an empty user-specific registry key.

LONG SHRegDeleteEmptyUSKey
    (HUSKEY hUSKey,
    LPCSTR pszValue,
    SHREGDEL_FLAGS delRegFlags
    );

Parameters

hUSKey
Handle to the currently open user-specific key.
pszValue
Address of the null-terminated string that specifies the empty user-defined registry key to be deleted.
delRegFlags
One of the SHREGDEL_FLAGS that specifies from which base key the key will be deleted.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

See Also

SHRegDeleteUSValue

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegDeleteUSValue

Deletes a user-specific registry value.

LONG SHRegDeleteUSValue(
    HUSKEY          hUSKey,
    LPCTSTR         pszValue,
    SHREGDEL_FLAGS  delRegFlags
    );

Parameters

hUSKey
Handle to the currently open user-specific key.
pszValue
Address of the null-terminated string that names the value to remove.
delRegFlags
One of the SHREGDEL_FLAGS that specifies from which base key the value will be deleted.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

See Also

SHRegDeleteEmptyUSKey

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegDuplicateHKey

Duplicates a registry key's HKEY handle.

HKEY SHRegDuplicateHKey(
    HKEY hkey
);

Parameters

hkey
[in] HKEY handle to be duplicated.

Return Values

Returns a duplicate of the handle specified in hkey.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegEnumUSKey

Enumerates the subkeys of a user-specific key.

DWORD SHRegEnumUSKey(
    HUSKEY hUSKey,
    DWORD dwIndex,
    LPSTR pszName,
    LPDWORD pcchName,
    SHREGENUM_FLAGS enumRegFlags
    );

Parameters

hUSKey
Handle to the currently open user-specific key.
dwIndex
Index of the subkey to retrieve. This parameter should be zero for the first call and incremented for subsequent calls.
pszName
Address of a character buffer that receives the enumerated key name.
pcchName
Address of a DWORD that, on entry, contains the size of the buffer at pszName. On exit, this contains the number of characters that were copied to pszName.
enumRegFlags
One of the SHREGENUM_FLAGS that specifies the base key in which the enumeration should take place.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a textual description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegEnumUSValue

Enumerates the values of the specified user-specific registry key.

DWORD SHRegEnumUSValue(
    HUSKEY hUSkey,
    DWORD dwIndex,
    LPTSTR pszValueName,
    LPDWORD pcchValueNameLen,
    LPDWORD pdwType,
    LPVOID pvData,
    LPDWORD pcbData,
    SHREGENUM_FLAGS enumRegFlags
    );

Parameters

hUSKey
Handle to the currently open user-specific key.
dwIndex
Index of the value to retrieve. This parameter should be zero for the first call and incremented for subsequent calls.
pszValueName
Address of a character buffer that receives the enumerated value name. The size of this buffer is specified in pcchValueName.
pcchValueNameLen
Address of a DWORD that, on entry, contains the size of the buffer at pszValueName. On exit, this contains the number of characters that were copied to pszValueName.
pdwType
Address of a DWORD that receives the data type of the value. These are the same values as those described under the lpType parameter of RegEnumValue.
pvData
Address of a buffer that receives the data for the value entry. The size of this buffer is specified in pcbData. This parameter can be NULL if the data is not required.
pcbData
Address of a DWORD that, on entry, contains the size of the buffer at pvData. On exit, this contains the number of bytes that were copied to pvData.
enumRegFlags
One of the SHREGENUM_FLAGS that specifies the base key in which the enumeration should take place.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a textual description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegGetBoolUSValue

Retrieves a user-specific Boolean value from the registry.

BOOL SHRegGetBoolUSValue(
    LPCTSTR pszSubKey,
    LPCTSTR pszValue,
    BOOL fIgnoreHKCU,
    BOOL fDefault
);

Parameters

pszSubKey
[in] Pointer to a null-terminated string with the name of the subkey relative to HKLM and HKCU. For example: "Software\MyCompany\MyProduct".
pszValue
[in] Pointer to a null-terminated string that specifies the name of the value.
fIgnoreHKCU
[in] Variable that specifies which key to look under. When set to TRUE, SHRegGetUSValue ignores HKCU and returns a value from HKLM.
fDefault
[in] Value that will be returned if there is no registry value.

Return Values

Returns either the value from the registry, or fDefault if none is found.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegGetPath

Retrieves a file path from the registry, expanding environment variables as needed.

DWORD SHRegGetPath(
  HKEY hkey,
  LPCTSTR pszSubkey,
  LPCTSTR pszValue,
  LPTSTR pszPath,
  DWORD dwFlags
);

Parameters

hkey
[in] Handle to a key that is currently open, or a registry root key.
pszSubkey
[in] Pointer to a NULL-terminated string that contains the name of the subkey.
pszValue
[in] Pointer to a NULL-terminated string that contains the name of the value that holds the unexpanded path string.
pszPath
[out] Buffer to hold the expanded path. The size of this buffer should be set to MAX_PATH to ensure that it is large enough to hold the returned string.
dwFlags
Reserved.

Return Values

Returns ERROR_SUCCESS if successful, or a Microsoft® Windows® error code otherwise.

Remarks

The data type of the specified registry value must be either REG_EXPAND_SZ or REG_SZ. If it has the REG_EXPAND_SZ type, any environment variables in the registry string will be expanded with ExpandEnvironmentStrings. If it has the REG_SZ data type, environment variables will not be expanded and the string pointed to by pszPath will be identical to the string in the registry.

For Windows 2000, the following environment strings will be replaced by their equivalent path.

Environment string | Folder
%USERPROFILE% | The current user's profile folder
%ALLUSERSPROFILE% | The All Users profile folder
%ProgramFiles% | The Program Files folder
%SystemRoot% | The system root folder
%SystemDrive% | The system drive letter

Note: %USERPROFILE% is relative to the user making the call. This function does not work if the user is being impersonated from a service.

The environment variables listed in the above table might not all be set on any particular system. If an environment variable is not set, it will not be unexpanded. In particular, none of these variables are set for the default environment of Windows® 95 or Windows® 98. The %ProgramFiles% variable is new for Windows® 2000, and will typically not be set on Windows NT® 4.0 systems.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegGetUSValue

Retrieves a user-specific registry value.

LONG SHRegGetUSValue(
    LPCTSTR  pszSubKey,
    LPCTSTR  pszValue,
    LPDWORD  pdwType,
    LPVOID   pvData,
    LPDWORD  pcbData,
    BOOL     fIgnoreHKCU,
    LPVOID   pvDefaultData,
    DWORD    dwDefaultDataSize
);

Parameters

pszSubKey
[in] Pointer to a null-terminated string with the name of the subkey relative to HKLM and HKCU. For example: "Software\MyCompany\MyProduct".
pszValue
[in] Pointer to a null-terminated string with the name of the value.
pdwType
[out] Pointer to a variable that receives the key's value type. For more information, see Registry Data Types.
pvData
[out] Pointer to a buffer that will receive the value's data.
pcbData
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by pvData. When SHRegGetUSValue returns, pcbData contains the size of the data copied to pvData.
fIgnoreHKCU
[in] Variable that specifies which key to look under. When set to TRUE, SHRegGetUSValue ignores HKCU and returns a value from HKLM.
pvDefaultData
[out] Pointer to a buffer that will receive the value's default data.
dwDefaultDataSize
[in] Length, in bytes, of buffer pointed to by pvDefaultData.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

This function opens the key each time it is used. If your code involves getting a series of values from the same key, it is more efficient to open the key once with SHRegOpenUSKey and then use SHRegQueryUSValue to retrieve the data.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegOpenUSKey

Opens a user-specific registry key.

LONG SHRegOpenUSKey(
    LPCTSTR  pszPath,
    REGSAM   samDesired,
    HUSKEY   hRelativeUSKey,
    PHUSKEY  phNewUSKey,
    BOOL     fIgnoreHKCU
    );

Parameters

pszPath
[in] Pointer to a null-terminated string with the name of the subkey.
samDesired
[in] Desired security access. For more information on security access, see REGSAM.
hRelativeUSKey
[in] Key to be used as a base for relative paths. If pszPath is a relative path, the key it specifies will be relative to hRelativeUSKey. If pszPath is an absolute path, set hRelativeUSKey to NULL.
phNewUSKey
[out] Pointer to the handle of the opened key.
fIgnoreHKCU
[in] Variable that specifies which key to look under. When set to TRUE, SHRegGetUSValue ignores HKCU and returns a value from HKLM.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegQueryInfoUSKey

Retrieves information about a specified user-specific registry key.

DWORD SHRegQueryInfoUSKey(
    HUSKEY hUSKey,
    LPDWORD pcSubKeys,
    LPDWORD pcchMaxSubKeyLen,
    LPDWORD pcValues,
    LPDWORD pcchMaxValueNameLen
    SHREGENUM_FLAGS enumRegFlags
);

Parameters

hUSKey
Handle to the user-specific key that is currently open.
pcSubKeys
Address of a DWORD that receives the number of subkeys under the specified key.
pcchMaxSubKeyLen
Address of a DWORD that receives the number of characters in the largest subkey name.
pcValues
Address of a DWORD that receives the number of values under the specified key.
pcchMaxValueNameLen
Address of a DWORD that receives the number of characters in the largest value name.
enumRegFlags
One of the SHREGENUM_FLAGS that specifies the base key in which the query should take place.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a textual description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegQueryUSValue

Retrieves the type and data for a specified name associated with an open USKEY.

LONG SHRegQueryUSValue(
    HUSKEY   hUSKey,
    LPCTSTR  pszValue,
    LPDWORD  pdwType,
    LPVOID   pvData,
    LPDWORD  pcbData,
    BOOL     fIgnoreHKCU,
    LPVOID   pvDefaultData,
    DWORD    dwDefaultDataSize
    );

Parameters

hUSKey
[in] Handle to the currently open USKEY, or one of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pszValue
[out] Address of the null-terminated string that contains the name of the value to be queried.
pdwType
[out] Address of the variable that receives the key's value type. For more information, see Registry Data Types.
pvData
[out] Address of the buffer that receives the value's data. This parameter can be NULL if the data is not required.
pcbData
[in/out] Address of the variable that specifies the size, in bytes, of the buffer pointed to by the pvData parameter. When the function returns, this variable contains the size of the data copied to pvData.
fIgnoreHKCU
[in] Variable that specifies which key to look under. When set to TRUE, SHRegQueryUSValue ignores HKCU and returns a value from HKLM.
pvDefaultData
[out] Address of the default data.
dwDefaultDataSize
[in] Length, in bytes, of the default data.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

If you only need to read a single value, SHRegGetUSValue will both open the key and return the value. To use SHRegQueryUSValue, you must first open the key with SHRegOpenUSKey. However, once the key is opened, you can use SHRegQueryUSValue as many times as necessary. If you need to retrieve more than one value from the same key, using multiple calls to SHRegQueryUSValue is usually more efficient than SHRegGetUSValue, as the key is only opened once.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegSetPath

Takes a file path, replaces folder names with environment strings, and places the resulting string in the registry.

DWORD SHRegSetPath(
  HKEY hkey,
  LPCTSTR pszSubkey,
  LPCTSTR pszValue,
  LPCTSTR pszPath,
  DWORD dwFlags
);

Parameters

hkey
[in] Handle to a key that is currently open, or a registry root key.
pszSubkey
[in] Pointer to a NULL-terminated string containing the name of an existing subkey. If the subkey does not exist, SHRegSetPath will fail.
pszValue
[in] Pointer to a NULL-terminated string with the name of the value to hold the path string.
pszPath
[in] Pointer to a NULL-terminated string with a fully qualified file path.
dwFlags
Reserved.

Return Values

Returns ERROR_SUCCESS if successful, or a Microsoft® Windows® error code otherwise.

Remarks

For Windows 2000, RegSetPath uses PathUnExpandEnvStrings to convert folder names to their corresponding environment string. If any environment variables were substituted, the registry value will be set with the REG_EXPAND_SZ data type. Otherwise, it will be set with the REG_SZ data type.

The following folders' paths will be replaced by their equivalent environment string.

Folder | Environment string
The current user's profile folder | %USERPROFILE%
The All Users profile folder | %ALLUSERSPROFILE%
The Program Files folder | %ProgramFiles%
The system root folder | %SystemRoot%
The system drive letter | %SystemDrive%

Note: %USERPROFILE% is relative to the user making the call. This function does not work if the user is being impersonated from a service.

The environment variables listed in the above table might not all be set on any particular system. If an environment variable is not set, it will not be unexpanded. In particular, none of these variables are set for the default environment of Windows® 95 or Windows® 98. The %ProgramFiles% variable is new for Windows® 2000, and will typically not be set on Windows NT® 4.0 systems.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegSetUSValue

Sets a user-specific registry value.

LONG SHRegSetUSValue(
    LPCTSTR pszSubKey,
    LPCTSTR pszValue,
    DWORD   dwType,
    LPVOID  pvData,
    DWORD   cbData,
    DWORD   dwFlags
);

Parameters

pszSubKey
[in] Pointer to a null-terminated string with the name of the subkey.
pszValue
[in] Pointer to a null-terminated string that specifies the name of the value.
dwType
[in] Type of data to be stored. This parameter must be the REG_SZ type. For more information, see Registry Data Types.
pvData
[in] Address of a null-terminated string that contains the value to be set for the specified key.
cbData
[in] Length, in bytes, of the string pointed to by the pvData parameter, not including the terminating null character.
dwFlags
[in] Flags indicating where the data should be written.
SHREGSET_HKCU | Write to HKCU if empty.
SHREGSET_FORCE_HKCU | Write to HKCU.
SHREGSET_HKLM | Write to HKLM if empty.
SHREGSET_FORCE_HKLM | Write to HKLM.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

This function opens the key each time it is used. If your code involves setting a series of values in the same key, it is more efficient to open the key once with SHRegOpenUSKey and then use SHRegWriteUSValue to write the data.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHRegWriteUSValue

Writes a user-specific registry value.

LONG SHRegWriteUSValue(
    HUSKEY  hUSKey,
    LPCTSTR pszValue,
    DWORD   dwType,
    LPVOID  pvData,
    DWORD   cbData,
    DWORD   dwFlags
);

Parameters

hUSKey
[in] Handle to the currently open USKEY.
pszValue
[in] Address of the null-terminated string that specifies the name of the value.
dwType
[in] Type of data to be stored.
pvData
[in] Address of a null-terminated string that contains the value to be set for the specified key.
cbData
[in] Length, in bytes, of the string pointed to by the pvData parameter, not including the terminating null character.
dwFlags
[in] Flags indicating where the data should be written.
SHREGSET_HKCU | Write to HKCU if empty.
SHREGSET_FORCE_HKCU | Write to HKCU.
SHREGSET_HKLM | Write to HKLM if empty.
SHREGSET_FORCE_HKLM | Write to HKLM.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Remarks

If you only need to write a single value, SHRegSetUSValue will both open the key and write the value. To use SHRegWriteUSValue, you must first open the key with SHRegOpenUSKey. Once the key is opened, you can use SHRegWriteUSValue as many times as necessary. If you need to write more than one value on the same key, using multiple calls to SHRegWriteUSValue is usually more efficient than SHRegSetUSValue, as the key is only opened once.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHSetValue

Sets the value of a registry key.

DWORD SHSetValue(
    HKEY     hkey,
    LPCTSTR  pszSubKey,
    LPCTSTR  pszValue,
    DWORD    dwType,
    LPCVOID  pvData,
    DWORD    cbData
    );

Parameters

hkey
Handle to the currently open key, or any of the following predefined values:
HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_DYN_DATA (Windows 95 only)
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA (Windows NT only)
HKEY_USERS
pszSubKey
Address of a null-terminated string that specifies the name of the subkey with which a value is associated. This can be NULL or a pointer to an empty string. In this case, the value will be added to the key identified by the hKey parameter.
pszValue
Address of a null-terminated string that specifies the value.
dwType
Type of data to be stored. This parameter must be the REG_SZ type. For more information, see Registry Data Types.
pvData
Address of a null-terminated string that contains the value to set for the specified key.
cbData
Length, in bytes, of the string pointed to by the pvData parameter, not including the terminating null character.

Return Values

Returns ERROR_SUCCESS if successful, or a nonzero error code defined in Winerror.h otherwise. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to retrieve a generic description of the error.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHREGDEL_FLAGS

Provides a set of values that indicate from which base key an item will be deleted.

typedef enum
{
    SHREGDEL_DEFAULT = 0x00000000,
    SHREGDEL_HKCU    = 0x00000001,
    SHREGDEL_HKLM    = 0x00000010,
    SHREGDEL_BOTH    = 0x00000011,
}  SHREGDEL_FLAGS;

Members

SHREGDEL_DEFAULT
Deletes from HKEY_CURRENT_USER, or, if the specified item is not found under HKEY_CURRENT_USER, deletes from HKEY_LOCAL_MACHINE.
SHREGDEL_HKCU
Enumerates from HKEY_CURRENT_USER only.
SHREGDEL_HKLM
Enumerates under HKEY_LOCAL_MACHINE only.
SHREGDEL_BOTH
Deletes from both HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlwapi.h.


SHREGENUM_FLAGS

Provides a set of values that indicate the base key that will be used for an enumeration.

typedef enum{
    SHREGENUM_DEFAULT = 0x00000000,
    SHREGENUM_HKCU    = 0x00000001,
    SHREGENUM_HKLM    = 0x00000010,
    SHREGENUM_BOTH    = 0x00000011,
} SHREGENUM_FLAGS;

Members

SHREGENUM_DEFAULT
Enumerates under HKEY_CURRENT_USER, or, if the specified item is not found in HKEY_CURRENT_USER, enumerates under HKEY_LOCAL_MACHINE.
SHREGENUM_HKCU
Enumerates under HKEY_CURRENT_USER only.
SHREGENUM_HKLM
Enumerates under HKEY_LOCAL_MACHINE only.
SHREGENUM_BOTH
Not used.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlwapi.h.


REGSAM

Data type used for specifying the security access attributes in the registry. A REGSAM value can be one or more of the following values:

KEY_ALL_ACCESS
Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, KEY_NOTIFY, KEY_CREATE_SUB_KEY, KEY_CREATE_LINK, and KEY_SET_VALUE access.
KEY_CREATE_LINK
Permission to create a symbolic link.
KEY_CREATE_SUB_KEY
Permission to create subkeys.
KEY_ENUMERATE_SUB_KEYS
Permission to enumerate subkeys.
KEY_EXECUTE
Permission for read access.
KEY_NOTIFY
Permission for change notification.
KEY_QUERY_VALUE
Permission to query subkey data.
KEY_READ
Combination of KEY_QUERY_VALUE, KEY_ENUMERATE_SUB_KEYS, and KEY_NOTIFY access.
KEY_SET_VALUE
Permission to set subkey data.
KEY_WRITE
Combination of KEY_SET and KEY_CREATE_SUB_KEY access.


Registry Data Types

The following data types can be used to specify the type of a registry value:

REG_BINARY
Binary data in any form.

REG_DWORD
32-bit number.

REG_QWORD
64-bit number.

REG_DWORD_LITTLE_ENDIAN
32-bit number in little-endian format. This is equivalent to REG_DWORD.

In little-endian format, a multibyte value is stored in memory from the lowest byte (the "little end") to the highest byte. For example, the value 0x12345678 is stored as (0x78 0x56 0x34 0x12) in little-endian format.

Windows NT and Windows 95 are designed to run on little-endian computer architectures. A user may connect to computers that have big-endian architectures, such as some UNIX systems.

REG_QWORD_LITTLE_ENDIAN
A 64-bit number in little-endian format. This is equivalent to REG_QWORD.
REG_DWORD_BIG_ENDIAN
32-bit number in big-endian format.

In big-endian format, a multibyte value is stored in memory from the highest byte (the "big end") to the lowest byte. For example, the value 0x12345678 is stored as (0x12 0x34 0x56 0x78) in big-endian format.

REG_EXPAND_SZ
Null-terminated string that contains unexpanded references to environment variables (for example, "%PATH%"). It will be a UNICODE or ANSI string, depending on whether you use the UNICODE or ANSI functions.

REG_LINK
Unicode symbolic link.

REG_MULTI_SZ
Array of null-terminated strings that are terminated by two null characters.

REG_NONE
No defined value type.

REG_RESOURCE_LIST
Device-driver resource list.

REG_SZ
Null-terminated string. It will be a Unicode or ANSI string, depending on whether you use the Unicode or ANSI functions.


ColorAdjustLuma

Changes the luminance of a red-green-blue (RGB) value. Hue and saturation are not affected.

COLORREF ColorAdjustLuma(
    COLORREF clrRGB,
    int n,
    BOOL fScale
);

Parameters

clrRGB
Initial RGB value.
n
Luminance in units of 0.1 percent of the total range. For example, a value of n = 50 corresponds to 5 percent of the maximum luminance.
fScale
If fScale is set to TRUE, n specifies how much to increment or decrement the current luminance. If fScale is set to FALSE, n specifies the absolute luminance.

Return Values

Returns the modified RGB value.

Remarks

If fScale is set to TRUE, n can range from -1000 to +1000.

If fScale is set to FALSE, n can range from 0 to 1000. Available luminance values range from 0 to a maximum. If the requested value is negative or exceeds the maximum, the luminance will be set to either zero or the maximum value, respectively.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


ColorHLSToRGB

Converts colors from hue-luminance-saturation (HLS) to red-green-blue (RGB) format.

COLORREF ColorHLSToRGB(
    WORD wHue,
    WORD wLuminance,
    WORD wSaturation
);

Parameters

wHue
HLS hue value.
wLuminance
HLS luminance value.
wSaturation
HLS saturation value.

Return Values

Returns the RGB value.

Requirements

Version 5.00 and later of Shlwapi.dll
Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


ColorRGBToHLS

Converts colors from red-green-blue (RGB) to hue-luminance-saturation (HLS) format.

VOID ColorRGBToHLS(
    COLORREF clrRGB,
    WORD *pwHue,
    WORD *pwLuminance,
    WORD *pwSaturation
);

Parameters

clrRGB
[in] RGB color.
pwHue
[out] HLS hue value.
pwLuminance
[out] HLS luminance value.
pwSaturation
[out] HLS saturation value.

Return Values

No return value.

Requirements

Version 5.00 and later of Shlwapi.dll
Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHCreateShellPalette

Creates a halftone palette for the specified device context.

HPALETTE SHCreateShellPalette(
    HDC	hdc
);

Parameters

hdc
Device context.

Return Values

Returns the palette if successful, or zero otherwise.

Remarks

This function behaves the same as CreateHalftonePalette, but it is designed to accommodate the differences between Microsoft® Windows® 95, Windows NT® 4.0, and Windows 2000. The palette that is returned depends on the device context in the following way:

  • If hdc is set to NULL, a full palette is returned.
  • If the device context is palettized, a full palette is returned.
  • If the device context is not palettized, a default palette (VGA colors) is returned.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


DllInstall

Handles installation and setup for a DLL.

STDAPI DllInstall(
    BOOL bInstall,
    LPCWSTR pszCmdLine
);

Parameters

bInstall
Value that is set to TRUE if the DLL is being installed, or FALSE if it is being uninstalled.
pszCmdLine
String passed in by regsvr32 that indicates which setup procedure to use.

Return Values

Returns NOERROR if successful, or an OLE-defined error value otherwise.

Remarks

This function may be implemented and exported by name by a DLL for use during application installation or setup. It is invoked by regsvr32 to allow the DLL to perform tasks such adding information to the registry.

DllInstall is used only for application installation and setup. It should not be called by an application. It is similar in purpose to DllRegisterServer or DllUnregisterServer. Unlike these functions, DllInstall takes an input string which can be used to specify a variety of different actions. This allows a DLL to be installed in more than one way, based on any criteria that is appropriate.

To use DllInstall with regsvr32, add a "/i" flag followed by a colon (:) and a string. The string will be passed to the DllInstall as the pszCmdLine parameter. If you omit the colon and string, pszCmdLine will be set to NULL. The following example would be used to install a DLL:

regsvr32 /i:"Install_1" dllname.dll

DllInstall is invoked with bInstall set to TRUE and pszCmdLine set to "Install_1". To uninstall a DLL, use:

regsvr32 /u /i:"Install_1" dllname.dll

With both of the above examples, DllRegisterServer or DllUnregisterServer will also be called. To call DllInstall only, add a "/n" flag:

regsvr32 /n /i:"Install_1" dllname.dll

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98.
Header: Declared in Shlwapi.h.


HashData

Hashes an array of data.

HRESULT HashData(
    LPBYTE pbData,
    DWORD cbData,
    LPBYTE pbHash,
    DWORD cbHash
);

Parameters

pbData
[in] Pointer to the data array.
cbData
[in] Number of elements in pbData.
pbHash
[out] Value used to return the hashed array.
cbHash
[in] Number of elements in pbHash. It should be no larger than 256.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHAutoComplete

Instructs system edit controls to use AutoComplete to help complete URLs or file system paths.

HRESULT SHAutoComplete(
    HWND hwndEdit,
    DWORD dwFlags
);

Parameters

hwndEdit
[in] Window handle of a system edit control. Typically, this parameter is the handle of an edit control or the edit control embedded in a comboboxex control.
dwFlags
[in] Flags to control the operation of SHAutoComplete. The first four flags are used to override the Microsoft® Internet Explorer registry settings. The user can change these settings manually by launching the Internet Options property sheet from the Tools menu and clicking the Advanced tab.
SHACF_AUTOAPPEND_FORCE_OFF | Ignore the registry default and force the autoappend feature off. This flag must be used in combination with one or more of the SHACF_FILESYSXXX or SHACF_URLXXX flags.
SHACF_AUTOAPPEND_FORCE_ON | Ignore the registry value and force the autoappend feature on. The completed string will be displayed in the edit box with the added characters highlighted. This flag must be used in combination with one or more of the SHACF_FILESYSXXX or SHACF_URLXXX flags.
SHACF_AUTOSUGGEST_FORCE_OFF | Ignore the registry default and force the autosuggest feature off. This flag must be used in combination with one or more of the SHACF_FILESYSXXX or SHACF_URLXXX flags.
SHACF_AUTOSUGGEST_FORCE_ON | Ignore the registry value and force the autosuggest feature on. A selection of possible completed strings will be displayed as a dropdown list, below the edit box. This flag must be used in combination with one or more of the SHACF_FILESYSXXX or SHACF_URLXXX flags.
SHACF_DEFAULT | The default setting, equivalent to SHACF_FILESYSTEM | SHACF_URLALL. SHACF_DEFAULT cannot be combined with any other flags.
SHACF_FILESYSTEM | Include the file system.
SHACF_URLALL | Include the URLs in the users History and Recently Used lists. Equivalent to SHACF_URLHISTORY | SHACF_URLMRU.
SHACF_URLHISTORY | Include the URLs in the user's History list.
SHACF_URLMRU | Include the URLs in the user's Recently Used list.
SHACF_USETAB | Allow the user to select from the autosuggest list by pressing the TAB key. If this flag is not set, pressing the TAB key will shift focus to the next control and close the autosuggest list. If SHACF_USETAB is set, pressing the TAB key will select the first item in the list. Pressing TAB again will select the next item in the list, and so on. When the user reaches the end of the list, the next TAB key press will cycle the focus back to the edit control. This flag must be used in combination with one or more of the SHACF_FILESYSXXX or SHACF_URLXXX flags.

Return Values

Returns S_OK if successful, or a standard OLE error value otherwise.

Remarks

SHAutoComplete will work on any system edit control, including the edit control and controls that contain edit controls such as comboboxex controls. To retrieve a handle to the edit control that is embedded in a comboboxex control send it a CBEM_GETEDITCONTROL.

An application must have invoked either CoInitialize or OleInitialize prior to calling this function. CoUninitialize or OleUninitialize cannot be called until the edit box has finished processing the WM_DESTROY message for hwndEdit.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHCreateStreamOnFile

Takes a file name, opens the file, and returns an IStream interface that can be used to read from and write to the file.

HRESULT SHCreateStreamOnFile(
  LPCTSTR pszFile,
  DWORD grfMode,
  IStream **ppstm
);

Parameters

pszFile
[in] Pointer to a NULL-terminated string with the file name.
grfMode
[in] STGM value that is used to specify access modes and how the object that exposes the IStream interface is created and deleted.
ppstm
[out] Pointer to an IStream interface for the file.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Internet Explorer 5.0 or later.
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHCreateThread

Creates a thread.

BOOL SHCreateThread(
  LPTHREAD_START_ROUTINE pfnThreadProc,
  VOID *pData,
  DWORD dwFlags,
  LPTHREAD_START_ROUTINE pfnCallback
);

Parameters

pfnThreadProc
Pointer to an application-defined function of the LPTHREAD_START_ROUTINE type. If a new thread was successfully created, this function will be called in the context of that thread. SHCreateThread does not wait for this function to complete before returning to its caller. The return value of this function will be the exit code of the thread.
pData
Pointer to an application-defined data structure containing initialization data. It is passed to the function pointed to by pfnThreadProc and, optionally, pfnCallback.
dwFlags
Flags that control the behavior of the function. This parameter can be a combination of the following flags.
Flag | Description
CTF_COINIT | Initialize COM for the created thread before calling either the optional function pointed to by pfnCallback or the function pointed to by pfnThreadProc. This flag is useful when COM needs to be initialized for a thread. COM will automatically be uninitialized as well.
CTF_INSIST | If the attempt to create the thread with CreateThread fails, setting this flag will cause the function pointed to by pfnThreadProc to be called synchronously from the calling thread. This flag cannot be used if pfnCallback has a non-NULL value.
CTF_PROCESS_REF | Hold a reference to the Windows® Explorer process for the duration of the call to the function pointed to by pfnThreadProc. This flag is useful for shell extension handlers, which might need to keep the Windows Explorer process from closing prematurely. Examples of where this action would be useful include tasks such as doing work on a background thread or copying files. For further information, see SHGetInstanceExplorer.
CTF_THREAD_REF | Hold a reference to the creating thread for the duration of the call to the function pointed to by pfnThreadProc. This reference must have been set with SHSetThreadRef.
pfnCallback
Pointer to an optional application-defined function of the LPTHREAD_START_ROUTINE type. This function is called in the context of the created thread before the function pointed to by pfnThreadProc is called. It will also receive pData as its argument. SHCreateThread will wait for the function pointed to by pfnCallback to return before returning to its caller. The return value of the function pointed to by pfnCallback is ignored.

Return Values

Returns TRUE if the thread is successfully created, or FALSE otherwise.

Remarks

The function pointed to by pfnThreadProc and pfnCallback must take the form:

DWORD WINAPI ThreadProc(LPVOID pData)
{
...
}

The function name is arbitrary. The pData parameter points to an application-defined data structure with initialization information.

See Also

CreateThread, CreateProcess

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHGetThreadRef

Retrieves the per-thread object reference set by SHSetThreadRef.

HRESULT SHGetThreadRef(
    IUnknown **ppunk
);

Parameters

ppunk
Address of a pointer to an IUnknown interface. If successful, this parameter will hold the object's IUnknown pointer on return. Your application is responsible for freeing the pointer when it is finished.

Return Values

Returns S_OK if the object reference exists, or E_NOINTERFACE otherwise.

See Also

SHCreateThread

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHOpenRegStream

Opens a registry value and supplies an IStream interface that can be used to read from or write to the value.

struct IStream* SHOpenRegStream(
    HKEY hkey,
    LPCTSTR pszSubkey,
    LPCTSTR pszValue,
    DWORD grfMode
);

Parameters

hkey
Handle to the key that is currently open.
pszSubkey
Address of a null-terminated string that specifies the name of the subkey.
pszValue
Address of the value to be accessed.
grfMode
Type of access for the stream. This can be one of the following values:
STGM_READ | Open the stream for reading.
STGM_WRITE | Open the stream for writing.
STGM_READWRITE | Open the stream for reading and writing.

Return Values

Returns the address of an IStream interface if successful, or NULL otherwise.

Remarks

The calling application is responsible for calling this interface's Release method when the IStream object is no longer needed.

Requirements

Version 4.71 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHOpenRegStream2

Opens a registry value and returns an IStream interface that can be used to read from or write to the value. It supersedes SHOpenRegStream.

IStream* SHOpenRegStream2(
  HKEY hkey,
  LPCSTR pszSubkey,
  LPCSTR pszValue,
  DWORD grfMode
);

Parameters

hkey
[in] Handle to a key that is currently open, or a registry root key.
pszSubkey
[in] Pointer to a NULL-terminated string that contains the name of the subkey.
pszValue
[in] Pointer to a NULL-terminated string with the name of the value that holds the unexpanded path string.
grfMode
[in] Type of access for the stream. It can have one of the following values.
Value | Description
STGM_READ | Open the stream for reading.
STGM_WRITE | Open the stream for writing.
STGM_READWRITE | Open the stream for reading and writing.

Return Values

Returns the address of an IStream interface if successful, or NULL otherwise.

Remarks

The calling application is responsible for calling this interface's Release method when the IStream object is no longer needed.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


SHSetThreadRef

Stores a per-thread reference to a COM object.

HRESULT SHSetThreadRef(
    IUnknown *punk
);

Parameters

punk
Pointer to the IUnknown interface of the object to which you want to store a reference.

Return Values

Returns S_OK if successful, or an OLE error value otherwise.

Remarks

Use SHGetThreadRef to retrieve the IUnknown pointer.

See Also

SHCreateThread

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


ABM_ACTIVATE

Notifies the system that an appbar has been activated. An appbar should call this message in response to the WM_ACTIVATE message.

SHAppBarMessage(ABM_ACTIVATE, pabd);

Parameters

pabd
Address of an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Value

Always returns TRUE.

Remarks

This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar. The system automatically sets the z-order for autohide appbars.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_GETAUTOHIDEBAR

Retrieves the handle to the autohide appbar associated with an edge of the screen.

hwndAutoHide = (HWND) SHAppBarMessage(ABM_GETAUTOHIDEBAR, pabd);

Parameters

pabd
Address of an APPBARDATA structure that specifies the screen edge. You must specify the cbSize, hWnd, and uEdge members when sending this message; all other members are ignored.

Return Values

Returns the handle to the autohide appbar. The return value is NULL if an error occurs or if no autohide appbar is associated with the given edge.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_GETSTATE

Retrieves the autohide and always-on-top states of the Windows taskbar.

uState = (UINT) SHAppBarMessage(ABM_GETSTATE, pabd);

Parameters

pabd
Address of an APPBARDATA structure. You must specify the cbSize member when sending this message; all other members are ignored.

Return Values

Returns zero if the taskbar is neither in the autohide nor always-on-top state. Otherwise, the return value is one or both of the following:
ABS_ALWAYSONTOP | The taskbar is in the always-on-top state.
ABS_AUTOHIDE | The taskbar is in the autohide state.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_GETTASKBARPOS

Retrieves the bounding rectangle of the Windows taskbar.

fResult = (BOOL) SHAppBarMessage(ABM_GETTASKBARPOS, pabd);

Parameters

pabd
Address of an APPBARDATA structure whose rc member receives the bounding rectangle, in screen coordinates, of the taskbar. You must specify the cbSize and hWnd when sending this message; all other members are ignored.

Return Values

Returns TRUE if successful, or FALSE otherwise.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_NEW

Registers a new appbar and specifies the message identifier that the system should use to send it notification messages. An appbar should send this message before sending any other appbar messages.

fRegistered = (BOOL) SHAppBarMessage(ABM_NEW, pabd);

Parameters

pabd
Address of an APPBARDATA structure that contains the new appbar's window handle and message identifier. You must specify the cbSize, hWnd, and uCallbackMessage members when sending this message; all other members are ignored.

Return Values

Returns TRUE if successful, or FALSE if an error occurs or if the appbar is already registered.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_QUERYPOS

Requests a size and screen position for an appbar. When the request is made, the message proposes a screen edge and a bounding rectangle for the appbar. The system adjusts the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any other appbars.

SHAppBarMessage(ABM_QUERYPOS, pabd);

Parameters

pabd
Address of an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the proposed bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

Remarks

An appbar should send this message before sending the ABM_SETPOS message.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_REMOVE

Unregisters an appbar by removing it from the system's internal list. The system no longer sends notification messages to the appbar or prevents other applications from using the screen area occupied by the appbar.

SHAppBarMessage(ABM_REMOVE, pabd);

Parameters

pabd
Address of an APPBARDATA structure that contains the handle to the appbar to unregister. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

Remarks

This message causes the system to send the ABN_POSCHANGED notification message to all appbars.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_SETAUTOHIDEBAR

Registers or unregisters an autohide appbar for an edge of the screen.

fSuccess = (BOOL) SHAppBarMessage(ABM_SETAUTOHIDEBAR, pabd);

Parameters

pabd
Address of an APPBARDATA structure. The uEdge member specifies the screen edge. The lParam parameter is set to TRUE to register the appbar or FALSE to unregister it. You must specify the cbSize, hWnd, uEdge, and lParam members when sending this message; all other members are ignored.

Return Values

Returns TRUE if successful, or FALSE if an error occurs or if an autohide appbar is already registered for the given edge.

Remarks

The system allows only one autohide appbar for each edge of the screen. This is determined when the member uEdge of theAPPBARDATA structure is set.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_SETPOS

Sets the size and screen position of an appbar. The message specifies a screen edge and the bounding rectangle for the appbar. The system may adjust the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any other appbars.

SHAppBarMessage(ABM_SETPOS, pabd);

Parameters

pabd
Address of an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

Remarks

This message causes the system to send the ABN_POSCHANGED notification message to all appbars.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABM_SETSTATE

Sets the autohide and always-on-top states of the Microsoft® Windows® taskbar.

SHAppBarMessage(ABM_SETSTATE, pabd);

Parameters

pabd
Address of an APPBARDATA structure. You must specify the cbSize and hWnd members when sending this message. Data for the desired state is sent in the lParam member using one of the following values.
Autohide and always-on-top both off | 0
Always-on-top on, autohide off | ABS_ALWAYSONTOP
Autohide on, always-on-top off | ABS_AUTOHIDE
Autohide and always-on-top both on | ABS_AUTOHIDE | ABS_ALWAYSONTOP

Return Value

Always returns TRUE.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Header: Declared in Shellapi.h.


ABM_WINDOWPOSCHANGED

Notifies the system when an appbar's position has changed. An appbar should call this message in response to the WM_WINDOWPOSCHANGED message.

SHAppBarMessage(ABM_WINDOWPOSCHANGED, pabd);

Parameters

pabd
Address of an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members when sending this message; all other members are ignored.

Return Values

Always returns TRUE.

Remarks

This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABN_FULLSCREENAPP

Notifies an appbar when a full-screen application is opening or closing. This notification is sent in the form of an application-defined message that is set by the ABM_NEW message.

ABN_FULLSCREENAPP
    fOpen = (BOOL) lParam;

Parameters

fOpen
Flag specifying whether a full-screen application is opening or closing. This parameter is TRUE if the application is opening or FALSE if it is closing.

Return Values

No return value.

Remarks

When a full-screen application is opening, an appbar must drop to the bottom of the z-order. When it is closing, the appbar should restore its z-order position.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABN_POSCHANGED

Notifies an appbar when an event has occurred that may affect the appbar's size and position. Events include changes in the taskbar's size, position, and visibility state, as well as the addition, removal, or resizing of another appbar on the same side of the screen.

ABN_POSCHANGED

Return Values

No return value.

Remarks

An appbar should respond to this notification message by sending the ABM_QUERYPOS and ABM_SETPOS messages. If its position has changed, the appbar should call the MoveWindow function to move itself to the new position.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABN_STATECHANGE

Notifies an appbar that the taskbar's autohide or always-on-top state has changed—that is, the user has selected or cleared the "Always on top" or "Auto hide" check box on the taskbar's property sheet.

ABN_STATECHANGE

Return Value

No return value.

Remarks

An appbar can use this notification message to set its state to conform to that of the taskbar, if desired.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


ABN_WINDOWARRANGE

Notifies an appbar that the user has selected the Cascade, Tile Horizontally, or Tile Vertically command from the taskbar's shortcut menu.

ABN_WINDOWARRANGE
    fBeginning = (BOOL) lParam;

Parameters

fBeginning
Flag specifying whether the cascade or tile operation is beginning. This parameter is TRUE if the operation is beginning and the windows have not yet been moved. It is FALSE if the operation has completed.

Return Value

No return value.

Remarks

The system sends this notification message twice—first with lParam set to TRUE and then with lParam set to FALSE. The first notification is sent before the windows are cascaded or tiled, and the second is sent after the cascade or tile operation has occurred.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


CPL_DBLCLK

Sent to the CPlApplet function of a Control Panel application when the user double-clicks the icon of a dialog box supported by the application.

CPL_DBLCLK
    uAppNum = (UINT) lParam1;
    lData = (LONG) lParam2;

Parameters

uAppNum
Dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT – 1).
lData
Value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads the lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Values

If the CPlApplet function processes this message successfully, the return value is zero; otherwise, it is nonzero.

Remarks

In response to this message, a Control Panel application must display the corresponding dialog box.

See Also

CPL_SELECT

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_EXIT

Sent once to the CPlApplet function of a Control Panel application before the DLL containing the Control Panel application is released.

CPL_EXIT

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

This message is sent after the last CPL_STOP message is sent.

In response to this message, a Control Panel application must free any memory that it has allocated and perform global-level cleanup.

See Also

FreeLibrary

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_GETCOUNT

Sent to the CPlApplet function of a Control Panel application to retrieve the number of dialog boxes supported by the application.

CPL_GETCOUNT

Return Values

The CPlApplet function returns the number of dialog boxes that the Control Panel application supports.

Remarks

This message is sent immediately after the CPL_INIT message.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_INIT

Sent to the CPlApplet function of a Control Panel application to prompt it to perform global initialization, especially memory allocation.

CPL_INIT

Return Values

If initialization succeeds, the CPlApplet function should return nonzero. Otherwise, it should return zero.

If CPlApplet returns zero, the controlling application ends communication and releases the DLL containing the Control Panel application.

Remarks

Because this is the only way a Control Panel application can signal an error condition, the application should allocate memory in response to this message.

This message is sent immediately after the DLL containing the application is loaded.

See Also

FreeLibrary

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_INQUIRE

Sent to the CPlApplet function of a Control Panel application to request information about a dialog box that the application supports.

CPL_INQUIRE
    uAppNum = (UINT) lParam1;
    lpcpli = (LPCPLINFO) lParam2;

Parameters

uAppNum
Dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT – 1).
lpcpli
Address of a CPLINFO structure. The application must fill this structure with resource identifiers for the icon, short name, description, and any user-defined value associated with the dialog box.

Return Value

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

The Control Panel sends the CPL_INQUIRE message once for each dialog box supported by your application. The Control Panel also sends a CPL_NEWINQUIRE message for each dialog box. These messages are sent immediately after the CPL_GETCOUNT message. However, the system does not guarantee the order in which the CPL_INQUIRE and CPL_NEWINQUIRE messages are sent.

You can perform initialization for the dialog box when you receive CPL_INQUIRE. If you must allocate memory, do so in response to the CPL_INIT message.

On Windows 95 and Windows NT version 4.0, the system caches the information returned in the CPLINFO structure used by CPL_INQUIRE. This provides significantly better performance because the system only needs to load your application the first time the Control Panel starts up. On the other hand, the CPL_NEWINQUIRE message returns information in a form that the system cannot cache. For this reason, most CPlApplet functions should process CPL_INQUIRE and ignore CPL_NEWINQUIRE.

The only applications that should use CPL_NEWINQUIRE are those that need to change their icon or display strings based on the state of the computer. In this case, your CPL_INQUIRE handler should specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members of the CPLINFO structure, rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings, allowing you to specify information based on the current state of the computer. Of course, this is significantly slower than using cached information.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_NEWINQUIRE

Sent to the CPlApplet function of a Control Panel application to request information about a dialog box that the application supports.

CPL_NEWINQUIRE
    uAppNum = (UINT) lParam1;
    lpncpli = (LPNEWCPLINFO) lParam2;

Parameters

uAppNum
Dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT – 1).
lpncpli
Address of a NEWCPLINFO structure. The Control Panel application should fill this structure with information about the dialog box.

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

For better performance, most applications should ignore CPL_NEWINQUIRE and process the CPL_INQUIRE message instead.

The Control Panel sends the CPL_NEWINQUIRE message once for each dialog box supported by your application. The Control Panel also sends a CPL_INQUIRE message for each dialog box. These messages are sent immediately after the CPL_GETCOUNT message. However, the system does not guarantee the order in which the CPL_INQUIRE and CPL_NEWINQUIRE messages are sent.

You can perform initialization for the dialog box when you receive CPL_INQUIRE. If you must allocate memory, do so in response to the CPL_INIT message.

The CPL_NEWINQUIRE message was introduced in Windows version 3.1 as a replacement for CPL_INQUIRE. However, CPL_INQUIRE is the preferred message for Windows 95 and Windows NT version 4.0. This is because CPL_NEWINQUIRE returns information in a form that the system cannot cache. Consequently, applications that process CPL_NEWINQUIRE must be loaded each time the Control Panel needs the information, resulting in a significant reduction in performance.

The only applications that should use CPL_NEWINQUIRE are those that need to change their icon or display strings based on the state of the computer. In this case, your CPL_INQUIRE handler should specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members of the CPLINFO structure, rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings, allowing you to specify information based on the current state of the computer. Of course, this is significantly slower than using cached information.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_SELECT

Obsolete. This message was used by versions of Windows earlier than Windows 95 and Windows NT version 4.0.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


CPL_STARTWPARMS

Sent to notify CPlApplet that the user has chosen the icon associated with a given dialog box. CPlApplet should display the corresponding dialog box and carry out any user-specified tasks.

CPL_STARTWPARMS
    uAppNum = (UINT) lParam1;
    lpszExtra = (LPCTSTR) lParam2;

Parameters

uAppNum
Dialog box number. This number must be in the range zero through one less than the value returned in response to the CPL_GETCOUNT message (CPL_GETCOUNT – 1).
lpszExtra
String with additional directions for execution.

Return Values

Returns TRUE if the message was handled, or FALSE otherwise.

Remarks

CPL_STARTWPARMS is similar to CPL_DBLCLK but allows you to pass a string to CPIApplet instead of an integer. You can use this string as a flexible way to provide detailed directions for execution.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in cpl.h.


CPL_STOP

Sent to the CPlApplet function of a Control Panel application when the controlling application of the Control Panel closes. The controlling application sends the message once for each dialog box that the application supports.

CPL_STOP
    uAppNum = (UINT) lParam1;
    lData = (LONG) lParam2;

Parameters

uAppNum
Dialog box number.
lData
Value that the Control Panel application loaded into the lData member of the CPLINFO or NEWCPLINFO structure for the dialog box. The application loads the lData member in response to the CPL_INQUIRE or CPL_NEWINQUIRE message.

Return Values

If the CPlApplet function processes this message successfully, it should return zero.

Remarks

In response to this message, a Control Panel application must perform cleanup for the given dialog box.

See Also

CPL_EXIT, CPL_GETCOUNT

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


FM_GETDRIVEINFO

Sent by a File Manager extension to retrieve drive information from the active File Manager window.

FM_GETDRIVEINFO
    wParam = 0;
    lParam = (LPARAM) (LPFMS_GETDRIVEINFO) lpfmsgdi;

Parameters

lpfmsgdi
Address of an FMS_GETDRIVEINFO structure that receives drive information.

Return Values

Returns nonzero.

Remarks

If 0xFFFFFFFF is returned in the dwTotalSpace or dwFreeSpace member of the FMS_GETDRIVEINFO structure, the extension library must compute the value or values.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_GETFILESEL

Sent by a File Manager extension to retrieve information about a selected file from the active File Manager window (either the directory window or the Search Results window).

FM_GETFILESEL
    wParam = (WPARAM) index;
    lParam = (LPARAM) (LPFMS_GETFILESEL) lpfmsgfs;

Parameters

index
Zero-based index of the selected file to retrieve.
lpfmsgfs
Address of an FMS_GETFILESEL structure that receives information about the selection.

Return Value

Returns the zero-based index of the selected file that was retrieved.

Remarks

An extension can use the FM_GETSELCOUNT message to retrieve the count of selected files.

See Also

FMExtensionProc, FM_GETFILESELLFN, FM_GETSELCOUNTLFN

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_GETFILESELLFN

Sent by a File Manager extension to retrieve information about a selected file from the active File Manager window (either the directory window or the Search Results window). The selected file can have a long file name.

FM_GETFILESELLFN
    wParam = (WPARAM) index;
    lParam = (LPARAM) (LPFMS_GETFILESEL) lpfmsgfs;

Parameters

index
Zero-based index of the selected file to retrieve.
lpfmsgfs
Address of an FMS_GETFILESEL structure that receives information about the selection.

Return Values

Returns the zero-based index of the selected file that was retrieved.

Remarks

Only extensions that support long file names (for example, network-aware extensions) should use this message.

An extension can use the FM_GETSELCOUNTLFN message to retrieve the count of selected files.

See Also

FMExtensionProc, FM_GETFILESEL, FM_GETSELCOUNT

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_GETFOCUS

Sent by a File Manager extension to retrieve the type of File Manager window that has the input focus.

FM_GETFOCUS
    wParam = 0;
    lParam = 0;

Return Values

Returns the type of File Manager window that has the input focus. It can be one of the following values:
FMFOCUS_DIR | Directory portion of a directory window.
FMFOCUS_TREE | Tree portion of a directory window.
FMFOCUS_DRIVES | Drive bar of a directory window.
FMFOCUS_SEARCH | Search Results window.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_GETSELCOUNT

Sent by a File Manager extension to retrieve a count of the selected files in the active File Manager window (either the directory window or the Search Results window).

FM_GETSELCOUNT
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of selected files.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNTLFN

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_GETSELCOUNTLFN

Sent by a File Manager extension to retrieve the number of selected files in the active File Manager window (either the directory window or the Search Results window). The count includes files that have long file names.

FM_GETSELCOUNTLFN
    wParam = 0;
    lParam = 0;

Return Values

Returns the number of selected files.

Remarks

Only extensions that support long file names (for example, network-aware extensions) should use this message.

See Also

FM_GETFILESEL, FM_GETFILESELLFN, FM_GETSELCOUNT

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_REFRESH_WINDOWS

Sent by a File Manager extension to cause File Manager to repaint either its active window or all of its windows.

FM_REFRESH_WINDOWS
    wParam = (WPARAM) (BOOL) fRepaint;
    lParam = 0;

Parameters

fRepaint
Value that indicates whether File Manager repaints its active window or all of its windows. If this parameter is TRUE, File Manager repaints all of its windows. Otherwise, File Manager repaints only its active window.

Return Values

No return value.

Remarks

File system changes caused by an extension are automatically detected by File Manager. An extension should use this message only in situations where drive connections are made or canceled.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FM_RELOAD_EXTENSIONS

Sent by a File Manager extension (or another application) to cause File Manager to reload all extension DLLs listed in the [AddOns] section of the Winfile.ini file.

FM_RELOAD_EXTENSIONS
    wParam = 0;
    lParam = 0;

Return Values

No return value.

Remarks

Other applications can use the PostMessage function to send this message to File Manager. To obtain the appropriate File Manager window handle, an application can specify "WFS_Frame" as the lpszClassName parameter in a call to the FindWindow function.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMEVENT_HELPMENUITEM

Sent to a File Manager extension DLL procedure when the user presses F1 on a menu or toolbar command item. The extension should call WinHelp, with that function's hwnd parameter set to the value of the extension's hwnd parameter.

FMEVENT_HELPMENUITEM
    uItem = (UINT) lParam;

Parameters

uItem
Value that identifies the menu or toolbar command item for which Help is sought. The extension procedure uses this value to determine how best to call WinHelp.

Return Values

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, FMEVENT_HELPSTRING

Requirements

Windows NT/2000: Requires Windows NT 3.5 or later.
Header: Declared in wfext.h.


FMEVENT_HELPSTRING

Sent to a File Manager extension DLL procedure when File Manager wants a Help string for a menu or toolbar command item.

FMEVENT_HELPSTRING
    lpfmshs = (LPFMS_HELPSTRING) lParam;

Parameters

lpfmshs
Address of an FMS_HELPSTRING structure that communicates command item Help string data.
The FMS_HELPSTRING structure identifies the command item for which a Help string is wanted, along with a handle to its menu. An application then writes the appropriate Help string to the FMS_HELPSTRING structure's szHelp member.

Return Values

An extension DLL procedure should return zero if it processes this message.

See Also

FMExtensionProc, FMEVENT_HELPMENUITEM

Requirements

Windows NT/2000: Requires Windows NT 3.5 or later.
Header: Declared in wfext.h.


FMEVENT_INITMENU

Sent to an extension DLL when the user selects the menu for the extension from the File Manager menu bar. The extension can use this notification to initialize menu items.

FMEVENT_INITMENU
    hmenu = (HMENU) lParam;

Parameters

hmenu
Handle to the File Manager menu bar.

Return Value

An extension DLL should return zero if it processes this message.

Remarks

An extension DLL receives this message only when the user selects the top-level menu. If the extension contains submenus, it must initialize them at the same time it initializes the top-level menu.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMEVENT_LOAD

Sent to an extension DLL when File Manager is loading the DLL.

FMEVENT_LOAD
    lpfmsld = (LPFMS_LOAD) lParam;

Parameters

lpfmsld
Address of an FMS_LOAD structure that specifies the menu item delta value.

Return Values

An extension DLL must return TRUE to continue loading the DLL. If the DLL returns FALSE, File Manager calls the FreeLibrary function and ends any communication with the extension DLL.

Remarks

An application should fill the dwSize, szMenuName, and hMenu members in the FMS_LOAD structure. It should also save the value of the wMenuDelta member and use it to identify menu items when modifying the menu.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMEVENT_SELCHANGE

Sent to an extension DLL when the user selects a file name in the File Manager directory window or Search Results window.

FMEVENT_SELCHANGE

Return Values

An extension DLL should return zero if it processes this message.

Remarks

Changes in the tree portion of the directory window do not produce this message.

Because the user can change the selection many times, the extension DLL must return promptly after processing this message to avoid slowing the selection process for the user.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMEVENT_TOOLBARLOAD

Sent to an extension DLL when File Manager is loading its toolbar. This message allows an extension DLL to add a button to the File Manager toolbar.

FMEVENT_TOOLBARLOAD
    lpfmstbl = (LPFMS_TOOLBARLOAD) lParam;

Parameters

lpfmstbl
Address of an FMS_TOOLBARLOAD structure. If the extension DLL adds a button to the toolbar in File Manager, the DLL should fill the structure with information about the button.

Return Values

An extension DLL must return TRUE to add the button to the toolbar. If the DLL returns FALSE, File Manager does not add the button.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMEVENT_UNLOAD

Sent to an extension DLL when File Manager is unloading the DLL.

FMEVENT_UNLOAD

Return Values

An extension DLL should return zero if it processes this message.

Remarks

The hwnd and hMenu values passed with the FMEVENT_LOAD and FMEVENT_INITMENU messages may not be valid at the time this message is sent.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMEVENT_USER_REFRESH

Sent to an extension DLL when the user chooses the Refresh command from the View menu in File Manager. The extension can use this notification to update its menu.

FMEVENT_USER_REFRESH

Return Values

An extension DLL should return zero if it processes this message.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


WM_CPL_LAUNCH

Not supported.


WM_CPL_LAUNCHED

Not supported.


WM_DROPFILES

Sent when the user drops a file on the window of an application that has registered itself as a recipient of dropped files.

WM_DROPFILES
    hDrop = (HDROP) wParam;

Parameters

hDrop
Handle to an internal structure describing the dropped files. Pass this handle DragFinish, DragQueryFile, or DragQueryPoint to retrieve information about the dropped files.

Return Values

An application should return zero if it processes this message.

Remarks

The HDROP handle is declared in Shellapi.h. You must include this header in your build to use WM_DROPFILES. For further discussion of how to use drag-and-drop to transfer Shell data, see Transferring Shell Data Using Drag-and-Drop or the Clipboard.

See Also

DragAcceptFiles

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.


WM_HELP

Indicates that the user pressed the F1 key. If a menu is active when F1 is pressed, WM_HELP is sent to the window associated with the menu; otherwise, WM_HELP is sent to the window that has the keyboard focus. If no window has the keyboard focus, WM_HELP is sent to the currently active window.

WM_HELP
    lphi = (LPHELPINFO) lParam;

Parameters

lphi
Address of a HELPINFO structure that contains information about the menu item, control, dialog box, or window for which Help is requested.

Return Values

Returns TRUE.

Remarks

The DefWindowProc function passes WM_HELP to the parent window of a child window or to the owner of a top-level window.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.


WM_TCARD

Sent to an application that has initiated a training card with Windows Help. The message informs the application when the user clicks an authorable button. An application initiates a training card by specifying the HELP_TCARD command in a call to the WinHelp function.

WM_TCARD
    idAction = wParam;
    dwActionData = lParam;

Parameters

idAction
Value that indicates the action the user has taken. This can be one of these values:
IDABORT | The user clicked an authorable Abort button.
IDCANCEL | The user clicked an authorable Cancel button.
IDCLOSE | The user closed the training card.
IDHELP | The user clicked an authorable Windows Help button.
IDIGNORE | The user clicked an authorable Ignore button.
IDOK | The user clicked an authorable OK button.
IDNO | The user clicked an authorable No button.
IDRETRY | The user clicked an authorable Retry button.
HELP_TCARD_DATA | The user clicked an authorable button. The lParam parameter contains a long integer specified by the Help author.
HELP_TCARD_NEXT | The user clicked an authorable Next button.
HELP_TCARD_OTHER_CALLER | Another application has requested training cards.
IDYES | The user clicked an authorable Yes button.
dwActionData
If idAction specifies HELP_TCARD_DATA, this parameter is a long integer specified by the Help author. Otherwise, this parameter is zero.

Return Values

The return value is ignored; use zero.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.


DIDiskQuotaUser

DIDiskQuotaUser Object

The DiskQuotaControl object allows a client to manage an NTFS volume's global disk quota settings. Each user on the volume that is managed by the DiskQuotaControl object has a DIDiskQuotaUser object associated with it. This object allows a client to manage an individual user's settings.

There are several ways to obtain a user's DIDiskQuotaUser object:

  • The DIDiskQuotaUser objects for all users with quotas on the volume are exposed as a collection and can be enumerated. For a discussion of how to enumerate DIDiskQuotaUser objects, see Enumerating Disk Quota Users.
  • When you add a new user, the DiskQuotaControl.AddUser method returns the user's DIDiskQuotaUser object.
  • If you have the user's name, the DiskQuotaControl.FindUser method returns the user's DIDiskQuotaUser object.

The DIDiskQuotaUser object supports the following properties and methods.

Properties

AccountContainerName | Contains the name of the user's account container. Read-only.
AccountStatus | Contains the status of the user's account. Read-only.
DisplayName | Contains the user's display name. Read-only.
ID | Contains an ID that uniquely identifies the user. Read-only.
LogonName | Contains the user's logon account name. Read-only.
QuotaLimit | Contains the user's current quota limit, in bytes. Read/write.
QuotaLimitText | Contains the user's current quota limit as a text string. Read-only.
QuotaThreshold | Contains the user's warning threshold, in bytes. Read/write.
QuotaThresholdText | Contains the user's warning threshold as a text string. Read-only.
QuotaUsed | Contains the user's current disk usage, in bytes. Read-only.
QuotaUsedText | Contains the user's current disk usage as a text string. Read-only.

Methods

Invalidate Clears the object's cached user information.

Remarks

This object makes the essential functionality of the IDiskQuotaUser interface available to scripting and Microsoft® Visual Basic®-based applications.

See Also

Shell Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.AccountContainerName

AccountContainerName Property

Contains the name of the user's account container. Read-only.

sContainerName = object.AccountContainerName

Possible Values

This property is a string value that is set to the user's account container name.

Remarks

For Microsoft® Windows NT® 4.0 accounts or other accounts without directory services information, this property contains the domain name. For accounts with directory services information, this property contains a canonical name with the terminating object name removed.

See Also

DIDiskQuotaUser Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.AccountStatus

AccountStatus Property

Contains the status of the user's account. Read-only.

iStatus = object.AccountStatus

Possible Values

This property can take one of the following values.

Status | Value | Description
dqAcctResolved | 0 | Account information is resolved.
dqAcctUnavailable | 1 | Account information is unavailable.
dqAcctDeleted | 2 | Account has been deleted.
dqAcctInvalid | 3 | Account is invalid.
dqAcctUnknown | 4 | Account cannot be found.
dqAcctUnresolved | 5 | Account information is unresolved.

See Also

DIDiskQuotaUser Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.DisplayName

DisplayName Property

Contains the user's display name. Read-only.

sDisplayName = object.DisplayName

Possible Values

This property is a string value that is set to the user's display name.

Remarks

This property contains the user's "friendly name." Its value is not necessarily defined.

See Also

DIDiskQuotaUser Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.ID

ID Property

Contains an ID that uniquely identifies the user. Read-only.

iID = object.ID

Possible Values

This property is a long value that uniquely identifies the user's DiDiskQuotaUser object within a particular DiskQuotaControl process.

Remarks

This property is intended for use by languages such as Microsoft® Visual Basic® that do not support pointers.

See Also

DIDiskQuotaUser Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.LogonName

LogonName Property

Contains the user's logon account name. Read-only.

sLogon = object.LogonName

Possible Values

This property is a string value that is set to the user's account logon name.

See Also

DIDiskQuotaUser Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.QuotaLimit

QuotaLimit Property

Contains the user's current quota limit, in bytes. Read/write.

object.QuotaLimit [= dQuotaLimit]

Possible Values

This property is a double value that is set to the user's current quota limit, in bytes.

See Also

DefaultQuotaLimit, DIDiskQuotaUser Object, QuotaLimitText

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.QuotaLimitText

QuotaLimitText Property

Contains the user's current quota limit as a text string. Read-only.

sQuotaLimit = object.QuotaLimitText

Possible Values

This property is a string value that contains the user's current quota limit.

See Also

DefaultQuotaLimitText, DIDiskQuotaUser Object, QuotaLimit

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.QuotaThreshold

QuotaThreshold Property

Contains the user's warning threshold, in bytes. Read/write.

object.QuotaThreshold [= dQuotaThreshold]

Possible Values

This property is a double value that is set to the user's warning threshold. If a user's disk usage exceeds this value and the DiskQuotaControl.LogQuotaThreshold property is set to TRUE, the system generates an event log entry.

See Also

DefaultQuotaThreshold, DIDiskQuotaUser Object, QuotaLimit, QuotaThresholdText

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.QuotaThresholdText

QuotaThresholdText Property

Contains the user's warning threshold as a text string. Read-only.

sQuotaThreshold = object.QuotaThresholdText

Possible Values

This property is a string value that contains the user's warning threshold. If a user's disk usage exceeds this value and the DiskQuotaControl.LogQuotaThreshold property is set to TRUE, the system generates an event log entry.

See Also

DIDiskQuotaUser Object, QuotaLimit, QuotaLimitText, QuotaThreshold

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.QuotaUsed

QuotaUsed Property

Contains the user's current disk usage, in bytes. Read-only.

dQuotaUsed = object.QuotaUsed

Possible Values

This property is a double value that is set to the amount of disk space currently in use. If NTFS file compression is enabled, QuotaUsed reflects the amount of disk space that the data would require in an uncompressed state.

See Also

DIDiskQuotaUser Object, QuotaLimit, QuotaThreshold, QuotaUsedText

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.QuotaUsedText

QuotaUsedText Property

Contains the user's current disk usage as a text string. Read-only.

sQuotaUsed = object.QuotaUsedText

Possible Values

This property is a string value that is set to the amount of disk space currently in use. If NTFS file compression is enabled, this property reflects the amount of disk space that the data would require in an uncompressed state.

See Also

DIDiskQuotaUser Object, QuotaLimitText, QuotaThresholdText, QuotaUsed

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUser.Invalidate

Invalidate Method

Clears the object's cached user information.

object.Invalidate()

Parameters

None.

Remarks

This method clears the user information stored in the object's cache. The next time a request is made for quota-related information, the object retrieves the information from the NTFS volume and refreshes the cache.

See Also

DIDiskQuotaUser Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DIDiskQuotaUsers Collection

Enumerating Disk Quota Users

The DIDiskQuotaUser objects for all users with a quota on the volume are exposed as a collection. The DiskQuotaControl object exports a standard enumerator method that allows you to enumerate the collection of DIDiskQuotaUser objects. The following procedure illustrates how to perform the enumeration with Microsoft® JScript® (compatible with ECMA 262 language specification). You can use a similar procedure with Microsoft® Visual Basic® or Visual Basic for Scripting (VBScript).

  1. Create a new DiskQuotaControl object.
  2. Initialize it with DiskQuotaControl.Initialize.
  3. Create a new JScript Enumerator object.
  4. Use a for loop to enumerate the DIDiskQuotaUser objects. There is no need to set a starting value. The enumerator object's moveNext method notifies the item method to return the next DIDiskQuotaUser object. The atEnd method returns FALSE when you reach the end of the list.
  5. As needed, use the DIDiskQuotaUser object returned by the enumerator's item method to retrieve or set one or more of the associated user's disk quota properties.

Example

The following code fragment illustrates how to enumerate DIDiskQuotaUser objects with JScript. The Volume_Label argument that is passed to the EnumUsers function is a string value containing a volume label such as "C:\\".

function EnumUsers(Volume_Label)
{
    var Volume;
    var QuotaUsers;
    var QuotaUser;

    Volume = new ActiveXObject("Microsoft.DiskQuota.1");
    Volume.Initialize(Volume_Label, 1);

    QuotaUsers = new Enumerator(Volume);
    for (;!Users.atEnd(); Users.moveNext())
    {
       QuotaUser = QuotaUsers.item();
     //Use the QuotaUser object to retrieve or set one or more
     //of the user's disk quota properties
     ...
    }
}

See Also

DIDiskQuotaUser Object, IDiskQuotaControl


DiskQuotaControl

DiskQuotaControl Object

The NTFS file system allows an administrator to manage disk usage on a shared volume by allocating a specified amount of disk space, or quota limit, to each user. The DiskQuotaControl object allows an administrator to manage a volume's disk quota properties. For instance, you can use this object to set the default quota limit that will be automatically assigned to all new users.

An administrator can use the DiskQuotaControl object to do a number of tasks, including:

  • Enabling and disabling the volume's disk quota system.
  • Obtaining the status of the quota system on the volume.
  • Denying disk space to users exceeding their quota limit.
  • Specifying the default warning threshold and quota limit values that will be assigned to new users.
  • Adding and removing users.

The DiskQuotaControl object allows you to set global default values for the volume for properties such as quota limits. However, each user is represented by a DIDiskQuotaUser object that can be used to specify individual quota settings.

There are several ways to obtain a user's DIDiskQuotaUser object:

  • The DIDiskQuotaUser objects for all users with quotas on the volume are exposed as a collection, and can be enumerated. For a discussion of how to enumerate DIDiskQuotaUser objects, see Enumerating Disk Quota Users.
  • When you add a new user, the AddUser method returns the user's DIDiskQuotaUser object.
  • If you have the user's name, the FindUser method returns the user's DIDiskQuotaUser object.

The DiskQuotaControl object supports the following properties, methods, and events.

Properties

DefaultQuotaLimit | Contains the default quota limit, in bytes. Read/write.
DefaultQuotaLimitText | Contains the default quota limit as a text string. Read-only.
DefaultQuotaThreshold | Contains the default quota threshold, in bytes. Read/write.
DefaultQuotaThresholdText | Contains the default quota threshold as a text string. Read-only.
LogQuotaLimit | Contains a Boolean value that indicates whether a system event log entry will be made when a user exceeds his or her assigned quota limit. Read/write.
LogQuotaThreshold | Contains a Boolean value that indicates whether a system event log entry will be made when a user exceeds his or her assigned quota threshold. Read/write.
QuotaFileIncomplete | Contains a Boolean value that indicates whether the quota file for the volume is complete. Read-only.
QuotaFileRebuilding | Contains a Boolean value that indicates whether the quota file for the volume is currently being rebuilt. Read-only.
QuotaState | Contains the state of the volume's disk quotas. Read/write.
UserNameResolution | Contains a value that controls how user security IDs are resolved to user names. Read/write.

Methods

AddUser | Assigns a nondefault disk quota to a new user.
DeleteUser | Deletes a user quota entry.
FindUser | Finds a user's entry, by name, in the volume's quota file.
GiveUserNameResolutionPriority | Places the specified user object next in line for name resolution.
Initialize | Opens a specified volume and initializes its quota control object.
InvalidateSidNameCache | Invalidates the security ID user name cache.
ShutdownNameResolution | Shuts down the user name resolution thread.
TranslateLogonNameToSID | Translates a logon name to the corresponding user SID in string format.

Events

OnUserNameChanged Occurs when the name information for a DiskQuotaUser object has been resolved.

Remarks

This object makes the essential functionality of the IDiskQuotaControl interface available to scripting and Microsoft® Visual Basic®-based applications.

See Also

IDiskQuotaControl Object, Shell Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.DefaultQuotaLimit

DefaultQuotaLimit Property

Contains the default quota limit, in bytes. Read/write.

object.DefaultQuotaLimit [= dDefaultQuotaLimit]

Possible Values

This property is a double value that is set to the default quota limit for new users, in bytes.

See Also

DefaultQuotaLimitText, DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.DefaultQuotaLimitText

DefaultQuotaLimitText Property

Contains the default quota limit as a text string. Read-only.

sDefaultQuotaLimitText = object.DefaultQuotaLimitText

Possible Values

This property is a string value that contains the default quota limit for new users of the volume. For example, if the default quota is 10.5 MB, the value of the property is "10.5 MB". If the volume has no default quota, the property is set to "No Limit" or the localized equivalent.

See Also

DefaultQuotaLimit, DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.DefaultQuotaThreshold

DefaultQuotaThreshold Property

Contains the default quota threshold, in bytes. Read/write.

object.DefaultQuotaThreshold [= dDefaultQuotaThreshold]

Possible Values

This property is a double value that is set to the default warning threshold for new users, in bytes.

Remarks

The default quota threshold is applied automatically to new users of the volume. If a user's disk usage exceeds this value and the LogQuotaThreshold property is set to TRUE, the system generates an event log entry. For example, if the default threshold is 10.0 MB, the value of the property is "10.0 MB". If the volume has no default threshold, the property is set to "No Limit" or the localized equivalent.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.DefaultQuotaThresholdText

DefaultQuotaThresholdText Property

Contains the default quota threshold as a text string. Read-only.

sDefaultQuotaThresholdText = object.DefaultQuotaThresholdText

Possible Values

This property is a string value that contains the default quota threshold for the volume.

Remarks

The default quota threshold is applied automatically to new users of the volume. If a user's disk usage exceeds this value and the LogQuotaThreshold property is set to TRUE, the system generates an event log entry. For example, if the default threshold is 10.0 MB, the value of the property is "10.0 MB". If the volume has no default threshold, the property is set to "No Limit" or the localized equivalent.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.LogQuotaLimit

LogQuotaLimit Property

Contains a Boolean value that indicates whether a system event log entry will be made when a user exceeds his or her assigned quota limit. Read/write.

object.LogQuotaLimit [= bLogQuotaLimit]

Possible Values

This property is set to TRUE if a system event log entry is made when the user exceeds his or her quota limit, or FALSE otherwise.

See Also

DefaultQuotaLimit, DiskQuotaControl Object, LogQuotaThreshold

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.LogQuotaThreshold

LogQuotaThreshold Property

Contains a Boolean value that indicates whether a system event log entry will be made when a user exceeds his or her assigned quota threshold. Read/write.

object.LogQuotaThreshold [= bLogQuotaThreshold]

Possible Values

This property is set to TRUE if a system event log entry is made when the user exceeds his or her quota warning threshold, or FALSE otherwise.

See Also

DefaultQuotaThreshold, DiskQuotaControl Object, LogQuotaLimit

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.QuotaFileIncomplete

QuotaFileIncomplete Property

Contains a Boolean value that indicates whether the quota file for the volume is complete. Read-only.

bQuotaFileIncomplete = object.QuotaFileIncomplete

Possible Values

This property is set to TRUE if the quota file is incomplete, or FALSE otherwise.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.QuotaFileRebuilding

QuotaFileRebuilding Property

Contains a Boolean value that indicates whether the quota file for the volume is currently being rebuilt. Read-only.

bQuotaFileRebuilding = object.QuotaFileRebuilding

Possible Values

This property is set to TRUE if the quota file is being rebuilt, or FALSE otherwise.

Remarks

The quota file is automatically rebuilt when quotas are enabled on the system or when one or more user entries are marked for deletion.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.QuotaState

QuotaState Property

Contains the state of the volume's disk quotas. Read/write.

object.QuotaState [= iQuotaState]

Possible Values

This property can be set to one of the following values.

State | Value | Description
dqStateDisable | 0 | Disk quotas are disabled.
dqStateTrack | 1 | Track quota usage. Quotas are enabled but the limit is not enforced.
dqStateEnforce | 2 | Enforce quota limit.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.UserNameResolution

UserNameResolution Property

Contains a value that controls how user security IDs are resolved to user names. Read/write.

object.UserNameResolution [= iUserNameResolution]

Possible Values

This property can be set to one of the following values.

Resolution type | Value | Description
dqResolveNone | 0 | Do not resolve user name information.
dqResolveSync | 1 | Wait while resolving name information.
dqResolveAsync | 2 | Do not wait while resolving name information. The OnUserNameChanged event fires when the name is resolved.

Remarks

This property affects the enumeration of DIDiskQuotaUser objects, and the AddUser and FindUser methods.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


DiskQuotaControl.AddUser

AddUser Method

Assigns a nondefault disk quota to a new user.

oUser = object.AddUser(sLogonName)

Parameters

sLogonName Required. String value that contains the user's logon name. Use the UserNameResolution property to specify how the name is to be resolved.

Return Values

Returns an object expression that evaluates to the user's DIDiskQuotaUser object.

Remarks

The NTFS file system automatically creates a user quota entry when a user first writes to the volume. Entries that are created in this way are assigned the default warning threshold and hard quota limit values for the volume. This method allows you to create a user quota entry before a user writes information to the volume. It returns a DIDiskQuotaUser object that can be used to assign a warning threshold or quota limit value that differs from the default settings for the volume.

If the user already exists, no new entry is created. The method returns the DIDiskQuotaUser object associated with the existing entry.

See Also

DefaultQuotaLimit, DefaultQuotaThreshold, DiskQuotaControl Object,

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl.DeleteUser

DeleteUser Method

Deletes a user from the volume.

object.DeleteUser(oUser)

Parameters

oUser Required. Object expression that evaluates to the user's DIDiskQuotaUser object.

Remarks

This method fails if the user owns any storage on the volume. Before you delete a user from a volume, all storage for that user must be deleted, be moved to another volume, or have its ownership transferred to another user.

See Also

AddUser, DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl.FindUser

FindUser Method

Finds a user's entry, by name, in the volume's quota file.

oUser = object.FindUser(sLogonName)

Parameters

sLogonName Required. String value that contains the user's logon name.

Return Values

Returns an object expression that evaluates to the user's DIDiskQuotaUser object.

Remarks

This method returns a DIDiskQuotaUser object even if there is no entry for the user in the quota file. The returned user object has warning threshold and hard quota limits set to the volume's default values.

The string returned from TranslateLogonNameToSID may be passed in place of the sLogonName parameter. When FindUser receives a SID string it uses the corresponding SID for direct lookup of the user's quota record on the volume. This bypasses the SID-name cache. In cases where FindUser fails due to a mismatch in format (SAM-compatible vs. UPN) of the logon name provided and the logon name cached, the logon name can be translated to a SID string using TranslateLogonNameToSID then passed again to FindUser. The following VBScript code illustrates this technique:

Function Find(dqc, name)
    On Error Resume Next
    SET Find = dqc.FindUser(name)
    If Err.Number <> 0 Then
        Err.Clear
        SET Find = dqc.FindUser(dqc.TranslateLogonNameToSID(name))
    End If
End Function

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl.GiveUserNameResolutionPriority

GiveUserNameResolutionPriority Method

Places the specified user object next in line for name resolution.

object.GiveUserNameResolutionPriority(oUser)

Parameters

oUser Required. Object expression that evaluates to the user's DIDiskQuotaUser object.

Remarks

If asynchronous name resolution is enabled, user objects are placed in a queue. By default, they are serviced in the order they are placed in the queue. The GiveUserNameResolutionPriority method moves an object to the front of the queue so that it is next in line to be serviced.

Use the UserNameResolution property to enable asynchronous name resolution.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl.Initialize

Initialize Method

Opens a specified volume and initializes its quota control object.

object.Initialize(sPath, bReadWrite)

Parameters

sPath | Required. String value that contains the fully qualified path of the volume to be initialized.
bReadWrite | Required. Boolean value that specifies how the volume is to be opened. Set bReadWrite to TRUE for read/write access or FALSE for read-only access.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl.InvalidateSidNameCache

InvalidateSidNameCache Method

Invalidates the security ID user name cache.

object.InvalidateSidNameCache()

Parameters

None.

Remarks

Users' names and associated security IDs are stored in a cache. You can clear this cache by calling InvalidateSidNameCache. If you subsequently create a new user object, the information will have to be obtained from the domain controller, and the cache will have to be reestablished.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl.ShutdownNameResolution

ShutdownNameResolution Method

Shuts down the user name resolution thread.

object.ShutdownNameResolution()

Parameters

None.

Remarks

The security ID name resolver translates security IDs (SIDs) to user names on a background thread. This thread is shut down automatically when the associated quota control object is destroyed. However, there are some cases when the thread is no longer needed, but the object is not yet ready to be destroyed. A typical example is when no further processing is taking place, but clients are still holding references to the object. The ShutdownNameResolution method allows you to terminate the resolver thread and free the associated resources without destroying the quota control object.

Note When you shut down the resolver thread, asynchronous name resolution immediately stops. If calls are subsequently made to methods such as AddUser or FindUser, the quota object might recreate the resolver thread.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


DiskQuotaControl_OnUserNameChanged

OnUserNameChanged Event

Occurs when the name information for a DIDiskQuotaUser object has been resolved.

Sub DiskQuotaControl_OnUserNameChanged(oUser)
    'Event handling code
End Sub

Parameters

oUser Object that evaluates to the DIDiskQuotaUser object associated with the user whose name has been resolved.

Remarks

When a client enumerates users, or calls the AddUser or FindUser method, the user name must be resolved to the associated security ID (SID). Because this procedure can be time-consuming, a client can have name resolution done asynchronously on a background thread. When a user's name is resolved, the DiskQuotaControl object notifies its client by firing the OnUserNameChanged event. A DIDiskQuotaUser object associated with the user is passed as a parameter. This object allows the client to modify the user's quota settings.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Dskquota.h.


Folder

Folder Object

The Folder object represents a Shell folder. It contains properties and methods that allow you to retrieve information about the folder.

Properties

Property | Description
Application | The folder's Application object. Read-only.
Parent | The object's parent object. Read-only.
ParentFolder | The parent Folder object. Read-only.
Title | The title of the folder. Read-only.

Methods

Method | Description
CopyHere | Copies an item or items to a folder.
GetDetailsOf | Retrieves information about an item in a folder.
Items | Retrieves a FolderItems object that represents the collection of items in the folder.
MoveHere | Moves an item or items to this folder.
NewFolder | Creates a new folder.
ParseName | Creates and returns a FolderItem object that represents a specified item.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.Application

Application Property

Description

Contains the folder's Application object. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a Folder object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.Parent

Parent Property

Description

Contains the object's parent object. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a Folder object.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.ParentFolder

ParentFolder Property

Description

Contains the parent Folder object. This is a read-only property.

Syntax

object.ParentFolder

Parameter | Description
object | Required. An object expression that evaluates to a Folder object.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.Title

Title Property

Description

Contains the title of the folder. This is a read-only property.

Syntax

object.Title

Parameter | Description
object | Required. An object expression that evaluates to a Folder object.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.CopyHere

CopyHere Method

Description

Copies an item or items to a folder.

Syntax

object.CopyHere vItem, [vOptions]

Parameter | Description
object | Required. An object expression that evaluates to a Folder object. This is the folder to which the item or items will be copied.
vItem | Required. Specifies the item or items to copy. This can be a string that represents a file name, a FolderItem object, or a FolderItems object.
vOptions | Optional. Specifies options for the copy operation. This can be zero or a combination of the FOF_ flags described under the fFlags member of the SHFILEOPSTRUCT structure.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.GetDetailsOf

GetDetailsOf Method

Description

Retrieves information about an item in a folder.

Syntax

object.GetDetailsOf vItem, iColumn

Parameter | Description
object | Required. An object expression that evaluates to a Folder object.
vItem | Required. Specifies the item for which to retrieve the information. This must be a FolderItem object.
iColumn Required. An integer value that specifies the information to be retrieved. The information available for an item depends on the folder in which it is displayed. This value corresponds to the zero-based column number that is displayed in a Shell view. For an item in the file system, this can be one of the following values:
Value | Description
0 | Retrieves the name of the item.
1 | Retrieves the size of the item.
2 | Retrieves the type of the item.
3 | Retrieves the date and time that the item was last modified.
4 | Retrieves the attributes of the item.
-1 | Retrieves the info tip information for the item.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.Items

Items Method

Description

Retrieves a FolderItems object that represents the collection of items in the folder.

Syntax

object.Items

Parameter | Description
object | Required. An object expression that evaluates to a Folder object.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.MoveHere

MoveHere Method

Description

Moves an item or items to this folder.

Syntax

object.MoveHere vItem, [vOptions]

Parameter | Description
object | Required. An object expression that evaluates to a Folder object. This is the folder to which the item or items will be moved.
vItem | Required. Specifies the item or items to move. This can be a string that represents a file name, a FolderItem object, or a FolderItems object.
vOptions | Optional. Specifies options for the move operation. This can be zero or a combination of the FOF_ flags described under the fFlags member of the SHFILEOPSTRUCT structure.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.NewFolder

NewFolder Method

Description

Creates a new folder.

Syntax

object.NewFolder bName, [vOptions]

Parameter | Description
object | Required. An object expression that evaluates to a Folder object. This is the folder in which the new folder will be created.
bName | Required. A string that specifies the name of the new folder.
vOptions | Optional. This value is not currently used.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder.ParseName

ParseName Method

Description

Creates and returns a FolderItem object that represents a specified item.

Syntax

object.ParseName bName

Parameter | Description
object | Required. An object expression that evaluates to a Folder object. This is the folder in which the new folder will be created.
bName | Required. A string that specifies the name of the item.

See Also

Folder

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Folder2

Folder2 Object

The Folder2 object extends the Folder object to support offline folders. In addition to the properties and methods supported by Folder, Folder2 has the following additional properties and methods.

Properties

HaveToShowWebViewBarricade | Specifies whether the Web view barricade is displayed. Read-only.
OfflineStatus | Contains the offline status of the server. Read-only.
Self | Contains the folder's FolderItem object. Read-only.

Methods

DismissedWebViewBarricade | Specifies that the Web view barricade has been dismissed by the user.
Synchronize | Synchronizes all offline files.

See Also

Folder Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


Folder2.HaveToShowWebViewBarricade Property

HaveToShowWebViewBarricade Property

Specifies whether the Web view barricade is displayed. Read-only.

bBarricade = object.HaveToShowWebViewBarricade

Possible Values

Boolean value that is set to TRUE if the Web view barricade is displayed, or FALSE otherwise.

See Also

Folder2 Object, Folder Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


Folder2.OfflineStatus Property

OfflineStatus Property

Contains the offline status of the folder. Read-only.

iOfflineStatus = object.OfflineStatus

Possible Values

Integer that is set to one of the following values.

Value | Description
OFS_DIRTYCACHE | Server is online with unsynchronized changes.
OFS_INACTIVE | Offline caching is not enabled for this folder.
OFS_OFFLINE | Server is offline.
OFS_ONLINE | Server is online.
OFS_SERVERBACK | Server is offline but can be reached.

See Also

Folder2 Object, Folder Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


Folder2.Self Property

Self Property

Contains the folder's FolderItem object. Read-only.

oFolderItem = object.Self

Possible Values

Object that evaluates to the folder's FolderItem object.

See Also

Folder2 Object, Folder Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


Folder2.DismissedWebViewBarricade

DismissedWebViewBarricade Method

Specifies that the Web view barricade has been dismissed by the user.

object.DismissedWebViewBarricade()

Parameters

None.

Return Values

None.

Remarks

Call this method after the Web view barricade is dismissed by the user.

See Also

Folder2 Object, Folder Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


Folder2.Synchronize

Synchronize Method

Synchronizes all offline files.

object.Synchronize()

Parameters

None.

Return Values

None.

See Also

Folder2 Object, Folder Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


FolderItem

FolderItem Object

The FolderItem object represents an item in a Shell folder. It contains properties and methods that allow you to retrieve information about the item.

Properties

Property | Description
Application | The Application object of the folder item. Read-only.
GetFolder | If the item is a folder, contains the item's Folder object. Read-only.
GetLink | If the item is a shortcut, contains the item's IShellLinkDual object. Read-only.
IsBrowsable | Indicates if the item can be browsed. Read-only.
IsFileSystem | Indicates if the item is part of the file system. Read-only.
IsFolder | Indicates if the item is a folder. Read-only.
IsLink | Indicates if the item is a shortcut. Read-only.
ModifyDate | The date and time that the item was last modified.
Name | The item's name.
Parent | The item's parent object. Read-only.
Path | The item's full path and name. Read-only.
Size | The item's size, in bytes. Read-only.
Type | A string representation of the item's type. Read-only.

Methods

Method | Description
InvokeVerb | Executes an item's verb.
Verbs | Retrieves the item's FolderItemVerbs object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Application

Application Property

Description

Contains the Application object of the folder item. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.GetFolder

GetFolder Property

Description

If the item is a folder, contains the item's Folder object. This is a read-only property.

Syntax

object.GetFolder

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

See Also

IsFolder Property

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.GetLink

GetLink Property

Description

If the item is a shortcut, contains the item's IShellLinkDual object . This is a read-only property.

Syntax

object.GetLink

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

See Also

IsLink Property

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.IsBrowsable

IsBrowsable Property

Description

Indicates if the item can be browsed. This property is TRUE if the item can be browsed or FALSE if not. This is a read-only property.

Syntax

object.IsBrowsable

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.IsFileSystem

IsFileSystem Property

Description

Indicates if the item is part of the file system. This property is TRUE if the item is part of the file system or FALSE if not. This is a read-only property.

Syntax

object.IsFileSystem

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.IsFolder

IsFolder Property

Description

Indicates if the item is a folder. This property is TRUE if the item is a folder or FALSE if not. This is a read-only property.

Syntax

object.IsFolder

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.IsLink

IsLink Property

Description

Indicates if the item is a shortcut. This property is TRUE if the item is a shortcut or FALSE if not. This is a read-only property.

Syntax

object.IsLink

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.ModifyDate

ModifyDate Property

Description

Contains the date and time that the item was last modified.

Syntax

object.ModifyDate

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Name

Name Property

Description

Contains the item's name.

Syntax

object.Name

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Parent

Parent Property

Description

Contains the item's parent object. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Path

Path Property

Description

Contains the item's full path and name. This is a read-only property.

Syntax

object.Path

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Size

Size Property

Description

Contains the item's size, in bytes. This is a read-only property.

Syntax

object.Size

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Type

Type Property

Description

Contains a string representation of the item's type. This is a read-only property.

Syntax

object.Type

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.InvokeVerb

InvokeVerb Method

Executes a verb on the item.

Syntax

object.InvokeVerb [vVerb]

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.
vVerb | Optional. A string that specifies the verb to be executed. It must be one of the values returned by the item's FolderItemVerb.Name property. If no verb is specified, the default verb will be invoked.

Remarks

A verb is a string used to specify a particular action that an item supports. Invoking a verb is equivalent to selecting a command from an item's shortcut menu. Typically, invoking a verb launches a related application. For example, invoking the "open" verb on a .txt file opens the file with a text editor, usually Notepad. See Launching Applications for further discussion of verbs.

The FolderItemVerbs object represents the collection of verbs associated with the item. The default verb may vary for different items, but it is typically "open".

See Also

FolderItem.Verbs, FolderItemVerb.DoIt

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItem.Verbs

Verbs Method

Description

Retrieves the item's FolderItemVerbs object. This object is the collection of verbs that can be executed on the item.

Syntax

object.Verbs

Parameter | Description
object | Required. An object expression that evaluates to a FolderItem object.

See Also

FolderItem.InvokeVerb, FolderItemVerb.DoIt

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems

FolderItems Object

The FolderItems object represents the collection of items in a Shell folder. It contains properties and methods that allow you to retrieve information about the collection.

Properties

Property | Description
Application | The Application object of the folder items collection. Read-only.
Count | The number of items in the collection. Read-only.
Parent | The parent object of the collection. Read-only.

Methods

Method | Description
Item | Retrieves the FolderItem object for a specified item in the collection.
_NewEnum | Creates and returns a new FolderItems object that is a copy of this FolderItems object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems.Application

Application Property

Description

Contains the Application object of the folder items collection. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a FolderItems object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

See Also

FolderItems

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems.Count

Count Property

Description

Contains the number of items in the collection. This is a read-only property.

Syntax

object.Count

Parameter | Description
object | Required. An object expression that evaluates to a FolderItems object.

See Also

FolderItems

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems.Parent

Parent Property

Description

Contains the parent object of the collection. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a FolderItems object.

See Also

FolderItems

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems.Item

Item Method

Description

Retrieves the FolderItem object for a specified item in the collection.

Syntax

object.Item [index]

Parameter | Description
object | Required. An object expression that evaluates to a FolderItems object.
index | Optional. Specifies the zero-based index of the item to retrieve. This value must be less than the value of the Count property.

See Also

FolderItems

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems._NewEnum

_NewEnum Method

Description

Creates and returns a new FolderItems object that is a copy of this FolderItems object.

Syntax

object._NewEnum

Parameter | Description
object | Required. An object expression that evaluates to a FolderItems object.

See Also

FolderItems

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItems2

FolderItems2 Object

The FolderItems2 object extends the FolderItems object. It supports one additional method.

Methods

InvokeVerbEx Executes a verb on a collection of FolderItem objects.

See Also

ShellExecute, ShellExecuteEx

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


FolderItems2.InvokeVerbEx

InvokeVerbEx Method

Executes a verb on a collection of FolderItem objects.

object.InvokeVerbEx([vVerb] [,vArgs])

Parameters

vVerb | Optional. Variant with the verb string that corresponds to the command to be executed. If no verb is specified, the default verb is executed.
vArgs | Optional. Variant that consists of a string with one or more arguments to the command specified by vVerb. The format of this string depends on the particular verb.

Return Values

None.

Remarks

A verb is a string used to specify a particular action associated with an item or collection of items. Typically, calling a verb launches a related application. For example, calling the open verb on a .txt file normally opens the file with a text editor, usually Microsoft® Notepad. For further discussion of verbs, see Launching Applications.

See Also

FolderItems2, ShellFolderItem.InvokeVerbEx

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


FolderItemVerb

FolderItemVerb Object

The FolderItemVerb object represents the verbs or commands to which an item in a Shell folder responds. It contains properties and methods that allow you to retrieve information about the collection.

Properties

Property | Description
Application | The Application object. Read-only.
Name | The verb's name. Read-only.
Parent | The object's parent object. Read-only.

Methods

Method | Description
DoIt | Executes a verb on a folder item.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerb.Application

Application Property

Description

Contains the FolderItemVerb object's Application object. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerb object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

See Also

FolderItemVerb

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerb.Name

Name Property

Description

Contains the verb's name. This is a read-only property.

Syntax

object.Name

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerb object.

See Also

FolderItemVerb

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerb.Parent

Parent Property

Description

Contains the object's parent object. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerb object.

See Also

FolderItemVerb

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerb.DoIt

DoIt Method

Description

Executes a verb on the FolderItem associated with the verb.

Syntax

object.DoIt

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerb object.

See Also

FolderItemVerb

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerbs

FolderItemVerbs Object

The FolderItemVerbs object represents the collection of verbs for an item in a Shell folder. It contains properties and methods that allow you to retrieve information about the collection.

Properties

Property | Description
Application | The Application object. Read-only.
Count | The verb's name. Read-only.
Parent | The object's parent object. Read-only.

Methods

Method | Description
Item | Retrieves the FolderItemVerb object for a specified item in the collection.
_NewEnum | Creates and returns a new FolderItemVerb object that is a copy of this FolderItemVerb object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerbs.Application

Application Property

Description

Contains the Application object of the object. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerbs object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

See Also

FolderItemVerbs

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerbs.Count

Count Property

Description

Contains the number of items in the collection. This is a read-only property.

Syntax

object.Count

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerbs object.

See Also

FolderItemVerbs

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerbs.Parent

Parent Property

Description

Contains the parent object of the object. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerbs object.

See Also

FolderItemVerbs

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerbs.Item

Item Method

Description

Retrieves the FolderItemVerb object for a specified item in the collection.

Syntax

object.Item [index]

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerbs object.
index | Optional. Specifies the zero-based index of the item to retrieve. This value must be less than the value of the Count property.

See Also

FolderItemVerbs

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


FolderItemVerbs._NewEnum

_NewEnum Method

Description

Creates and returns a new FolderItemVerbs object that is a copy of this FolderItemVerbs object.

Syntax

object._NewEnum

Parameter | Description
object | Required. An object expression that evaluates to a FolderItemVerbs object.

See Also

FolderItemVerbs

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


IShellDispatch2

IShellDispatch2 Object

The IShellDispatch2 object extends the Shell object. In addition to the properties and methods supported by Shell, IShellDispatch2 supports the following methods.

Methods

CanStartStopService | Determines if the current user can start and stop the named service.
FindPrinter | Finds a printer in the directory service.
GetSystemInformation | Retrieves information about the user's system.
IsRestricted | Not currently supported.
IsServiceRunning | Determines if the named service is running.
ServiceStart | Starts the named service.
ServiceStop | Stops the named service.
ShellExecute | Executes a command.
ShowBrowserBar | Shows or hides the browser bar.

Remarks

For a discussion of Microsoft® Windows® services, see the services documentation.

See Also

Shell Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.CanStartStopService

CanStartStopService Method

Determines if the current user can start and stop the named service.

bSuccess = object.CanStartStopService(sServiceName)

Parameters

sServiceName String value that contains the name of the service.

Return Values

Boolean. Returns TRUE if the user can start and stop the service, or FALSE otherwise.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.FindPrinter

FindPrinter Method

Displays the Find Printer dialog box to allow the user to find a printer.

object.FindPrinter([sName] [,sLocation] [,sModel])

Parameters

sName | Optional. String value that contains the printer name.
sLocation | Optional. String value that contains the printer location.
sModel | Optional. String value that contains the printer model.

Remarks

If you assign strings to one or more of the optional parameters, they are displayed as default values in the associated edit control when the Find Printer dialog box is displayed. The user can either accept or override these values. If no value is assigned to a parameter, the associated edit box is empty and the user must enter a value.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.GetSystemInformation

GetSystemInformation Method

Retrieves system information.

vSystemInfo = object.GetSystemInformation(sName)

Parameters

sName Required. String value that specifies the system information that is being requested.

Return Values

Variant. Returns the requested system information value. The return type depends on what system information is requested. See the Remarks section for details.

Remarks

This method can be used to request a number of system information values. The following table gives the sName value that is used to request the information and the type of the returned value.

sName value | Return type | Description
DirectoryServiceAvailable | Boolean | Set to TRUE if directory service is available, or FALSE otherwise.
DoubleClickTime | Integer | The double-click time, in milliseconds.
ProcessorLevel | Integer | The processor level. Returns 3, 4, or 5, for x386, x486, and Pentium-level processors, respectively.
ProcessorSpeed | Integer | The processor speed, in MHz.
ProcessorArchitecture | Integer | The processor architecture. For details, see the discussion of the wProcessorArchitecture member of the SYSTEM_INFO structure.
PhysicalMemoryInstalled | Integer | Amount of physical memory installed, in bytes.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.IsRestricted

IsRestricted Method

Not currently supported.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.IsServiceRunning

IsServiceRunning Method

Returns a value that indicates whether a named service is running.

bIsRunning = object.IsServiceRunning(sServiceName)

Parameters

sServiceName String value that contains the service's name.

Return Values

Variant. Returns TRUE if the service specified by sServiceName is running, or FALSE otherwise.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.ServiceStart

ServiceStart Method

Starts a named service.

bSuccess = object.ServiceStart(sServiceName, vPersistent)

Parameters

sServiceName | Required. String value that contains the name of the service.
vPersistent | Required. Variant value that is set to TRUE to have the service started automatically by the service control manager during system startup. To leave the service configuration unchanged, set vPersistent to FALSE.

Return Values

Variant. Returns TRUE if successful, or FALSE otherwise.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.ServiceStop

ServiceStop Method

Stops a named service.

bSuccess = object.ServiceStop(sServiceName, vPersistent)

Parameters

sServiceName | Required. String value that contains the name of the service.
vPersistent | Required. Variant value that is set to TRUE to have the service started by the service control manager when ServiceStart is called. To leave the service configuration unchanged, set vPersistent to FALSE.

Return Values

Boolean. Returns TRUE if successful, or FALSE otherwise.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.ShellExecute

ShellExecute Method

Performs a specified operation on a specified file.

object.ShellExecute(sFile [,vArguments] [,vDirectory] [,vOperation] [,vShow])

Parameters

sFile | Required. String value that contains the name of the file on which ShellExecute will perform the action specified by vOperation.
vArguments | Optional. Variant that contains the parameter values for the operation.
vDirectory | Optional. Variant that contains the fully qualified path of the directory that contains the file specified by sFile. If this parameter is not specified, the current working directory is used.
vOperation | Optional. Variant that specifies the operation to be performed. It should be set to one of the verb strings that is supported by the file. For a discussion of verbs, see the Remarks section. If this parameter is not specified, the default operation is performed.
vShow Optional. Variant that recommends how the window that belongs to the application that performs the operation should be displayed initially. The application can ignore this recommendation. vShow can take one of the following values. If this parameter is not specified, the application uses its default value.
0 | Open the application with a hidden window.
1 | Open the application with a normal window. If the window is minimized or maximized, the system restores it to its original size and position.
2 | Open the application with a minimized window.
3 | Open the application with a maximized window.
4 | Open the application with its window at its most recent size and position. The active window remains active.
5 | Open the application with its window at its current size and position.
7 | Open the application with a minimized window. The active window remains active.
10 | Open the application with its window in the default state specified by the application.

Remarks

This method is equivalent to launching one of the commands associated with a file's shortcut menu. Each command is identified by a verb string. The supported verbs vary from file to file. The most commonly supported verb is "open", which is also usually the default verb. Others might be supported only by certain types of files. For further discussion of Shell verbs, see Launching Applications or Extending Shortcut Menus.

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellDispatch2.ShowBrowserBar

ShowBrowserBar Method

Displays a browser bar.

object.ShowBrowserBar(sCLSID, vShow)

Parameters

sCLSID | Required. String value that contains the string form of the CLSID of the browser bar to be displayed. The object must be registered as an Explorer Bar object with a CATID_InfoBand component category. For further information, see Creating Custom Explorer Bars, Tool Bands, and Desk Bands.
vShow | Required. Variant that is set to TRUE to show the browser bar, or FALSE to hide it.

Return Values

Variant. Returns TRUE if successful, or FALSE otherwise.

Remarks

You can display one of the standard Explorer Bars by setting sCLSID to its CLSID string. The standard Explorer Bars and their CLSID strings are as follows.

Explorer Bar | CLSID string
Favorites | {EFA24E61-B078-11d0-89E4-00C04FC9E26E}
Folders | {EFA24E64-B078-11d0-89E4-00C04FC9E26E}
History | {EFA24E62-B078-11d0-89E4-00C04FC9E26E}
Search | {30D02401-6A81-11d0-8274-00C04FD5AE38}

See Also

IShellDispatch2 Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellLinkDual2

IShellLinkDual2 Object

The IShellLinkDual2 object extends the ShellLinkObject object. It supports one additional property.

Properties

Target Contains the link object's target. Read-only.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


IShellLinkDual2.Target

Target Property

Contains the link object's target. Read-only.

oTargetItem = object.Target

Possible Values

Object expression that evaluates to the target's FolderItem object.

See Also

IShellLinkDual2 Object, ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


Shell

Shell Object

The Shell object represents the objects in the Shell. There are methods to control the Shell and to execute commands within the Shell. There are also methods to obtain other Shell-related objects.

Properties

Property | Description
Application | Contains the object's Application object.
Parent | Contains the object's parent object. Read-only.

Methods

Method | Description
BrowseForFolder | Creates a dialog box that allows the user to select a folder and then returns the selected folder's Folder object.
CascadeWindows | Cascadess all of the windows on the desktop.
ControlPanelItem | Runs a Control Panel application.
EjectPC | Ejects the computer from its docking station.
Explore | Explores a folder.
FileRun | Displays the Run dialog to the user.
FindComputer | Displays the Find: Computer dialog box.
FindFiles | Displays the Find: All Files dialog box.
Help | Displays Microsoft® Windows® Help.
MinimizeAll | Minimizes all of the windows on the desktop.
NameSpace | Creates and returns a Folder object for the specified folder.
Open | Opens a folder.
RefreshMenu | Refreshes the contents of the Start Menu.
SetTime | Displays the Date/Time Properties dialog box.
ShutdownWindows | Displays the Shut Down Windows dialog box.
Suspend | Suspends the computer.
TileHorizontally | Tiles all of the windows on the desktop horizontally.
TileVertically | Tiles all of the windows on the desktop vertically.
TrayProperties | Displays the Taskbar Properties dialog box.
UndoMinimizeALL | Restores all of the windows on the desktop to the same state they were in before the last MinimizeAll command.
Windows | Creates and returns a ShellWindows object.

Constants

Constant | Description
ShellSpecialFolderConstants | Set of values that specify special folders in the Shell.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Application

Description

Contains the object's Application object. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Parent

Parent Property

Description

Contains the object's parent object. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.BrowseForFolder

BrowseForFolder Method

Description

Creates a dialog box that allows the user to select a folder and then returns the selected folder's Folder object.

Syntax

object.BrowseForFolder Hwnd, Title, Options, [RootFolder]

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.
Hwnd | Required. The handle to the window that will be the parent of the browse dialog box. This value can be zero.
Title | Required. A string value that represents the title that will be displayed inside the browse dialog box.
Options | Required. A long value that contains the options for the method. This can be zero or a combination of the values listed under the ulFlags member of the BROWSEINFO structure.
RootFolder | Optional. Specifies the root of the browse dialog box. The user cannot browse higher in the folder architecture than this folder. If this value is not specified, the root of the browse dialog box is the desktop. This value can be a string that specifies the path of the folder or one of the ShellSpecialFolderConstants values.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.CascadeWindows

CascadeWindows Method

Description

Cascades all of the windows on the desktop. This method has the same effect as right-clicking the taskbar and selecting Cascade Windows.

Syntax

object.CascadeWindows

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.ControlPanelItem

ControlPanelItem Method

Description

Runs the specified Control Panel application. If the application is already open, it will activate the running instance.

Syntax

object.ControlPanelItem szDir

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.
szDir | Required. Specifies the Control Panel application's file name. All Control Panel applications have the .cpl extension.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.EjectPC

EjectPC Method

Description

Ejects the computer from its docking station. This is the same as clicking the Start menu and selecting Eject PC, if your computer supports this command.

Syntax

object.EjectPC

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Explore

Explore Method

Description

Explores a folder.

Syntax

object.Explore vDir

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.
vDir | Required. Specifies the folder to be explored. This can be a string that specifies the path of the folder or one of the ShellSpecialFolderConstants values.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.FileRun

FileRun Method

Description

Displays the Run dialog to the user. This method has the same effect as clicking the Start Menu and selecting Run.

Syntax

object.FileRun

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.FindComputer

FindComputer Method

Description

Displays the Search Results - Computers dialog box. The dialog box shows the result of the search for a specified computer.

Syntax

object.FindComputer

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.FindFiles

FindFiles Method

Description

Displays the Find: All Files dialog box. This is the same as clicking the Start Menu, selecting Find, and then selecting Files or Folders.

Syntax

object.FindFiles

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Help

Help Method

Description

Displays Microsoft® Windows® Help. This method has same effect as clicking the Start Menu and selecting Help.

Syntax

object.Help

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.MinimizeAll

MinimizeAll Method

Description

Minimizes all of the windows on the desktop. This method has the same effect as right-clicking the taskbar and selecting Minimize All Windows.

Syntax

object.MinimizeAll

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

UndoMinimizeALL, Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.NameSpace

NameSpace Method

Description

Creates and returns a Folder object for the specified folder.

Syntax

object.NameSpace vDir

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.
vDir | Required. Specifies the folder for which to create the Folder object. This can be a string that specifies the path of the folder or one of the ShellSpecialFolderConstants values.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Open

Open Method

Description

Opens a folder.

Syntax

object.Open vDir

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.
vDir | Required. This can be a string that specifies the path of the folder or one of the ShellSpecialFolderConstants values.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.RefreshMenu

RefreshMenu Method

Description

Refreshes the contents of the Start Menu.

Syntax

object.RefreshMenu

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.SetTime

SetTime Method

Description

Displays the Date/Time Properties dialog box. This method has the same effect as right-clicking the clock in the taskbar status area and selecting Adjust Date/Time.

Syntax

object.SetTime

Parameter | Description
object | Required. Object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.ShutdownWindows

ShutdownWindows Method

Description

Displays the Shut Down Windows dialog box. This is the same as clicking the Start menu and selecting Shut Down.

Syntax

object.ShutdownWindows

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Suspend

Suspend Method

Description

Suspends the computer. This method has the same effect as clicking the Start menu and selecting Suspend (for computers that support suspending).

Syntax

object.Suspend

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.TileHorizontally

TileHorizontally Method

Description

Tiles all of the windows on the desktop horizontally. This method has the same effect as right-clicking the taskbar and selecting Tile Windows Horizontally.

Syntax

object.TileHorizontally

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.TileVertically

TileVertically Method

Description

Tiles all of the windows on the desktop vertically. This method has the same effect as right-clicking the taskbar and selecting Tile Windows Vertically.

Syntax

object.TileVertically

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.TrayProperties

TrayProperties Method

Description

Displays the Taskbar Properties dialog box. This method has the same effect as right-clicking the taskbar and selecting Properties.

Syntax

object.TrayProperties

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.UndoMinimizeALL

UndoMinimizeALL Method

Description

Restores all of the windows on the desktop to the same state they were in before the last MinimizeAll command. This method has the same effect as right-clicking the taskbar and selecting Undo Minimize All Windows.

Syntax

object.UndoMinimizeALL

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


Shell.Windows

Windows Method

Description

Creates and returns a ShellWindows object. This object represents a collection of all of the open windows that belong to the Shell.

Syntax

object.Windows

Parameter | Description
object | Required. An object expression that evaluates to a Shell object.

See Also

Shell

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellSpecialFolderConstants

ShellSpecialFolderConstants Enumeration

There are a number of standard folders that are used frequently by applications, but may not have the same name or location on any given system. For example, the system folder may be "C:\Windows" on one system and "C:\Winnt" on another. The values in this enumeration are equivalent to the CSIDL values used in C++ applications. They provide a unique system-independent way for applications to identify special folders. They supersede the use of environment variables for this purpose.

Note: Where the a constant identifies a file system folder, a commonly used path on Windows 2000 systems is given as an example. However, there is no guarantee that this path will be used on any particular system, including Windows 2000 systems.

enum ShellSpecialFolderConstants
    {	ssfDESKTOP	= 0,
    ssfPROGRAMS	= 0x2,
    ssfCONTROLS	= 0x3,
    ssfPRINTERS	= 0x4,
    ssfPERSONAL	= 0x5,
    ssfFAVORITES	= 0x6,
    ssfSTARTUP	= 0x7,
    ssfRECENT	= 0x8,
    ssfSENDTO	= 0x9,
    ssfBITBUCKET	= 0xa,
    ssfSTARTMENU	= 0xb,
    ssfDESKTOPDIRECTORY	= 0x10,
    ssfDRIVES	= 0x11,
    ssfNETWORK	= 0x12,
    ssfNETHOOD	= 0x13,
    ssfFONTS	= 0x14,
    ssfTEMPLATES	= 0x15,
    ssfCOMMONSTARTMENU	= 0x16,
    ssfCOMMONPROGRAMS	= 0x17,
    ssfCOMMONSTARTUP	= 0x18,
    ssfCOMMONDESKTOPDIR	= 0x19,
    ssfAPPDATA	= 0x1a,
    ssfPRINTHOOD	= 0x1b,
    ssfLOCALAPPDATA	= 0x1c,
    ssfALTSTARTUP	= 0x1d,
    ssfCOMMONALTSTARTUP	= 0x1e,
    ssfCOMMONFAVORITES	= 0x1f,
    ssfINTERNETCACHE	= 0x20,
    ssfCOOKIES	= 0x21,
    ssfHISTORY	= 0x22,
    ssfCOMMONAPPDATA	= 0x23,
    ssfWINDOWS	= 0x24,
    ssfSYSTEM	= 0x25,
    ssfPROGRAMFILES	= 0x26,
    ssfMYPICTURES	= 0x27,
    ssfPROFILE	= 0x28,
    }	ShellSpecialFolderConstants;

Members

ssfALTSTARTUP
File system directory that corresponds to the user's nonlocalized Startup program group. (value = 29)
ssfAPPDATA
Version 4.71. File system directory that serves as a common repository for application-specific data. A typical path is C:\Documents and Settings\username\Application Data. (value = 26)
ssfBITBUCKET
Virtual folder containing the objects in the user's Recycle Bin. (value = 15)
ssfCOMMONALTSTARTUP
File system directory that corresponds to the nonlocalized Startup program group for all users. Valid only for Windows NT® systems. (value = 30)
ssfCOMMONAPPDATA
Version 5.0. Application data for all users. A typical path is C:\Documents and Settings\All Users\Application Data. (value = 35)
ssfCOMMONDESKTOPDIR
File system directory that contains files and folders that appear on the desktop for all users. A typical path is C:\Documents and Settings\All Users\Desktop. Valid only for Windows NT® systems. (value = 25)
ssfCOMMONFAVORITES
File system directory that serves as a common repository for all users' favorite items. Valid only for Windows NT® systems.(value = 31)
ssfCOMMONPROGRAMS
File system directory that contains the directories for the common program groups that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs. Valid only for Windows NT® systems. (value = 23)
ssfCOMMONSTARTMENU
File system directory that contains the programs and folders that appear on the Start menu for all users. A typical path is C:\Documents and Settings\All Users\Start Menu. Valid only for Windows NT® systems. (value = 22)
ssfCOMMONSTARTUP
File system directory that contains the programs that appear in the Startup folder for all users. A typical path is C:\Documents and Settings\All Users\Start Menu\Programs\Startup. Valid only for Windows NT® systems. (value = 24)
ssfCONTROLS
Virtual folder containing icons for the Control Panel applications. (value = 3)
ssfCOOKIES
File system directory that serves as a common repository for Internet cookies. A typical path is C:\Documents and Settings\username\Cookies. (value = 33)
ssfDESKTOP
Windows Desktop—virtual folder that is the root of the namespace. (value = 0)
ssfDESKTOPDIRECTORY
File system directory used to physically store the file objects that are displayed on the desktop. It is not to be confused with the desktop folder itself, which is a virtual folder. A typical path is C:\Documents and Settings\username\Desktop (value = 16)
ssfDRIVES
My Computer—virtual folder containing everything on the local computer: storage devices, printers, and Control Panel. This folder may also contain mapped network drives. (value = 17)
ssfFAVORITES
File system directory that serves as a common repository for the user's favorite items. A typical path is C:\Documents and Settings\username\Favorites. (value = 6)
ssfFONTS
Virtual folder containing installed fonts. A typical path is C:\WINNT\Fonts. (value = 20)
ssfHISTORY
File system directory that serves as a common repository for Internet history items. (value = 34)
ssfINTERNETCACHE
File system directory that serves as a common repository for temporary Internet files. A typical path is C:\Documents and Settings\username\Temporary Internet Files. (value = 32)
ssfLOCALAPPDATA
Version 5.0. File system directory that serves as a data repository for local (non-roaming) applications. A typical path is C:\Documents and Settings\username\Local Settings\Application Data. (value = 28)
ssfMYPICTURES
My Pictures folder. A typical path is C:\Documents and Settings\username\My Documents\My Pictures. (value = 39)
ssfNETHOOD
A file system folder containing the link objects that may exist in the My Network Places virtual folder. It is not the same as ssfNETWORK, which represents the network namespace root. A typical path is C:\Documents and Settings\username\NetHood. (value = 19)
ssfNETWORK
Network Neighborhood—virtual folder representing the root of the network namespace hierarchy. (value = 18)
ssfPERSONAL
File system directory that serves as a common repository for a user's documents. A typical path is C:\Documents and Settings\username\My Documents. (value = 5)
ssfPRINTERS
Virtual folder containing installed printers. (value = 4)
ssfPRINTHOOD
File system directory that contains the link objects that may exist in the Printers virtual folder. A typical path is C:\Documents and Settings\username\PrintHood. (value = 27)
ssfPROFILE
Version 5.0. User's profile folder. (value = 40)
ssfPROGRAMFILES
Version 5.0. Program Files folder. A typical path is C:\Program Files. (value = 38)
ssfPROGRAMS
File system directory that contains the user's program groups (which are also file system directories). A typical path is C:\Documents and Settings\username\Start Menu\Programs. (value = 2)
ssfRECENT
File system directory that contains the user's most recently used documents. A typical path is C:\Documents and Settings\username\Recent. (value = 8)
ssfSENDTO
File system directory that contains Send To menu items. A typical path is C:\Documents and Settings\username\SendTo. (value = 9)
ssfSTARTMENU
File system directory containing Start menu items. A typical path is C:\Documents and Settings\username\Start Menu. (value = 11)
ssfSTARTUP
File system directory that corresponds to the user's Startup program group. The system starts these programs whenever any user logs onto Windows NT® or starts Windows® 95. A typical path is C:\Documents and Settings\username\Start Menu\Programs\Startup. (value = 7)
ssfSYSTEM
Version 5.0. System folder. A typical path is C:\WINNT\SYSTEM32. (value = 37)
ssfTEMPLATES
File system directory that serves as a common repository for document templates. (value = 21)
ssfWINDOWS
Version 5.0. Windows directory or SYSROOT. This corresponds to the %windir% or %SYSTEMROOT% environment variables. A typical path is C:\WINNT. (value = 36)

See Also

Shell


ShellFolderItem

ShellFolderItem Object

This object extends the FolderItem object. In addition to the properties and methods supported by FolderItem, ShellFolderItem has two additional methods.

Methods

ExtendedProperty | Returns the value of a property from an item's property set. The property can be specified either by name or by the property set's format identifier (FMTID) and property identifier (PID).
InvokeVerbEx | Executes a verb on a Shell item.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellFolderItem.ExtendedProperty

ExtendedProperty Method

Returns the value of a property from an item's property set. The property can be specified either by name or by the property set's format identifier (FMTID) and property identifier (PID).

vProperty = object.ExtendedProperty(sPropName)

Parameters

sPropName Required. String value that specifies the property. There are two ways to specify a property. The first is to assign the property's name, such as "Author" or "Date", to sPropName. However, each property is a member of a COM property set and can also be identified by specifying its format ID (FMTID) and property ID (PID). An FMTID is a GUID that identifies the property set, and a PID is an integer that identifies a particular property within the property set. Specifying a property by its FMTID/PID values is usually more efficient than using its name. To use a property's FMTID/PID values with ExtendedProperty, they must be combined into an SCID. An SCID is a string that contains the FMTID/PID values in the form "FMTID,PID", where the FMTID is the string form of the property set's GUID. For example, the SCID of the summary information property set's author property is "{F29F85E0-4FF9-1068-AB91-08002B27B3D9},4". For a list of FMTIDs and PIDs that are currently supported by the Shell, see SHCOLUMNID.

Return Values

Variant. Returns the value of the property, if it exists for the specified item. The value will have full typing—for example, dates will be returned as dates, not strings.

This method returns a zero-length string if the property is valid but does not exist for the specified item, or an OLE error code otherwise.

Example

This sample code illustrates how to use ExtendedProperty to retrieve the "Title" and "Author" properties from a Microsoft® Word document. Once you have the ShellFolderItem object associated with the file, fiWordDoc in this example, retrieve the property's value by passing its name to ExtendedProperty.

...
Doc_Title=fiWordDoc.ExtendedProperty("Title")
Doc_Author=fiWordDoc.ExtendedProperty("Author")
...

A faster and more efficient approach is to pass an SCID to ExtendedProperty.

...
FMTID_SummaryInfo="{F29F85E0-4FF9-1068-AB91-08002B27B3D9}"
PID_TITLE="2"
PID_AUTHOR="4"
SCID_TITLE=FMTID_SummaryInfo+","+PID_TITLE
SCID_AUTHOR=FMTID_SummaryInfo+","+PID_AUTHOR
Doc_Title=fiWordDoc.ExtendedProperty(SCID_TITLE)
Doc_Author=fiWordDoc.ExtendedProperty(SCID_AUTHOR)
...

See Also

ShellFolderItem Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellFolderItem.InvokeVerbEx

InvokeVerbEx Method

Executes a verb on a Shell item.

object.InvokeVerbEx([vVerb] [,vArgs])

Parameters

vVerb | Optional. Variant with the verb string that corresponds to the command to be executed. It must be one of the values returned by the item's FolderItemVerb.Name property. If no verb is specified, the default verb is executed.
vArgs | Optional. Variant that consists of a string with one or more arguments to the command specified by vVerb. The format of this string depends on the particular verb.

Return Values

None.

Remarks

A verb is a string used to specify a particular action that an item supports. Typically, calling a verb launches a related application. For example, calling the open verb on a .txt file normally opens the file with a text editor, usually Microsoft® Notepad. The FolderItemVerbs object represents the collection of verbs associated with the item. For further discussion of verbs, see Launching Applications.

This method is similar to FolderItem.InvokeVerb, but it allows you to specify arguments to the command as well as the command itself.

See Also

ShellFolderItem Object, FolderItem.InvokeVerb

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellFolderView

ShellFolderView Object

The ShellFolderView object represents the objects in a view. There are properties and methods used to obtain information about the contents of the view.

Properties

Property | Description
Application | Contains the object's Application object. Read-only.
FocusedItem | Contains a FolderItem object that represents the item that has the input focus. Read-only.
Folder | Contains a Folder object that represents the view. Read-only.
Parent | Contains the object's parent object. Read-only.
Script | Contains the scripting object for the view. Read-only.
ViewOptions | Contains a set of ShellFolderViewOptions flags that indicate the current options of the view. Read only.

Methods

Method | Description
PopupItemMenu | Creates a shortcut menu for an item and returns the selected command string.
SelectedItems | Retrieves a FolderItems object that represents all of the selected items in the view.
SelectItem | Sets the selection state of an item in the view.

Events

Event | Description
SelectionChanged | The selection state of any item or items in the view has changed

Constants

Constant | Description
ShellFolderViewOptions | Specifies the view options returned by the ViewOptions property.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.Application

Application Property

Description

Contains the object's Application object. This is a read-only property.

Syntax

object.Application

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

Remarks

The Application property returns the automation object supported by the application that contains the WebBrowser control, if that object is accessible. Otherwise, this property returns the WebBrowser control's automation object.

Use this property with the Set and CreateObject commands or with the GetObject command to create and manipulate an instance of the Internet Explorer application.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.FocusedItem

FocusedItem Property

Description

Contains a FolderItem object that represents the item that has the input focus. This is a read-only property.

Syntax

object.FocusedItem

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.Folder

Folder Property

Description

Contains a Folder object that represents the view. This is a read-only property.

Syntax

object.Folder

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.Parent

Parent Property

Description

Contains the object's parent object. This is a read-only property.

Syntax

object.Parent

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.Script

Script Property

Description

Contains the scripting object for the view. This is a read-only property.

Syntax

object.Script

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.ViewOptions

ViewOptions Property

Description

Contains a set of ShellFolderViewOptions flags that indicate the current options of the view. This is a read-only property.

Syntax

object.ViewOptions

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.PopupItemMenu

PopupItemMenu Method

Description

Creates a shortcut menu for the specified item and returns the selected command string.

Syntax

object.PopupItemMenu vItem, [vx], [vy]

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.
vItem | Required. The FolderItem object for which the shortcut menu will be created.
vx | Optional. The horizontal position of the menu, in screen coordinates.
vy | Optional. The vertical position of the menu, in screen coordinates.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.SelectedItems

SelectedItems Method

Description

Retrieves a FolderItems object that represents all of the selected items in the view.

Syntax

object.SelectedItems

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.SelectItem

SelectItem Method

Description

Sets the selection state of an item in the view.

Syntax

object.SelectItem vItem, dwFlags

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.
vItem | Required. The FolderItem object for which the selection state will be set.
dwFlags Required. A set of flags that indicate the new selection state. This can be one or more of the following values:
Flag | Description
0 | Deselect the item.
1 | Select the item.
3 | Put the item in edit mode.
4 | Deselect all but the specified item.
8 | Ensure the item is displayed in the view.
16 | Give the item the focus.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderView.SelectionChanged

SelectionChanged Event

Description

Occurs when the selection state of any item or items in the view has changed.

Syntax

Private Sub object_SelectionChanged

Parameter | Description
object | Required. An object expression that evaluates to a ShellFolderView object.

See Also

ShellFolderView

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


ShellFolderViewOptions

ShellFolderViewOptions Enumeration

Description

Specifies the view options returned by the ViewOptions property.

Syntax

enum ShellFolderViewOptions {
    SFVVO_SHOWALLOBJECTS = 0x00000001,
    SFVVO_SHOWEXTENSIONS = 0x00000002,
    SFVVO_SHOWCOMPCOLOR = 0x00000008,
    SFVVO_SHOWSYSFILES = 0x00000020,
    SFVVO_WIN95CLASSIC = 0x00000040,
    SFVVO_DOUBLECLICKINWEBVIEW = 0x00000080,
    SFVVO_DESKTOPHTML = 0x00000200,
} ShellFolderViewOptions;

Parameter | Description
SFVVO_SHOWALLOBJECTS | The Show All Files option is enabled.
SFVVO_SHOWEXTENSIONS | The Hide File Extensions for Known File Types option is disabled.
SFVVO_SHOWCOMPCOLOR | The Display Compressed Files and Folders with Alternate Color option is enabled.
SFVVO_SHOWSYSFILES | The Do Not Show Hidden Files option is enabled.
SFVVO_WIN95CLASSIC | The Classic Style option is enabled.
SFVVO_DOUBLECLICKINWEBVIEW | The Double-Click to Open an Item option is enabled.
SFVVO_DESKTOPHTML | The Active Desktop – View as Web Page option is enabled.

See Also

ShellFolderView


ShellFolderViewOC

ShellFolderViewOC Object

The ShellFolderViewOC object forwards the events fired by a specified ShellFolderView object to corresponding ShellFolderViewOC event handlers.

The ShellFolderView object fires two events, EnumDone and SelectionChanged, that must normally be handled by applications. However, some applications need to handle events from a series of ShellFolderView objects. For example, an application might host a Web Browser control that allows users to navigate through a series of folders. Each folder has its own ShellFolderView object with its associated events. Handling these events can be rather difficult.

The ShellFolderViewOC object simplifies event handling for such scenarios. It allows applications to handle events for all ShellFolderView objects with a single pair of ShellFolderViewOC event handlers. Each time the user navigates to a new folder, the application passes the associated ShellFolderView object to the ShellFolderViewOC object by calling SetFolderView. Then, when an EnumDone or SelectionChanged event is fired, the ShellFolderViewOC object forwards the event to its own handler for processing.

The ShellFolderViewOC object supports the following methods and events.

Methods

SetFolderView Forwards the events of the specified ShellFolderView object to the corresponding ShellFolderViewOC event handler.

Events

EnumDone | Indicates that the ShellFolderView object has finished enumerating the folder's contents.
SelectionChanged | Indicates that the selection state of one or more items in the view has changed.

See Also

ShellFolderView Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellFolderViewOC.SetFolderView Method

SetFolderView Method

Forwards the events of the specified ShellFolderView object to the corresponding ShellFolderViewOC event handler.

object.SetFolderView(oShellFolderView)

Parameters

oShellFolderView Required. ShellFolderView object. Its EnumDone and SelectionChanged events will be forwarded to the corresponding ShellFolderViewOC event handler.

See Also

ShellFolderViewOC Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellFolderViewOC.EnumDone Event

EnumDone Event

Indicates that the ShellFolderView object has finished enumerating the folder's contents.

Sub ShellFolderViewOC_EnumDone()
    'Event handling code
End Sub

Remarks

The ShellFolderView object must enumerate the contents of a folder before it can display it. With folders that are large or located on a remote system, this process can take as much as several minutes. During this time, an animated flashlight graphic is displayed to indicate to the user that processing is under way. Once the enumeration is complete, the EnumDone event is fired and the flashlight graphic is replaced by the contents of the folder.

See Also

ShellFolderViewOC Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellFolderViewOC.SelectionChanged Event

SelectionChanged Event

Indicates that the selection state of one or more items in the view has changed.

Sub ShellFolderViewOC_SelectionChanged()
    'Event handling code
End Sub

See Also

ShellFolderViewOC Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject

ShellLinkObject Object

The ShellLinkObject object manages Shell links. It makes much of the functionality of the IShellLink interface available to scripting applications. For further discussion of Shell links, see Shell Links. The ShellLinkObject object supports the following properties and methods.

Properties

Arguments | Contains the link's arguments. Read/write.
Description | Contains the link's description. Read/write.
Hotkey | Contains the link's hot-key code. Read/write.
Path | Contains the link's path. Read/write.
ShowCommand | Contains the initial show state of the link's command. Read/write.
WorkingDirectory | Contains the link's working directory. Read/write.

Methods

GetIconLocation | Retrieves the location of the link's icon.
Resolve | Attempts to find the target of a Shell link, even if the target has been moved or renamed.
Save | Saves all changes to the link.
SetIconLocation | Sets the location of the link's icon.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.Arguments

Arguments Property

Contains the link's arguments. Read/write.

object.Arguments [= sArguments]

Possible Values

String value that contains the link's arguments.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.Description

Description Property

Contains the link's description. Read/write.

object.Description [= sDescription]

Possible Values

String value that contains the link's description.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.Hotkey

Hotkey Property

Contains the link's hot-key code. Read/write.

object.Hotkey [= iHotkey]

Possible Values

Integer that contains the link's hot-key code. The virtual key code is in the low-order byte, and the modifier flags are in the high-order byte. The modifier flags can be a combination of the following values.

1 | SHIFT key
2 | CTRL key
4 | ALT key
8 | Extended key

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.Path

Path Property

Contains the link's path. Read/write.

sPath = object.Path

Possible Values

String value that contains the link's fully qualified path.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.ShowCommand

ShowCommand Property

Contains the initial show state of the link's command. Read/write.

iShowCommand = object.ShowCommand

Possible Values

Integer that contains the link's show state. This can be one of the following values.

1 | Activates and displays a window. If the window is minimized or maximized, the system restores it to its original size and position.
2 | Activates the window and displays it as a minimized window.
3 | Activates the window and displays it as a maximized window.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.WorkingDirectory

WorkingDirectory Property

Contains the link's working directory. Read/write.

sWorkingDirectory = object.WorkingDirectory

Possible Values

String value that contains the fully qualified path of the link's working directory.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.GetIconLocation

GetIconLocation Method

Retrieves the location of the link's icon.

iIcon = object.GetIconLocation(sPath)

Parameters

sPath Required. String variable. When the method returns, it holds the fully qualified path of the file containing the icon.

Return Values

Integer. Returns the icon's index in the file specified by sPath.

See Also

ShellLinkObject Object, ShellLinkObject.SetIconLocation

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.Resolve

Resolve Method

Attempts to find the target of a Shell link, even if the target has been moved or renamed.

object.Resolve(fFlags)

Parameters

fFlags Required. Flags that specify the action to be taken. This can be a combination of the following values.
1 | Do not display a dialog box if the link cannot be resolved. When this flag is set, the high-order word of fFlags specifies a time-out duration, in milliseconds. The method returns if the link cannot be resolved within the time-out duration. If the high-order word is set to zero, the time-out duration defaults to 3000 milliseconds (3 seconds).
4 | If the link has changed, update its path and list of identifiers.
8 | Do not update the link information.
16 | Do not execute the search heuristics.
32 | Do not use distributed link tracking.
64 | Disable distributed link tracking. By default, distributed link tracking tracks removable media across multiple devices based on the volume name. It also uses the UNC (Universal Naming Convention) path to track remote file systems whose drive letter has changed. Setting this flag disables both types of tracking.
128 | Call the Microsoft® Windows® Installer.

Remarks

This method is essentially identical in functionality to IShellLink::Resolve. For further discussion of link resolution, see the Remarks section of that reference page.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.Save

Save Method

Saves all changes to the link.

object.Save([sFile])

Parameters

sFile Optional. String value that contains the fully qualified path of the file where the new link information is to be saved. If no file is specified, the current file is used.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellLinkObject.SetIconLocation

SetIconLocation Method

Sets the location of the link's icon.

object.SetIconLocation(sPath, iIndex)

Parameters

sPath | Required. String value that contains the fully qualified path of the file that contains the icon.
iIndex | Required. Integer that is set to the index of the icon in the file specified by sPath.

See Also

ShellLinkObject Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in shldisp.h.


ShellUIHelper

ShellUIHelper Object

The ShellUIHelper object is implemented by the Shell to help script and Visual Basic developers to use some of the features available in the Shell. The ShellUIHelper object does not have any properties or events. There are methods you can use to add items to the Shell.

Methods

Method | Description
AddChannel | Adds a new channel to the list of channels.
AddDesktopComponent | Adds an item to the Active Desktop.
AddFavorite | Displays the default user interface for creating a favorite item.
IsSubscribed | Indicates whether or not a URL is subscribed to.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellUIHelper.AddChannel

AddChannel Method

Description

Adds a new channel to the list of channels.

Syntax

object.AddChannel URL

Parameter | Description
object | Required. An object expression that evaluates to a ShellUIHelper object.
URL Required. | A string value that specifies the URL of the Channel Definition File.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellUIHelper.AddDesktopComponent

AddDesktopComponent Method

Description

Adds an item to the Active Desktop.

Syntax

object.AddDesktopComponent URL Type [Left] [Top] [Width] [Height]

Parameter | Description
object | Required. An object expression that evaluates to a ShellUIHelper object.
URL | Required. A string value that specifies the URL of the new favorite item.
Type Required. A string value that specifies the type of item being added. This can be one of the following values:
"image" | The component is an image.
"website" | The component is a web site.
Left | Optional. Specifies the position of the left edge of the component, in screen coordinates.
Top | Optional. Specifies the position of the top edge of the component, in screen coordinates.
Width | Optional. Specifies the width of the component, in screen units.
Height | Optional. Specifies the height of the component, in screen units.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellUIHelper.AddFavorite

AddFavorite Method

Description

Displays the default user interface for creating a favorite item. The user interface will be initialized to the specified parameters.

Syntax

object.AddFavorite URL [Title]
Parameter | Description
object | Required. An object expression that evaluates to a ShellUIHelper object.
URL | Required. A string value that specifies the URL of the item to be added to the Favorites folder.
Title | Optional. A string value that specifies the name of the item.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellUIHelper.IsSubscribed

IsSubscribed Method

Description

Indicates whether or not a URL is subscribed to. Returns TRUE if the URL is subscribed to or FALSE otherwise.

Syntax

object.IsSubscribed URL
Parameter | Description
object | Required. An object expression that evaluates to a ShellUIHelper object.
URL | Required. A string value that specifies the URL that is to be tested.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellWindows

ShellWindows Object

The ShellWindows object represents a collection of the open windows that belong to the Shell. There are methods that can be used to control and execute commands within the Shell. There are also methods that can be used to obtain other Shell-related objects.

Properties

Property | Description
Count | The number of items in the collection.

Methods

Method | Description
Item | Retrieves an InternetExplorer object that represents the Shell window.
_NewEnum Method | Creates and returns a new ShellWindows object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellWindows.Count

Count Property

Description

Contains the number of items in the collection. This is a read-only property.

Syntax

object.Count

Parameter | Description
object | Required. An object expression that evaluates to a ShellWindows object.

See Also

ShellWindows

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellWindows.Item

Item Method

Description

Retrieves an InternetExplorer object that represents the Shell window.

Syntax

object.Item [index]

Parameter | Description
object | Required. An object expression that evaluates to a ShellWindows object.
index | Optional. Specifies the zero-based index of the item to retrieve. This value must be less than the value of the Count property.

See Also

ShellWindows

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


ShellWindows._NewEnum Method

_NewEnum

Description

Creates and returns a new ShellWindows object that is a copy of this ShellWindows object.

Syntax

object._NewEnum

Parameter | Description
object | Required. An object expression that evaluates to a ShellWindows object.

See Also

ShellWindows

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in exdisp.h.


Web View Scripting Objects

WebViewFolderContents

The WebViewFolderContents object is implemented by the Shell for use inside a WebView. WebViewFolderContents automatically initializes itself to WebView's current folder. It creates a Shell folder view that displays the contents of the folder in one of five formats: Small Icon, Large Icon, List, Details, or Thumbnail. It is not valid outside of a WebView.


WebViewFolderContents

WebViewFolderContents Object

The WebViewFolderContents object is implemented by the Shell for use inside a WebView. WebViewFolderContents automatically initializes itself to WebView's current folder. It creates a Shell folder view that displays the contents of the folder in one of five formats: Small Icon, Large Icon, List, Details, or Thumbnail. It is not valid outside of a WebView.

The methods and properties exposed by WebViewFolderContents are identical to those of the ShellFolderView object.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in shldisp.h.


APPBARDATA

Contains information about a system appbar message. This structure is used with the SHAppBarMessage function.

typedef struct _AppBarData {
    DWORD  cbSize;
    HWND   hWnd;
    UINT   uCallbackMessage;
    UINT   uEdge;
    RECT   rc;
    LPARAM lParam;
} APPBARDATA, *PAPPBARDATA;

Members

cbSize
Contains the size of the structure, in bytes.
hWnd
Contains the handle to the appbar window.
uCallbackMessage
Application-defined message identifier. The application uses the specified identifier for notification messages that it sends to the appbar identified by the hWnd member. This member is used when sending the ABM_NEW message.
uEdge
Value that specifies an edge of the screen. This member can be one of the following values:
ABE_BOTTOM | Bottom edge.
ABE_LEFT | Left edge.
ABE_RIGHT | Right edge.
ABE_TOP | Top edge.

This member is used when sending the ABM_GETAUTOHIDEBAR, ABM_QUERYPOS, ABM_SETAUTOHIDEBAR, and ABM_SETPOS messages.

rc
RECT structure to contain the bounding rectangle, in screen coordinates, of an appbar or the Windows taskbar. This member is used when sending the ABM_GETTASKBARPOS, ABM_QUERYPOS, and ABM_SETPOS messages.
lParam
Message-dependent value. This member is used with the ABM_SETAUTOHIDEBAR and ABM_SETSTATE messages.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


APPCATEGORYINFO Structure

This is preliminary documentation and is subject to change.

Provides application category information to Add/Remove Programs in Control Panel. The APPCATEGORYINFOLIST structure is used create a complete list of categories for an application publisher.

Syntax

typedef struct {
    LCID Locale;
    LPWSTR pszDescription;
    GUID AppCategoryID;
} APPCATEGORYINFO;

Members

Locale
A locale identification flag.
pszDescription
Pointer to a string containing a description of the category.
AppCategoryID
Globally unique identifier (GUID) identifying the application category.

Structure Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IAppPublisher::GetCategories, APPCATEGORYINFOLIST


APPCATEGORYINFOLIST Structure

This is preliminary documentation and is subject to change.

Provides a list of supported application categories from an application publisher to Add/Remove Programs in Control Panel.

Syntax

typedef struct {
    DWORD cCategory;
    APPCATEGORYINFO *pCategoryInfo;
} APPCATEGORYINFOLIST;

Members

cCategory
Value of type DWORD that specifies the count of APPCATEGORYINFO elements in the array pointed to by pCategoryInfo.
pCategoryInfo
Pointer to an array of APPCATEGORYINFO structures. This array contains all the categories an application publisher supports and must be allocated with the Shell task allocator (cf. SHGetMalloc).

Structure Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IAppPublisher::GetCategories, APPCATEGORYINFO


APPINFODATA Structure

This is preliminary documentation and is subject to change.

Provides a list of supported application categories from an application publisher to Add/Remove Programs in Control Panel.

Syntax

typedef struct {
    DWORD cbSize;
    DWORD dwMask;
    LPWSTR pszDisplayName;
    LPWSTR pszVersion;
    LPWSTR pszProductID;
    LPWSTR pszRegisteredOwner;
    LPWSTR pszRegisteredCompany;
    LPWSTR pszLanguage;
    LPWSTR pszSupportUrl;
    LPWSTR pszLanguage;
    LPWSTR pszSupportTelephone;
    LPWSTR pszHelpLink;
    LPWSTR pszInstallLocation;
    LPWSTR pszInstallSource;
    LPWSTR pszInstallDate;
    LPWSTR pszContact;
    LPWSTR pszComments;
    LPWSTR pszImage;
    LPWSTR pszReadmeUrl;
    LPWSTR pszUpdateInfoUrl;
} APPINFODATA;

Members

cbSize
Value of type DWORD that specifies the size of the APPINFODATA data structure. This field is set by the Add/Remove Program executable code.
dwMask
Value of type DWORD that specifies the bit mask indicating which items in the structure are desired or valid. Implementations of IShellApp::GetAppInfo should inspect this value for bits that are set and attempt to provide values corresponding to those bits. Implementations should also return with bits set for only those members that are being returned.
pszDisplayName
Pointer to a string containing the application display name.
pszVersion
Not applicable to published applications.
pszProductID
Not applicable to published applications.
pszRegisteredOwner
Not applicable to published applications.
pszRegisteredCompany
Not applicable to published applications.
pszLanguage
Not applicable to published applications.
pszSupportUrl
URL to support information. This string is displayed as a link with the application name in Control Panel Add/Remove Programs.
pszLanguage
Not applicable to published applications.
pszSupportTelephone
Not applicable to published applications.
pszHelpLink
Not applicable to published applications.
pszInstallLocation
Not applicable to published applications.
pszInstallSource
Not applicable to published applications.
pszInstallDate
Not applicable to published applications.
pszContact
Not applicable to published applications.
pszComments
Not applicable to published applications.
pszImage
Not applicable to published applications.
pszReadmeUrl
Not applicable to published applications.
pszUpdateInfoUrl
Not applicable to published applications.

Structure Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IAppPublisher, IPublishedApp::GetPublishedAppInfo


BROWSEINFO

Contains parameters for the SHBrowseForFolder function and receives information about the folder selected by the user.

typedef struct _browseinfo {
    HWND hwndOwner;
    LPCITEMIDLIST pidlRoot;
    LPTSTR pszDisplayName;
    LPCTSTR lpszTitle;
    UINT ulFlags;
    BFFCALLBACK lpfn;
    LPARAM lParam;
    int iImage;
} BROWSEINFO, *PBROWSEINFO, *LPBROWSEINFO;

Members

hwndOwner
Handle to the owner window for the dialog box.
pidlRoot
Pointer to an ITEMIDLIST structure (PIDL) specifying the location of the root folder from which to start browsing. Only the specified folder and any subfolders that are beneath it in the namespace hierarchy will appear in the dialog box. This member can be NULL; in that case, the namespace root (the desktop folder) is used.
pszDisplayName
Address of a buffer to receive the display name of the folder selected by the user. The size of this buffer is assumed to be MAX_PATH bytes.
lpszTitle
Address of a null-terminated string that is displayed above the tree view control in the dialog box. This string can be used to specify instructions to the user.
ulFlags
Flags specifying the options for the dialog box. This member can include zero or a combination of the following values:
BIF_BROWSEFORCOMPUTER | Only return computers. If the user selects anything other than a computer, the OK button is grayed.
BIF_BROWSEFORPRINTER | Only return printers. If the user selects anything other than a printer, the OK button is grayed.
BIF_BROWSEINCLUDEFILES | Version 4.71. The browse dialog box will display files as well as folders.
BIF_BROWSEINCLUDEURLS | Version 5.0. The browse dialog box can display URLs. The BIF_USENEWUI and BIF_BROWSEINCLUDEFILES flags must also be set. If these three flags are not set, the browser dialog box will reject URLs. Even when these flags are set, the browse dialog box will only display URLs if the folder that contains the selected item supports them. When the folder's IShellFolder::GetAttributesOf method is called to request the selected item's attributes, the folder must set the SFGAO_FOLDER attribute flag. Otherwise, the browse dialog box will not display the URL.
BIF_DONTGOBELOWDOMAIN | Do not include network folders below the domain level in the dialog box's tree view control.
BIF_EDITBOX | Version 4.71. Include an edit control in the browse dialog box that allows the user to type the name of an item.
BIF_NEWDIALOGSTYLE | Version 5.0. Use the new user interface. Setting this flag provides the user with a larger dialog box that can be resized. The dialog box has several new capabilities including: drag and drop capability within the dialog box, reordering, shortcut menus, new folders, delete, and other shortcut menu commands. To use this flag, you must call OleInitialize or CoInitialize before calling SHBrowseForFolder.
BIF_RETURNFSANCESTORS | Only return file system ancestors. An ancestor is a subfolder that is beneath the root folder in the namespace hierarchy. If the user selects an ancestor of the root folder that is not part of the file system, the OK button is grayed.
BIF_RETURNONLYFSDIRS | Only return file system directories. If the user selects folders that are not part of the file system, the OK button is grayed.
BIF_SHAREABLE | Version 5.0. The browse dialog box can display shareable resources on remote systems. It is intended for applications that want to expose remote shares on a local system. The BIF_USENEWUI flag must also be set.
BIF_STATUSTEXT | Include a status area in the dialog box. The callback function can set the status text by sending messages to the dialog box.
BIF_USENEWUI | Version 5.0. Use the new user interface, including an edit box. This flag is equivalent to BIF_EDITBOX | BIF_NEWDIALOGSTYLE. To use BIF_USENEWUI, you must call OleInitialize or CoInitialize before calling SHBrowseForFolder.
BIF_VALIDATE | Version 4.71. If the user types an invalid name into the edit box, the browse dialog box will call the application's BrowseCallbackProc with the BFFM_VALIDATEFAILED message. This flag is ignored if BIF_EDITBOX is not specified.
lpfn
Address of an application-defined function that the dialog box calls when an event occurs. For more information, see the BrowseCallbackProc function. This member can be NULL.
lParam
Application-defined value that the dialog box passes to the callback function, if one is specified.
iImage
Variable to receive the image associated with the selected folder. The image is specified as an index to the system image list.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


CATEGORY_INFO Structure

This is preliminary documentation and is subject to change.

Contains category information. A component category is a group of logically-related COM classes that share a common category ID or CATID.

Syntax

typedef struct {
    CATEGORYINFO_FLAGS cif;
    WCHAR wszName[260];
} CATEGORY_INFO;

Members

cif
Flag from CATEGORYINFO_FLAGS that specifies the type of information to retrieve.
wszName
Character array that specifies the name of the category.

Structure Information

Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


CIDA

This structure is used with the CFSTR_SHELLIDLIST clipboard format to transfer the PIDLs of one or more Shell namespace objects.

typedef struct _IDA {
    UINT cidl;
    UINT aoffset[1];
} CIDA, * LPIDA;

Members

cidl
Number PIDLs that are being transferred, not counting the parent folder.
aoffset
An array of offsets, relative to the beginning of this structure. The array contains cidl+1 elements. The first element of aoffset contains an offset to the fully-qualified PIDL of a parent folder. If this PIDL is empty, the parent folder is the desktop. Each of the remaining elements of the array contains an offset to one of the PIDLs to be transferred. All of these PIDLs are relative to the PIDL of the parent folder.

Remarks

To use this structure to retrieve a particular PIDL, add the PIDLs aoffset value to the address of the structure. The following two macros can be used to retrive PIDLs from the structure. The first retrieves the PIDL of the parent folder. The second retrieves a PIDL, specified by its zero-based index.

#define HIDA_GetPIDLFolder(pida) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[0])
#define HIDA_GetPIDLItem(pida, i) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[i+1])

The value that is returned by these macros is a pointer to the PIDL's ITEMIDLIST structure. Since these structures vary in length, you must determine the end of the structure by parsing it. See The Shell Namespace for further discussion of PIDLs and the ITEMIDLIST structure

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


CMINVOKECOMMANDINFO

Contains information needed by IContextMenu::InvokeCommand to invoke a shortcut menu command.

typedef struct _CMInvokeCommandInfo{
    DWORD cbSize;
    DWORD fMask;
    HWND hwnd;
    LPCSTR lpVerb;
    LPCSTR lpParameters;
    LPCSTR lpDirectory;
    int nShow;
    DWORD dwHotKey;
    HANDLE hIcon;
} CMINVOKECOMMANDINFO, *LPCMINVOKECOMMANDINFO;

Members

cbSize
Contains the size of this structure, in bytes.
fMask

Zero, or one or more of the following flags:

CMIC_MASK_ASYNCOK | Wait for the DDE conversation to terminate before returning.
CMIC_MASK_FLAG_NO_UI | The system is prevented from displaying user interface elements (for example, error messages) while carrying out a command.
CMIC_MASK_HOTKEY | The dwHotKey member is valid.
CMIC_MASK_ICON | The hIcon member is valid.
CMIC_MASK_NO_CONSOLE | If a shortcut menu handler needs to create a new process, it will normally create a new console. Setting the CMIC_MASK_NO_CONSOLE flag suppresses the creation of a new console.
hwnd
Handle to the window that is the owner of the shortcut menu. An extension can also use this handle as the owner of any message boxes or dialog boxes it displays.
lpVerb
32-bit value that contains zero in the high-order word and a menu-identifier offset of the command to carry out in the low-order word. The Shell specifies this value (using the MAKEINTRESOURCE macro) when the user chooses a menu command.

If the high-order word is not zero, this member is the address of a null-terminated string specifying the language-independent name of the command to carry out. This member is typically a string when a command is being activated by an application. The system provides predefined constant values for the following command strings.

Value | String
CMDSTR_NEWFOLDER | "NewFolder"
CMDSTR_VIEWDETAILS | "ViewDetails"
CMDSTR_VIEWLIST | "ViewList"
lpParameters
Optional string containing parameters that are passed to the command. The format of this string is determined by the command that is to be invoked. This member is always NULL for menu items inserted by a Shell extension.
lpDirectory
Optional working directory name. This member is always NULL for menu items inserted by a Shell extension.
nShow
Set of SW_ values to pass to the ShowWindow function if the command displays a window or starts an application.
dwHotKey
Optional hot key to assign to any application activated by the command. If the fMask parameter does not specify CMIC_MASK_HOTKEY, this member is ignored.
hIcon
Icon to use for any application activated by the command. If the fMask member does not specify CMIC_MASK_ICON, this member is ignored.

Remarks

Although the IContextMenu::InvokeCommand declaration specifies a CMINVOKECOMMANDINFO structure for the pici parameter, it can also accept a CMINVOKECOMMANDINFOEX structure. If you are implementing this method, you must inspect cbSize to determine which structure has been passed.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


CMINVOKECOMMANDINFOEX

Contains extended information about a shortcut menu command. This structure is an extended version of CMINVOKECOMMANDINFO that allows the use of Unicode values.

typedef struct _CMInvokeCommandInfoEx {
    DWORD cbSize;
    DWORD fMask;
    HWND hwnd;
    LPCSTR lpVerb;
    LPCSTR lpParameters;
    LPCSTR lpDirectory;
    int nShow;
    DWORD dwHotKey;
    HANDLE hIcon;
    LPCSTR lpTitle;
    LPCWSTR lpVerbW;
    LPCWSTR lpParametersW;
    LPCWSTR lpDirectoryW;
    LPCWSTR lpTitleW;
    POINT ptInvoke;
} CMINVOKECOMMANDINFOEX,  *LPCMINVOKECOMMANDINFOEX;

Members

cbSize
Contains the size of this structure, in bytes.
fMask
Zero, or one or more of the following flags:
CMIC_MASK_HOTKEY | The dwHotKey member is valid.
CMIC_MASK_ICON | The hIcon member is valid.
CMIC_MASK_FLAG_NO_UI | The system is prevented from displaying user interface elements (for example, error messages) while carrying out a command.
CMIC_MASK_NO_CONSOLE | If a shortcut menu handler needs to create a new process, it will normally create a new console. Setting the CMIC_MASK_NO_CONSOLE flag suppresses the creation of a new console.
CMIC_MASK_UNICODE | Indicates that the shortcut menu handler should use lpVerbW, lpParametersW, lpDirectoryW, and lpTitleW members instead of their ANSI equivalents. Because some shortcut menu handlers may not support Unicode, you should also pass valid ANSI strings in the lpVerb, lpParameters, lpDirectory, and lpTitle members.
hwnd
Handle to the window that is the owner of the shortcut menu. An extension can also use this handle as the owner of any message boxes or dialog boxes it displays.
lpVerb
32-bit value that contains zero in the high-order word and a menu-identifier offset of the command to carry out in the low-order word. The Shell specifies this value (using the MAKEINTRESOURCE macro) when the user chooses a menu command.

If the high-order word is not zero, this member is the address of a null-terminated string specifying the language-independent name of the command to carry out. This member is typically a string when a command is being activated by an application. The system provides predefined constant values for the following command strings.

Value | String
CMDSTR_NEWFOLDER | "NewFolder"
CMDSTR_VIEWDETAILS | "ViewDetails"
CMDSTR_VIEWLIST | "ViewList"
lpParameters
Optional parameters. This member is always NULL for menu items inserted by a Shell extension.
lpDirectory
Optional working directory name. This member is always NULL for menu items inserted by a Shell extension.
nShow
Set of SW_ values to pass to the ShowWindow function if the command displays a window or starts an application.
dwHotKey
Optional hot key to assign to any application activated by the command. If the fMask parameter does not specify CMIC_MASK_HOTKEY, this member is ignored.
hIcon
Icon to use for any application activated by the command. If the fMask member does not specify CMIC_MASK_ICON, this member is ignored.
lpTitle
ASCII title.
lpVerbW
Unicode verb, for those commands that can use it.
lpParametersW
Unicode parameters, for those commands that can use it.
lpDirectoryW
Unicode directory, for those commands that can use it.
lpTitleW
Unicode title.
ptInvoke
Point where the command is invoked. This member is not valid prior to Internet Explorer 4.0.

Remarks

Although the IContextMenu::InvokeCommand declaration specifies a CMINVOKECOMMANDINFO structure for the pici parameter, it can also accept a CMINVOKECOMMANDINFOEX structure. If you are implementing this method, you must inspect cbSize to determine which structure has been passed.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


COMPONENT

Used by Microsoft® Windows 2000 to hold information about a component. This structure replaces the IE4COMPONENT structure.

typedef struct _tagCOMPONENT
{
    DWORD dwSize;
    DWORD dwID;
    int iComponentType;
    BOOL fChecked;
    BOOL fDirty;
    BOOL fNoScroll;
    COMPPOS cpPos;
    WCHAR wszFriendlyName[MAX_PATH];
    WCHAR wszSource[INTERNET_MAX_URL_LENGTH];
    WCHAR wszSubscribedURL[INTERNET_MAX_URL_LENGTH];
    DWORD dwCurItemState;
    COMPSTATEINFO csiOriginal;
    COMPSTATEINFO csiRestored;
}
COMPONENT, *LPCOMPONENT;

Members

dwSize
Size of the structure.
dwID
Reserved. Set to zero.
iComponentType
Component type. It can take one of the following values:
Value | Description
COMP_TYPE_HTMLDOC | HTML document
COMP_TYPE_PICTURE | Picture
COMP_TYPE_WEBSITE | Web site
COMP_TYPE_CONTROL | Active X Control. This value is valid only for IActiveDesktop::AddDesktopItem.
fChecked
Value that is set to TRUE if the component is enabled, or FALSE if it's not.
fDirty
Value that is set to TRUE if the component has been modified and not yet saved to disk. It will be set to FALSE if the component has not been modified, or if it has been modified and saved to disk.
fNoScroll
Value that is set to TRUE if the component is scrollable, or FALSE if not.
cpPos
COMPPOS structure containing position and size information.
wszFriendlyName
Component's friendly name.
wszSource
Component's URL.
wszSubscribed
Subscribed URL.
dwCurItemState
Current state of the component. It can take one of the following values:
Value | Description
IS_NORMAL | Normal screen
IS_FULLSCREEN | Full screen
IS_SPLIT | Split screen
csiOriginal
COMPSTATEINFO structure with the state of the component when it was first added.
csiRestored
COMPSTATEINFO structure with the restored state of the component.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


COMPONENTSOPT

Contains the desktop item options.

typedef struct _tagCOMPONENTSOPT {
    DWORD dwSize;
    BOOL fEnableComponents;
    BOOL fActiveDesktop;
} COMPONENTSOPT;

Members

dwSize
Unsigned long integer value that contains the size of the structure.
fEnableComponents
Boolean value that determines if desktop items are enabled.
fActiveDesktop
Boolean value that determines if the Active Desktop is enabled.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


COMPPOS

This structure holds information about a component's position and size.

typedef struct _tagCOMPPOS
{
    DWORD	dwSize;
    int	iLeft;
    int	iTop;
    DWORD	dwWidth;
    DWORD	dwHeight;
    int	izIndex;
    BOOL	fCanResize;
    BOOL	fCanResizeX;
    BOOL	fCanResizeY;
    int	iPreferredLeftPercent;
    int     iPreferredTopPercent;
}
COMPPOS, *LPCOMPPOS;

Members

dwSize
The size of the structure.
iLeft
The left edge of the top-left corner in screen co-ordinates.
iTop
The top of the top-left corner in screen co-ordinates.
dwWidth
The width, in pixels.
dwHeight
The height, in pixels.
izIndex
The Z-Order of the component.
fCanResize
Set to TRUE if the component is resizable, FALSE if not.
fCanResizeX
Set to TRUE if the component is resizablein the X-direction, FALSE if not.
fCanResizeY
Set to TRUE if the component is resizablein the Y-direction, FALSE if not.
iPreferredLeftPercent
The left edge of the upper-left corner as a percentage of screen width.
iPreferredTopPercent
The top of the upper-left corner as a percentage of screen width.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


COMPSTATEINFO

Used by Microsoft® Windows 2000 to hold information about a component's state.

typedef struct  _tagCOMPSTATEINFO
{
    DWORD dwSize;
    int iLeft;
    int iTop;
    DWORD dwWidth;
    DWORD dwHeight;
    DWORD dwItemState;
}
COMPSTATEINFO, *LPCOMPSTATEINFO;

Members

dwSize
Size of the structure.
iLeft
Left edge of the top-left corner in screen coordinates.
iTop
Top of the top-left corner in screen coordinates.
dwWidth
Width, in pixels.
dwHeight
Height, in pixels.
dwItemState
State of the component:
IS_NORMAL | Normal screen
IS_FULLSCREEN | Full screen
IS_SPLIT | Split screen

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


CPLINFO

Contains resource information and an application-defined value for a dialog box supported by a Control Panel application. The CPlApplet function of the Control Panel application returns this information to the Control Panel in response to a CPL_INQUIRE message.

typedef struct tagCPLINFO {
    int  idIcon;
    int  idName;
    int  idInfo;
    LONG lData;
} CPLINFO;

Members

idIcon
Resource identifier of the icon that represents the dialog box.
idName
Resource identifier of the string containing the short name for the dialog box. This name is intended to be displayed below the icon.
idInfo
Resource identifier of the string containing the description for the dialog box that is intended to be displayed when the application icon is selected.
lData
Data defined by the application. When the Control Panel sends the CPL_DBLCLK and CPL_STOP messages, it passes this value back to your application.

Remarks

If the icon or display strings of the dialog box can change based on the state of the computer, you can specify the CPL_DYNAMIC_RES value for the idIcon, idName, or idInfo members rather than specifying a valid resource identifier. This causes the Control Panel to send the CPL_NEWINQUIRE message each time it needs the icon and display strings. Using this technique is significantly slower, however, because the Control Panel will need to load your application each time it sends the CPL_NEWINQUIRE message.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


DATABLOCK_HEADER

Serves as the header for some of the extra data structures used by IShellLinkDataList.

typedef struct tagDATABLOCKHEADER
{
    DWORD cbSize;
    DWORD dwSignature;
} DATABLOCK_HEADER, *LPDATABLOCK_HEADER, *LPDBLIST;

Members

cbSize
Size of the extra data block.
dwSignature
Signature that identifies the type of data block that follows the header.

See Also

EXP_DARWIN_LINK, NT_CONSOLE_PROPS, NT_FE_CONSOLE_PROPS

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


DESKBANDINFO

Contains and receives information for a band object. This structure is used with the IDeskBand::GetBandInfo method.

typedef struct {
    DWORD dwMask;
    POINTL ptMinSize;
    POINTL ptMaxSize;
    POINTL ptIntegral;
    POINTL ptActual;
    WCHAR wszTitle[256];
    DWORD dwModeFlags;
    COLORREF crBkgnd;
} DESKBANDINFO;

Members

dwMask
Set of flags that determine which members of this structure are being requested. This will be a combination of the following values:
DBIM_MINSIZE | ptMinSize is being requested.
DBIM_MAXSIZE | ptMaxSize is being requested.
DBIM_INTEGRAL | ptIntegral is being requested.
DBIM_ACTUAL | ptActual is being requested.
DBIM_TITLE | wszTitle is being requested.
DBIM_MODEFLAGS | dwModeFlags is being requested.
DBIM_BKCOLOR | crBkgnd is being requested.
ptMinSize
POINTL structure that receives the minimum size of the band object. The minimum width is placed in the x member and the minimum height is placed in the y member.
ptMaxSize
POINTL structure that receives the maximum size of the band object. The maximum height is placed in the y member and the x member is ignored. If there is no limit for the maximum height, (LONG)-1 should be used.
ptIntegral
POINTL structure that receives the sizing step value of the band object. The vertical step value is placed in the y member, and the x member is ignored. The step value determines in what increments the band will be resized. This member is ignored if dwModeFlags does not contain DBIMF_VARIABLEHEIGHT.
ptActual
POINTL structure that receives the ideal size of the band object. The ideal width is placed in the x member and the ideal height is placed in the y member. The band container will attempt to use these values, but the band is not guaranteed to be this size.
wszTitle
WCHAR buffer that receives the title of the band.
dwModeFlags
A value that receives a set of flags that define the mode of operation for the band object. This must be one or a combination of the following values:
DBIMF_NORMAL | The band is normal in all respects. The other mode flags modify this flag.
DBIMF_VARIABLEHEIGHT | The height of the band object can be changed. The ptIntegral member defines the step value by which the band object can be resized.
DBIMF_DEBOSSED | The band object is displayed with a sunken appearance.
DBIMF_BKCOLOR | The band will be displayed with the background color specified in crBkgnd.
crBkgnd
A value that eceives the background color of the band. This member is ignored if dwModeFlags does not contain the DBIMF_BKCOLOR flag.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


DLLVERSIONINFO

Receives DLL-specific version information. It is used with the DllGetVersion function.

typedef struct _DllVersionInfo
{
    DWORD cbSize;
    DWORD dwMajorVersion;
    DWORD dwMinorVersion;
    DWORD dwBuildNumber;
    DWORD dwPlatformID;
}DLLVERSIONINFO;

Members

cbSize
Size of the structure, in bytes. This member must be filled in before calling the function.
dwMajorVersion
Major version of the DLL. If the DLL's version is 4.0.950, this value will be 4.
dwMinorVersion
Minor version of the DLL. If the DLL's version is 4.0.950, this value will be 0.
dwBuildNumber
Build number of the DLL. If the DLL's version is 4.0.950, this value will be 950.
dwPlatformID
Identifies the platform for which the DLL was built. This can be one of the following values:
DLLVER_PLATFORM_WINDOWS | The DLL was built for all Windows platforms.
DLLVER_PLATFORM_NT | The DLL was built specifically for Windows NT.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlwapi.h.


DLLVERSIONINFO2

Receives DLL-specific version information. It is used with the DllGetVersion function.

typedef struct _DLLVERSIONINFO2
{
    DLLVERSIONINFO info1;
    DWORD dwFlags;
    ULONGLONG ullVersion;
}DLLVERSIONINFO2;

Members

info1
DLLVERSIONINFO structure. This member is included to provide backward compatibility with applications that are not expecting a DLLVERSIONINFO2 structure.
dwFlags
Reserved.
ullVersion
Value that contains the version information. It is divided into four 16-bit fields containing the major and minor version numbers, the build number, and the QFE version, in that order. Use the MAKEDLLVERULL macro to construct this value.

Remarks

Your application must set the cbSize member of the structure pointed to by info1 to sizeof(DLLGETVERSIONINFO2) before calling DllGetVersion. Otherwise, no value will be assigned to the dwFlags or ullVersion member of the DLLGETVERSIONINFO2 structure.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlwapi.h.


DROPFILES

Defines the CF_HDROP and CF_PRINTERS clipboard formats. In the CF_HDROP case, the data that follows is a double null-terminated list of file names. For CF_PRINTERS, the data that follows are the printer friendly names.

typedef struct _DROPFILES {
    DWORD pFiles;
    POINT pt;
    BOOL fNC;
    BOOL fWide;
} DROPFILES, FAR * LPDROPFILES;

Members

pFiles
Offset of the file list from the beginning of this structure, in bytes.
pt
Drop point. The coordinates depend on fNC.
fNC
Nonclient area flag. If this member is TRUE, pt specifies the screen coordinates of a point in a window's nonclient area. If it is FALSE, pt specifies the client coordinates of a point in the client area.
fWide
Value that indicates whether the file contains ANSI or Unicode characters. If the value is zero, the file contains ANSI characters. Otherwise, it contains Unicode characters.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


EXP_DARWIN_LINK

Holds an extra data block used by IShellLinkDataList. It holds the link's Windows® Installer ID.

typedef struct {
    DATABLOCK_HEADER dbh;
    CHAR        szDarwinID[MAX_PATH];
    WCHAR       szwDarwinID[MAX_PATH];
} EXP_DARWIN_LINK, *LPEXP_DARWIN_LINK;

Members

dbh
DATABLOCK_HEADER structure with the EXP_DARWIN_LINK structure's size and signature. There are two available signatures.
EXP_DARWIN_ID_SIG | Contains a Windows Installer ID.
EXP_LOGO3_ID_SIG | Not currently supported.
szDarwinID
ANSI string with the the link's ID.
szwDarwinID
Unicode string with the link's ID.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


EXP_SPECIAL_FOLDER

Holds an extra data block used by IShellLinkDataList. It holds special folder information.

typedef struct
{
    DWORD cbSize;
    DWORD dwSignature;
    DWORD idSpecialFolder;
    DWORD cbOffset;
} EXP_SPECIAL_FOLDER, *LPEXP_SPECIAL_FOLDER;

Members

cbSize
Size of the EXP_SPECIAL_FOLDER structure.
dwSignature
Structure's signature. It should be set to EXP_SPECIAL_FOLDER_SIG.
idSpecialFolder
ID of the special folder that the link points into.
cbOffset
Offset into the saved PIDL.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


EXP_SZ_LINK

Holds an extra data block used by IShellLinkDataList. It holds expandable environment strings for the icon or target.

typedef struct
{
    DWORD       cbSize;
    DWORD       dwSignature;
    CHAR        szTarget[ MAX_PATH ];
    WCHAR       swzTarget[ MAX_PATH ];
} EXP_SZ_LINK, *LPEXP_SZ_LINK;

Members

cbSize
Size of the EXP_SZ_LINK structure.
dwSignature
Structure's signature. It can have one of the following values.
EXP_SZ_LINK_SIG | Contains the link's target path.
EXP_SZ_ICON_SIG | Contains the links icon path.
szTarget
NULL-terminated ANSI string with the path of the target or icon.
swzTarget
NULL-terminated Unicode string with the path of the target or icon.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


EXT_BUTTON

Contains information about a button that a File Manager extension dynamic-link library is adding to the toolbar of File Manager.

typedef struct _EXT_BUTTON {
    WORD idCommand;
    WORD idsHelp;
    WORD fsStyle;
} EXT_BUTTON;

Members

idCommand
Command identifier for the button.
idsHelp
Identifier of the Help string for the button.
fsStyle
Style of the button.

See Also

FMEVENT_TOOLBARLOAD, FMS_TOOLBARLOAD

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


EXTRASEARCH

Used by an IEnumExtraSearch enumerator object to return information on the search objects supported by a Shell Folder object.

typedef struct tagEXTRASEARCH
{
    GUID    guidSearch;
    WCHAR   wszFriendlyName[80];
    WCHAR   wszUrl[2084];
}EXTRASEARCH, *LPEXTRASEARCH;

Members

guidSearch
Search object's globally unique identifier (GUID).
wszFriendlyName
A Unicode string containing the search object's friendly name. It will be used to identify the search engine on the Search Assistant menu.
wszUrl
The URL that will be displayed in the search pane.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


FILEDESCRIPTOR

Describes the properties of a file that is being copied by means of the clipboard during an OLE drag-and-drop operation.

typedef struct _FILEDESCRIPTOR {
    DWORD    dwFlags;
    CLSID    clsid;
    SIZEL    sizel;
    POINTL   pointl;
    DWORD    dwFileAttributes;
    FILETIME ftCreationTime;
    FILETIME ftLastAccessTime;
    FILETIME ftLastWriteTime;
    DWORD    nFileSizeHigh;
    DWORD    nFileSizeLow;
    TCHAR    cFileName[MAX_PATH];
} FILEDESCRIPTOR, *LPFILEDESCRIPTOR;

Members

dwFlags
Array of flags that indicate which of the other structure members contain valid data. This member can be a combination of the following values:
Flag | Description
FD_ACCESSTIME | The ftLastAccessTime member is valid.
FD_ATTRIBUTES | The dwFileAttributes member is valid.
FD_CLSID | The clsid member is valid.
FD_CREATETIME | The ftCreationTime member is valid.
FD_FILESIZE | The nFileSizeHigh and nFileSizeLow members are valid.
FD_LINKUI | Treat the operation as "Link."
FD_SIZEPOINT | The sizel and pointl members are valid.
FD_WRITESTIME | The ftLastWriteTime member is valid.
clsid
File class identifier.
sizel
Width and height of the file icon.
pointl
Screen coordinates of the file object.
dwFileAttributes
File attribute flags. This will be a combination of the FILE_ATTRIBUTE_ values described in GetFileAttributes.
ftCreationTime
FILETIME structure that contains the time of file creation.
ftLastAccessTime
FILETIME structure that contains the time that the file was last accessed.
ftLastWriteTime
FILETIME structure that contains the time of the last write operation.
nFileSizeHigh
High-order DWORD of the file size, in bytes.
nFileSizeLow
Low-order DWORD of the file size, in bytes.
cFileName
Null-terminated string that contains the name of the file.

Remarks

If the CFSTR_FILECONTENTS format that corresponds to this structure contains the file as a global memory object, nFileSizeHigh and nFileSizeLow specify the size of the associated memory block. If they are set, they can also be used if a user-interface needs to be displayed. For instance, if a file is about to be overwritten, you would normally use information from this structure to display a dialog box containing the size, data, and name of the file.

To create a zero-length file, set the FD_FILESIZE flag in the dwFlags member, and set nFileSizeHigh and nFileSizeLow to zero. The CFSTR_FILECONTENTS format should represent the file as either a stream or global memory object (TYMED_ISTREAM or TYMED_HGLOBAL).

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


FILEGROUPDESCRIPTOR

Defines the CF_FILEGROUPDESCRIPTOR clipboard format.

typedef struct _FILEGROUPDESCRIPTOR {
    UINT cItems;
    FILEDESCRIPTOR fgd[1];
} FILEGROUPDESCRIPTOR, * LPFILEGROUPDESCRIPTOR;

Members

cItems
Number of elements in fgd.
fgd
Array of FILEDESCRIPTOR structures that contain the file information.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


FMS_GETDRIVEINFO

Contains information about the drive selected in the active File Manager window (the directory window or the Search Results window).

typedef struct _FMS_GETDRIVEINFO {
    DWORD dwTotalSpace;
    DWORD dwFreeSpace;
    TCHAR  szPath[260];
    TCHAR  szVolume[14];
    TCHAR  szShare[128];
} FMS_GETDRIVEINFO;

Members

dwTotalSpace
Total amount of storage space, in bytes, on the disk associated with the drive.
dwFreeSpace
Amount of free storage space, in bytes, on the disk associated with the drive.
szPath
Null-terminated path of the current directory.
szVolume
Null-terminated volume label of the disk associated with the drive.
szShare
Null-terminated name of the network resource (if the drive is being accessed through a network).

See Also

FMExtensionProc, FM_GETDRIVEINFO

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMS_GETFILESEL

Contains information about a selected file in the active File Manager window (the directory window or the Search Results window).

typedef struct _FMS_GETFILESEL {
    FILETIME ftTime;
    DWORD    dwSize;
    BYTE     bAttr;
    TCHAR     szName[260];
} FMS_GETFILESEL;

Members

ftTime
Time and date the file was created.
dwSize
Size, in bytes, of the file.
bAttr
Attributes of the file.
szName
Null-terminated full path and file name of the selected file.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMS_HELPSTRING

Contains information that File Manager uses to add a Help string for a menu or toolbar command item.

typedef struct _FMS_HELPSTRING {
    INT  idCommand;
    HMENU hMenu;
    CHAR szHelp[128];
} FMS_HELPSTRING;

Members

idCommand
Identifier of the command item.
hMenu
Identifer of the menu bar.
szHelp
Null-terminated string that receives the Help text.

See Also

FMExtensionProc, FMEVENT_HELPMENUITEM

Requirements

Windows NT/2000: Requires Windows NT 3.5 or later.
Header: Declared in wfext.h.


FMS_LOAD

Contains information that File Manager uses to add a custom menu provided by a File Manager extension DLL. The structure also provides a delta value that the extension DLL can use to manipulate the custom menu after File Manager has loaded the menu.

typedef struct _FMS_LOAD {
    DWORD dwSize;
    TCHAR  szMenuName[MENU_TEXT_LEN];
    HMENU hMenu;
    UINT  wMenuDelta;
} FMS_LOAD;

Members

dwSize
Length, in bytes, of the structure.
szMenuName
Null-terminated name for a menu item that appears on the menu bar in File Manager.
hMenu
Identifer of the pop-up menu added to the menu bar in File Manager.
wMenuDelta
Menu item delta value. To avoid conflicts with its own menu items, File Manager renumbers the menu item identifiers in the pop-up menu identified by the hMenu member by adding this delta value to each identifier. An extension DLL that must modify a menu item must identify the item by adding the delta value to the menu item's identifier. The value of this member can vary from session to session.

See Also

FMExtensionProc

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FMS_TOOLBARLOAD

Contains information about custom buttons to be added to the File Manager toolbar. The buttons are provided by a File Manager extension DLL.

typedef struct _FMS_TOOLBARLOAD {
    DWORD        dwSize;
    LPEXT_BUTTON lpButtons;
    WORD         cButtons;
    WORD         cBitmaps;
    WORD         idBitmap;
    HBITMAP      hBitmap;
} FMS_TOOLBARLOAD;

Members

dwSize
Size, in bytes, of the structure. File Manager sets the size before calling the extension and checks the size after the extension procedure returns.
lpButtons
Address of an array of EXT_BUTTON structures.
cButtons
Number of EXT_BUTTON structures in the array pointed to by the lpButtons member. This number equals the number of buttons and separators to add to the toolbar.
cBitmaps
Number of buttons represented by the given bitmap.
idBitmap
Identifier of a bitmap resource in the executable file for the extension DLL. The bitmap resource contains images for the number of buttons specified by cBitmaps. File Manager loads the bitmap resource and then uses it to display the buttons.
hBitmap
Handle to a bitmap that File Manager will use to obtain and display button images if idBitmap is 0.

See Also

FMEVENT_TOOLBARLOAD

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Header: Declared in wfext.h.


FOLDERSETTINGS

Contains folder view information.

typedef struct {
    UINT     ViewMode;
    UINT     fFlags;
}FOLDERSETTINGS, *LPFOLDERSETTINGS;

Members

ViewMode
Folder view mode. This can be one of the FOLDERVIEWMODE values.
fFlags
Set of flags that indicate the options for the folder. This can be zero or a combination of the FOLDERFLAGS values.

Remarks

These settings assume a particular user interface, which the Shell's folder view has. A Shell extension can use these settings if they apply to the view implemented by the extension.

See Also

IShellView::CreateViewWindow, IShellView::GetCurrentInfo

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


FVSHOWINFO

Contains information that the file viewer uses to display a file.

typedef struct {
    DWORD cbSize;
    HWND hwndOwner;
    int iShow;
    DWORD dwFlags;
    RECT rect;
    LPUNKNOWN punkRel;
    OLECHAR strNewFile[MAX_PATH];
} FVSHOWINFO, *LPFVSHOWINFO;

Members

cbSize
Size of the structure, in bytes.
hwndOwner
Window handle to the owner of the window in which the file will be displayed.
iShow
Show command for the window. This parameter is one of the SW_ values detailed in ShowWindow.
dwFlags
Flags that determine what the file viewer displays. This member can be one or more of the following values:
FVSIF_CANVIEWIT | The file viewer can display the file.
FVSIF_NEWFAILED | The file viewer specified a new file to display, but no viewer could display the file. The file viewer should either continue to display the previous file or terminate.
FVSIF_NEWFILE | A drag-and-drop operation has dropped a file on the file viewer window. The file viewer passes the name of the file to the Shell by copying the name to the strNewFile member. The Shell attempts to load a file viewer that can display the new file.
FVSIF_PINNED | A pinned window exists. A file viewer should either use the pinned window to display the file or set a new pinned window and display the file in it.
FVSIF_RECT | The rect member contains valid data.
rect
RECT structure that specifies the size and position of the file viewer's window. This member is valid only if the dwFlags member includes the FVSIF_RECT value.
punkRel
Address of an interface that has its Release method called by a new file viewer to release the previous file viewer. This member is used when a drag-and-drop operation drops a file on the file viewer's window.
strNewFile
Address of a string that specifies the name of a new file to display. A file viewer sets this member when a drag-and-drop operation drops a file on the file viewer's window.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


HELPINFO

Contains information about an item for which context-sensitive Help has been requested.

typedef  struct  tagHELPINFO {
    UINT     cbSize;
    int      iContextType
    int      iCtrlId;
    HANDLE   hItemHandle;
    DWORD    dwContextId;
    POINT    MousePos;
} HELPINFO, FAR *LPHELPINFO;

Members

cbSize
Structure size, in bytes.
iContextType
Type of context for which Help is requested. This member can be one of the following values:
HELPINFO_MENUITEM | Help requested for a menu item.
HELPINFO_WINDOW | Help requested for a control or window.
iCtrlId
Identifier of the window or control if iContextType is HELPINFO_WINDOW, or identifier of the menu item if iContextType is HELPINFO_MENUITEM.
hItemHandle
Identifier of the child window or control if iContextType is HELPINFO_WINDOW, or identifier of the associated menu if iContextType is HELPINFO_MENUITEM.
dwContextId
Help context identifier of the window or control.
MousePos
POINT structure that contains the screen coordinates of the mouse cursor. This is useful for providing Help based on the position of the mouse cursor.

Requirements

Windows NT/2000: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.


HELPWININFO

Contains the size and position of either a primary or a secondary Help window. An application can set this information by calling the WinHelp function with the HELP_SETWINPOS value.

Syntax

typedef struct {
    int   wStructSize;
    int   x;
    int   y;
    int   dx;
    int   dy;
    int   wMax;
    TCHAR rgchMember[2];
} HELPWININFO;

Members

wStructSize
Structure size, in bytes.
x
X-coordinate of the upper-left corner of the window, in screen coordinates.
y
Y-coordinate of the upper-left corner of the window, in screen coordinates.
dx
Window width, in pixels.
dy
Window height, in pixels.
wMax
How to show the window. This member must be one of the following values:
SW_HIDE | Hides the window and passes activation to another window.
SW_MINIMIZE | Minimizes the specified window and activates the top-level window in the z-order.
SW_RESTORE | Same as SW_SHOWNORMAL.
SW_SHOW | Activates a window and displays it in its current size and position.
SW_SHOWMAXIMIZED | Activates the window and displays it as a maximized window.
SW_SHOWMINIMIZED | Activates the window and displays it as an icon.
SW_SHOWMINNOACTIVE | Displays the window as an icon. The window that is currently active remains active.
SW_SHOWNA | Displays the window in its current state. The window that is currently active remains active.
SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The window that is currently active remains active.
SW_SHOWNORMAL | Activates and displays the window. Whether the window is minimized or maximized, Windows restores it to its original size and position.
rgchMember
Name of the window.

Remarks

Windows Help divides the display into 1024 units in both the x and y directions. To create a secondary window that fills the upper-left quadrant of the display, for example, an application would specify zero for the x and y members and 512 for the dx and dy members.

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.


IE4COMPONENT

Used by Microsoft® Internet Explorer 4.0 and 4.01 to hold information about a component. With Microsoft® Windows® 2000, it is replaced by the COMPONENT structure.

typedef struct _tagIE4COMPONENT
{
    DWORD dwSize;
    DWORD dwID;
    int iComponentType;
    BOOL fChecked;
    BOOL fDirty;
    BOOL fNoScroll;
    COMPPOS cpPos;
    WCHAR wszFriendlyName[MAX_PATH];
    WCHAR wszSource[INTERNET_MAX_URL_LENGTH];
    WCHAR wszSubscribedURL[INTERNET_MAX_URL_LENGTH];
}
IE4COMPONENT, *LPIE4COMPONENT;

Members

dwSize
Size of the structure.
dwID
Reserved. Set to zero.
iComponentType
Component type. It can be set to one of these values:
COMP_TYPE_HTMLDOC | HTML document
COMP_TYPE_PICTURE | Picture
COMP_TYPE_WEBSITE | Web site
COMP_TYPE_CONTROL | Control
fChecked
Value that is set to TRUE if the component is enabled, or FALSE if not.
fDirty
Value that is set to TRUE if the component has been modified and not yet saved to disk. It will be set to FALSE if the component has not been modified, or if it has been modified and saved to disk.
fNoScroll
Value that is set to TRUE if the component is scrollable, or FALSE if it's not.
cpPos
COMPPOS structure containing position and size information.
wszFriendlyName
Component's friendly name.
wszSource
Component's URL.
wszSubscribed
URL that a user has been subscribed to.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


ITEMIDLIST

Contains a list of item identifiers.

typedef struct _ITEMIDLIST {
    SHITEMID mkid;
} ITEMIDLIST, * LPITEMIDLIST;
typedef const ITEMIDLIST * LPCITEMIDLIST;

Members

mkid
List of item identifiers.

Remarks

A pointer to this structure, called a PIDL, is used to identify objects in the Shell namespace. For a discussion of PIDLs, see The Shell Namespace.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


MULTIKEYHELP

Specifies a keyword to search for and the keyword table to be searched by Windows Help.

typedef struct tagMULTIKEYHELP {
    DWORD  mkSize;
    TCHAR  mkKeylist;
    TCHAR  szKeyphrase[1];
} MULTIKEYHELP;

Members

mkSize
Structure size, in bytes.
mkKeylist
Single character that identifies the keyword table to search.
szKeyphrase
Null-terminated text string that specifies the keyword to locate in the keyword table.

See Also

WinHelp

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in winuser.h.


NEWCPLINFO

Contains resource information and an application-defined value for a dialog box supported by a Control Panel application.

typedef struct tagNEWCPLINFO {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwHelpContext;
    LONG  lData;
    HICON hIcon;
    TCHAR  szName[32];
    TCHAR  szInfo[64];
    TCHAR  szHelpFile[128];
} NEWCPLINFO;

Members

dwSize
Length of the structure, in bytes.
dwFlags
This member is ignored.
dwHelpContext
This member is ignored.
lData
Data defined by the application. When the Control Panel sends the CPL_DBLCLK and CPL_STOP messages, it passes this value back to your application.
hIcon
Identifier of the icon that represents the dialog box. This icon is intended to be displayed by the application that controls the Control Panel application.
szName
Null-terminated string that contains the dialog box name. The name is intended to be displayed below the icon.
szInfo
Null-terminated string containing the dialog box description. The description is intended to be displayed when the icon for the dialog box is selected.
szHelpFile
This member is ignored.

Remarks

The CPlApplet function of the Control Panel application returns this information to the Control Panel in response to a CPL_NEWINQUIRE message.

See Also

CPLINFO

Requirements

Windows NT/2000: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in cpl.h.


NOTIFYICONDATA

Contains information that the system needs to process taskbar status area messages.

typedef struct _NOTIFYICONDATA {
    DWORD cbSize;
    HWND hWnd;
    UINT uID;
    UINT uFlags;
    UINT uCallbackMessage;
    HICON hIcon;
    TCHAR szTip[64];
    DWORD dwState; //Version 5.0
    DWORD dwStateMask; //Version 5.0
    TCHAR szInfo[256]; //Version 5.0
    union {
        UINT  uTimeout; //Version 5.0
        UINT  uVersion; //Version 5.0
    } DUMMYUNIONNAME;
    TCHAR szInfoTitle[64]; //Version 5.0
    DWORD dwInfoFlags; //Version 5.0
} NOTIFYICONDATA, *PNOTIFYICONDATA;

Members

cbSize
Size of this structure, in bytes.
hWnd
Handle to the window that will receive notification messages associated with an icon in the taskbar status area. The Shell uses hWnd and uID to identify which icon on which to operate when Shell_NotifyIcon is invoked.
uID
Application-defined identifier of the taskbar icon. The Shell uses hWnd and uID to identify which icon on which to operate when Shell_NotifyIcon is invoked. You can have multiple icons associated with a single hWnd by assigning each a diffent uID.
uFlags
Array of flags that indicate which of the other members contain valid data. This member can be a combination of the following:
Flag | Description
NIF_ICON | The hIcon member is valid.
NIF_MESSAGE | The uCallbackMessage member is valid.
NIF_TIP | The szTip member is valid.
NIF_STATE | The dwState and dwStateMask members are valid.
NIF_INFO | Use a balloon-style ToolTip instead of a standard ToolTip. The szInfo, uTimeout, szInfoTitle, and dwInfoFlags members are valid.
uCallbackMessage
Application-defined message identifier. The system uses this identifier to send notifications to the window identified in hWnd. These notifications are sent when a mouse event occurs in the bounding rectangle of the icon, or when the icon is selected or activated with the keyboard. The wParam parameter of the message contains the identifier of the taskbar icon in which the event occurred. The lParam parameter holds the mouse or keyboard message associated with the event. For example, when the mouse cursor moves over a taskbar icon, lParam is set to WM_MOUSEMOVE. See the Taskbar guide chapter for further discussion.
hIcon
Handle to the icon to be added, modified, or deleted.
szTip
Pointer to a NULL-terminated string with the text for a standard ToolTip. It can have a maximum of 64 characters including the terminating NULL.

For Version 5.0 and later, szTip can have a maximum of 128 characters, including the terminating NULL.

dwState
Version 5.0. State of the icon. There are two flags that can be set independently:
Flag | Description
NIS_HIDDEN | The icon is hidden.
NIS_SHAREDICON | The icon is shared.
dwStateMask
Version 5.0. A value that specifies which bits of the state member will be retrieved or modified. For example, setting this member to NIS_HIDDEN will cause only the item's hidden state to be retrieved.
szInfo
Version 5.0. Pointer to a NULL-terminated string with the text for a balloon-style ToolTip. It can have a maximum of 255 characters. To remove the ToolTip, set the NIF_INFO flag in uFlags and set szInfo to an empty string.
uTimeout
The timeout value, in milliseconds, for a balloon-style ToolTip. The system enforces minimum and maximum timeout values. uTimeout values that are too large are set to the maximum value and values that are too small default to the minimum value. The system minimum and maximum timeout values are currently set at 10 seconds and 30 seconds, respectively. These values may change in future versions of Windows. See the remarks for further discussion of uTimeout. Union with uVersion.
uVersion
Version 5.0. Specifies whether the Shell notify icon interface should use Windows 95 or Windows 2000 behavior. This member is only employed when using Shell_NotifyIcon to send an NIM_VERSION message. Union with uTimeout.
Value | Description
0 | Use the Windows 95 behavior.
NOTIFYICON_VERSION | Use the Windows 2000 behavior.
szInfoTitle
Version 5.0. Pointer to a NULL-terminated string containing a title for a balloon ToolTip. This title will be in boldface, and placed above the text. It can have a maximum of 63 characters.
dwInfoFlags
Version 5.0. Flags that can be set to add an icon to a balloon ToolTip. It will be placed to the left of the title. If the szTitleInfo member is zero-length, the icon will not be shown.
Flag | Description
NIIF_WARNING | A warning icon.
NIIF_ERROR | An error icon.
NIIF_INFO | An information icon.

Remarks

If you set the NIF_INFO flag in the uFlags member, the standard ToolTip, will be replaced by a balloon ToolTip. For more discussion of balloon ToolTips, see the ToolTip Controls chapter.

No more than one balloon ToolTip at at time will be displayed for the taskbar. If an application attempts to display a ToolTip when one is already being displayed, the ToolTip will not appear until the existing balloon ToolTip has been visible for at least the system minum timeout value. For example, a balloon ToolTip with uTimeout set to 30 seconds has been visible for seven seconds when another application attempts to display a balloon ToolTip. If the system minimum timeout is ten seconds, the first ToolTip will be displayed for an additional three seconds before being replaced by the second ToolTip.

Note that several members of this structure are only supported for Shell32.dll versions 5.0 and later. To enable these members, include the following in your header:

#define _WIN32_IE 0x0500

However, you must initialize the structure with its size. If you use the size of the currently defined structure, the application may not run with the earlier versions of Shell32.dll, which expect a smaller structure. You can run your application on pre-5.0 versions of Shell32.dll by defining the appropriate version number (see Shell and Common Controls Versions). However, this may cause problems if your application also needs to run on systems with more recent versions.

Your application can remain compatible with all Shell32.dll versions while still using the current header files by setting the size of the NOTIFYICONDATA structure appropriately. Before initializing the structure, use the DllGetVersion function to determine which Shell32.dll version is installed on the system. If it is version 5.0 or greater, initialize the cbSize member with:

nid.cbSize = sizeof(NOTIFYICONDATA);

Setting cbSize to this value will enable all the version 5.0 enhancements. For earlier versions, the size of the pre-5.0 structure is given by the NOTIFYICONDATA_V1_SIZE constant. Initialize the cbSize member with:

nid.cbSize = NOTIFYICONDATA_V1_SIZE;

Using this value for cbSize will allow your application to use NOTIFYICONDATA with earlier Shell32.dll versions, although without the version 5.0 enhancements.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


NRESARRAY

Defines the CF_NETRESOURCE clipboard format.

typedef struct _NRESARRAY {
    UINT        cItems;
    NETRESOURCE nr[1];
} NRESARRAY, * LPNRESARRAY;

Members

cItems
Number of elements in the nr array.
nr
Array of NETRESOURCE structures that contain information about network resources. The string members (LPSTR types) in the structure contain offsets instead of addresses.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


NT_CONSOLE_PROPS

Holds an extra data block used by IShellLinkDataList. It holds console properties.

typedef struct {
    DATABLOCK_HEADER dbh;
    WORD     wFillAttribute;
    WORD     wPopupFillAttribute;
    COORD    dwScreenBufferSize;
    COORD    dwWindowSize;
    COORD    dwWindowOrigin;
    DWORD    nFont;
    DWORD    nInputBufferSize;
    COORD    dwFontSize;
    UINT     uFontFamily;
    UINT     uFontWeight;
    WCHAR    FaceName[LF_FACESIZE];
    UINT     uCursorSize;
    BOOL     bFullScreen;
    BOOL     bQuickEdit;
    BOOL     bInsertMode;
    BOOL     bAutoPosition;
    UINT     uHistoryBufferSize;
    UINT     uNumberOfHistoryBuffers;
    BOOL     bHistoryNoDup;
    COLORREF ColorTable[ 16 ];
} NT_CONSOLE_PROPS, *LPNT_CONSOLE_PROPS;

Members

dbh
DATABLOCK_HEADER structure with the NT_CONSOLE_PROPS structure's size and signature. The signature for an NT_CONSOLE_PROPS structure is NT_CONSOLE_PROPS_SIG.
wFillAttribute
Fill attribute for the console.
wPopupFillAttribute
Fill attribute for console pop-ups.
dwScreenBufferSize
COORD structure with the console's screen buffer size.
dwWindowSize
COORD structure with the console's window size.
dwWindowOrigin
COORD structure with the console's window origin.
nFont
Font.
nInputBufferSize
Input buffer size.
dwFontSize
COORD structure with the font size.
uFontFamily
Font family.
uFontWeight
Font weight.
FaceName
Character array that contains the font's face name.
uCursorSize
Cursor size.
bFullScreen
Boolean value that is set to TRUE if the console is in full-screen mode, or FALSE otherwise.
bQuickEdit
Boolean value that is set to TRUE if the console is in quick-edit mode, or FALSE otherwise.
bInsertMode
Boolean value that is set to TRUE if the console is in insert mode, or FALSE otherwise.
bAutoPosition
Boolean value that is set to TRUE if the console is in auto-position mode, or FALSE otherwise.
uHistoryBufferSize
Size of the history buffer.
uNumberOfHistoryBuffers
Number of history buffers.
bHistoryNoDup
Boolean value that is set to TRUE if old duplicate history lists should be discarded, or FALSE otherwise.
ColorTable
Array of COLORREF values with the console's color settings.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


NT_FE_CONSOLE_PROPS

Holds an extra data block used by IShellLinkDataList. It holds the console's code page.

typedef struct {
    DATABLOCK_HEADER dbh;
    UINT     uCodePage;
} NT_FE_CONSOLE_PROPS, *LPNT_FE_CONSOLE_PROPS;

Members

dbh
DATABLOCK_HEADER structure with the NT_FE_CONSOLE_PROPS structure's size and signature. The signature for an NT_FE_CONSOLE_PROPS structure is NT_FE_CONSOLE_PROPS_SIG.
uCodePage
Console's code page.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


PERSIST_FOLDER_TARGET_INFO

Specifies a folder shortcut's target folder and its attributes. This structure is used by IPersistFileSystemFolder::GetFolderTargetInfo and IPersistFileSystemFolder::InitializeEx.

typedef struct
{
    LPITEMIDLIST  pidlTargetFolder;
    WCHAR         szTargetParsingName[MAX_PATH];
    WCHAR         szNetworkProvider[MAX_PATH];
    DWORD         dwAttributes;
    int           csidl;
} PERSIST_FOLDER_TARGET_INFO;

Members

pidlTargetFolder
Fully qualified PIDL of the target folder. Set pidlTargetFolder to NULL if not specified.
szTargetParsingName
NULL-terminated Unicode string with the target folder's parsing name. Set szTargetParsingName to an empty string if not specified.
szNetworkProvider
NULL-terminated Unicode string that specifies the type of network provider that will be used when binding to the target folder. The format is the same as that used by the WNet API. Set szNetworkProvider to an empty string if not specified.
dwAttributes
DWORD value that contains SFGAO_XXX file attribute flags. For a complete list of available flags, see IShellFolder::ParseDisplayName. Set dwAttributes to -1 if not specified.
csidl
Target folder's CSIDL value, if it has one. Set csidl to -1 if the target folder does not have a CSIDL. In addition to the CSIDL value, you can also set the following two flags.
CSIDL_FLAG_PFTI_TRACKTARGET | Indicates that the target folder should change if the user changes the target folder's underlying CSIDL value.
CSIDL_FLAG_CREATE | Indicates that the target folder should be created if it does not already exist.

Remarks

Any or all of the pidlTargetFolder, szTargetParsingName, and csidl members can be used to specify the target folder's location.

See Also

IPersistFolder3

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


PUBAPPINFO Structure

This is preliminary documentation and is subject to change.

Provides information about a published application from an application publisher to the Add/Remove Programs control panel applet.

Syntax

typedef struct {
    DWORD cbSize;
    DWORD dwMask;
    LPWSTR pszSource;
    SYSTEMTIME stAssigned;
    SYSTEMTIME stPublished;
    SYSTEMTIME stScheduled;
    SYSTEMTIME stExpire;
} PUBAPPINFO;

Members

cbSize
DWORD size of the PUBAPPINFO data structure. This member is set by the Add/Remove Program executable code.
dwMask
Bit mask indicating which items in the structure are valid.
pszSource
Pointer to a string containing the display name of the publisher. This name will be displayed in Add/Remove Programs if duplicate application names are encountered. The string buffer must be allocated using the Shell task allocator (cf. SHGetMalloc).
stAssigned
Time when an application manager scheduled this application's installation. Add/Remove Programs will not allow the user to schedule an installation time later than the value in this member. This member is ignored if it describes a time prior to the current time.
stPublished
Not used.
stScheduled
Time user scheduled this application's installation.
stExpire
Time after which the published application cannot be installed via Add/Remove Programs.

Structure Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IAppPublisher, IPublishedApp::GetPublishedAppInfo


SHChangeProductKeyAsIDList Structure

Not currently supported.


SHCOLUMNDATA

Contains information that identifies a particular file. It is used by IColumnProvider::GetItemData when requesting data for a particular file.

typedef struct {
    ULONG   dwFlags;
    DWORD   dwFileAttributes;
    ULONG   dwReserved;
    WCHAR   *pwszExt;
    WCHAR   wszFile[MAX_PATH];
} SHCOLUMNDATA, *LPSHCOLUMNDATA;
typedef const SHCOLUMNDATA* LPCSHCOLUMNDATA;

Members

dwFlags
Flags used to specify the nature of the request.
Flag | Description
SHCDF_UPDATEITEM | The file specified by wszFile is a new file or a file that has changed since the last call to IColumnProvider::GetItemData . Any cached data should be flushed and recalculated. Column handlers that do not cache data, or that display data that is stored separately from the file, can ignore this flag.
dwFileAttributes
File attribute flags. It will be one or more of the following values.
Flag | Description
FILE_ATTRIBUTE_ARCHIVE | The file or directory is an archive file or directory. Applications use this attribute to mark files for backup or removal.
FILE_ATTRIBUTE_COMPRESSED | The file or directory is compressed. For a file, this means that all data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_DIRECTORY | The handle identifies a directory.
FILE_ATTRIBUTE_ENCRYPTED | The file or directory is encrypted. For a file, this means that all data streams in the file are encrypted. For a directory, this means that encryption is the default for newly created files and subdirectories.
FILE_ATTRIBUTE_HIDDEN | The file or directory is hidden. It is not included in an ordinary directory listing.
FILE_ATTRIBUTE_NORMAL | The file or directory has no other attributes set. This attribute is valid only if used alone.
FILE_ATTRIBUTE_OFFLINE | The data of the file is not immediately available. This attribute indicates that the file data has been physically moved to offline storage. This attribute is used by Remote Storage, the hierarchical storage management software in Microsoft® Windows® 2000. If this attribute is set, the column handler should avoid opening the file because doing so will cause the file to be recalled from offline storage.
FILE_ATTRIBUTE_READONLY | The file or directory is read-only. Applications can read the file but cannot write to it or delete it. In the case of a directory, applications cannot delete it.
FILE_ATTRIBUTE_REPARSE_POINT | The file has an associated reparse point.
FILE_ATTRIBUTE_SPARSE_FILE | The file is a sparse file.
FILE_ATTRIBUTE_SYSTEM | The file or directory is part of, or is used exclusively by, the operating system.
FILE_ATTRIBUTE_TEMPORARY | The file is being used for temporary storage. File systems attempt to keep all of the data in memory for quicker access rather than flushing the data back to mass storage. A temporary file should be deleted by the application as soon as it is no longer needed.
dwReserved
Reserved. Set to NULL.
pwszExt
Pointer to a NULL-terminated Unicode string with a file name extension.
wszFile
NULL-terminated Unicode string containing a fully qualified file path.

See Also

GetFileAttributes

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


SHCOLUMNID Structure

This is preliminary documentation and is subject to change.

Specifies a property identifier that maps to the functions of the IPropertySetStorage Online link interface. IPropertySetStorage creates, opens, deletes, and enumerates property set storages.

Syntax

typedef struct {
    GUID fmtid;
    DWORD pid;
} SHCOLUMNID, *LPSHCOLUMNID;

Members

fmtid
Specifies the property identifiers in the property set.
pid
Specifies a property identifier.

Structure Information

Header and IDL files shobjidl.h, shobjidl.idl
Minimum operating systems


SHCOLUMNINFO

Contains information about the properties of a column. It is used by IColumnProvider::GetColumnInfo.

typedef struct {
    SHCOLUMNID  scid;
    VARTYPE     vt;
    DWORD       fmt;
    UINT        cChars;
    DWORD       csFlags;
    WCHAR wszTitle[MAX_COLUMN_NAME_LEN];
    WCHAR wszDescription[MAX_COLUMN_DESC_LEN];
} SHCOLUMNINFO, *LPSHCOLUMNINFO;
typedef const SHCOLUMNINFO* LPCSHCOLUMNINFO;

Members

scid
[out] SHCOLUMNID structure that uniquely identifies the column.
vt
[out] Native VARIANT type of the column's data.
fmt
[out] List view format. This member is normally set to LVCFMT_LEFT.
cChars
[out] Default width of the column, in characters.
csFlags
[out] Flags indicating the default column state. It can be a combination of the following flags.
Flag | Description
SHCOLSTATE_TYPE_STR | A string.
SHCOLSTATE_TYPE_INT | An integer.
SHCOLSTATE_TYPE_DATE | A date.
SHCOLSTATE_ONBYDEFAULT | Will be shown by default in Microsoft® Windows® Explorer Details view, even if the user has not selected the column. If this flag is set, the column will be displayed for all folders. There is no way to force a column to be displayed on a per-folder basis.
SHCOLSTATE_SLOW | Will be slow to compute. Windows Explorer should retrieve the data asynchronously and do the computation on a background thread.
SHCOLSTATE_EXTENDED | Provided by a handler, not the folder object.
SHCOLSTATE_SECONDARYUI | Not displayed in the shortcut menu, but listed in the More... dialog box.
SHCOLSTATE_HIDDEN | Not displayed in the user interface.
wszTitle
[out] Unicode string with the column's title. It must contain no more than MAX_COLUMN_NAME_LEN characters, including the terminating NULL.
wszDescription
[out] Unicode string with the column's description. It must contain no more than MAX_COLUMN_DESC_LEN characters, including the terminating NULL.

See Also

IColumnProvider::GetColumnInfo

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


SHCOLUMNINIT

Passes initialization information to IColumnProvider::Initialize.

typedef struct {
    ULONG    dwFlags;
    ULONG    dwReserved;
    WCHAR    wszFolder[MAX_PATH];
} SHCOLUMNINIT, *LPSHCOLUMNINIT;
typedef const SHCOLUMNINFO* LPCSHCOLUMNINFO;

Members

dwFlags
Initialization flags. Reserved. Set to NULL
dwReserved
Reserved. Set to NULL.
wszFolder
Pointer to a NULL-terminated Unicode string with a fully qualified folder path. The string will be empty if multiple folders are specified.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


SHCREATEPROCESSINFOW

Contains the information needed by SHCreateProcessAsUserW to create a process.

typedef struct _SHCREATEPROCESSINFOW
{
        DWORD cbSize;
        ULONG fMask;
        HWND hwnd;
        LPCWSTR  pszFile;
        LPCWSTR  pszParameters;
        LPCWSTR  pszCurrentDirectory;
        HANDLE hUserToken;
        LPSECURITY_ATTRIBUTES lpProcessAttributes;
        LPSECURITY_ATTRIBUTES lpThreadAttributes;
        BOOL bInheritHandles;
        DWORD dwCreationFlags;
        LPSTARTUPINFOW lpStartupInfo;
        LPPROCESS_INFORMATION lpProcessInformation;
} SHCREATEPROCESSINFOW, *PSHCREATEPROCESSINFOW;

Members

cbSize
[in] Size, in bytes, of this structure.
fMask
[in] Array of flags that indicates the content and validity of the other structure members. This can be a combination of the following values.
Flag | Description
SEE_MASK_CLASSKEY | Use the file's class registry key.
SEE_MASK_CLASSNAME | Use the file's class name.
SEE_MASK_CONNECTNETDRV | Validate the share and connect to a drive letter. The pwszFile member is a Universal Naming Convention (UNC) path of a file on a network.
SEE_MASK_DOENVSUBST | Expand any environment variables.
SEE_MASK_FLAG_DDEWAIT | Wait for the DDE conversation to terminate before returning.
SEE_MASK_FLAG_NO_UI | Do not display an error message box if an error occurs.
SEE_MASK_HMONITOR | Use this flag when specifying a monitor on multimonitor systems.
SEE_MASK_NOCLOSEPROCESS | The application will close the process. If the lpProcessInformation member is a valid PROCESS_INFORMATION pointer, and SEE_MASK_NOCLOSEPROCESS is set, the process will remain open when SHCreateProcessAsUserW returns. The hProcess and hThread members of the PROCESS_INFORMATION structure will hold the process and thread handles, respectively. This flag is typically set to allow an application to find out when a process created with SHCreateProcessAsUserW terminates. In some cases, such as when execution is satisfied through a DDE conversation, no handle will be returned. The calling application is responsible for closing the handle when it is no longer needed. If this flag is not set, the process will be closed before SHCreateProcessAsUserW returns, even if lpProcessInformation is a valid pointer.
SEE_MASK_NO_CONSOLE | Create a console for the new process instead of having it inherit the parent's console. It is equivalent to using a CREATE_NEW_CONSOLE flag with CreateProcess.
SEE_MASK_UNICODE | Indicates a Unicode application.
hwnd
[in] Parent window handle.
pwszFile
[in] Pointer to a NULL-terminated Unicode string that specifies the executable file on which SHCreateProcessAsUserW will perform the action specified by the runas verb. The runas verb must be supported by the file's class.

Note: If the path is not included with the file name, the current directory is assumed.

pwszParameters
[in] Pointer to a NULL-terminated Unicode string containing the application parameters. The parameters must be separated by spaces. To include double quotation marks, you must enclose each mark in a pair of quotation marks, as in the following example:

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

In this case, the application receives three parameters: An, example:, and "quoted text".

pwszCurrentDirectory
[in] NULL-terminated Unicode string that contains the current directory.
hUserToken
[in] Access token that can be used to represent a particular user. It is needed when there are multiple users for those folders that are treated as belonging to a single user. The caller must have appropriate security privileges for the particular user, including TOKEN_QUERY and TOKEN_IMPERSONATE, and the user's registry hive must be currently mounted. For further discussion of access control issues, see Access Control.
lpProcessAttributes
[in] Pointer to a SECURITY_ATTRIBUTES structure with the security descriptor for the new process. It also specifies whether a child process can be inherited. If this parameter is set to NULL, the process will have a default security descriptor and the handle cannot be inherited.
lpThreadAttributes
[in] Pointer to a SECURITY_ATTRIBUTES structure with the security descriptor for the new thread. It also specifies whether a child process can be inherited. If this parameter is set to NULL, the process will have a default security descriptor and the handle cannot be inherited.
bInheritHandles
[in] Indicator as to whether the new process inherits handles from the calling process. If set to TRUE, each inheritable open handle in the calling process is inherited by the new process. Inherited handles have the same value and access privileges as the original handles.
dwCreationFlags
[in] Flags that control the creation of the process and the priority class. For a list of the available flags, see CreateProcessAsUser.
lpStartupInfo
[in] Pointer to a STARTUPINFO structure that specifies how the main window for the new process should appear.
lpProcessInformation
[out] Pointer to a PROCESS_INFORMATION structure that receives information about the new process. Set this member to a valid structure pointer, and set the SEE_MASK_NOCLOSEPROCESS flag in the fMask member, and the process will remain open when the function returns. The structure's hProcess and hThread members will then hold the process and thread handles, respectively. Set this member to NULL, and the process will be closed before the function returns.

See Also

SHELLEXECUTEINFO

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shellapi.h.
Import Library: Shell32.lib.


SHDESCRIPTIONID

Receives item data in response to a call to SHGetDataFromIDList.

typedef struct SHDESCRIPTIONID{
    DWORD   dwDescriptionId;
    CLSID   clsid;
} SHDESCRIPTIONID, *LPSHDESCRIPTIONID;

Members

dwDescriptionId
Receives a value that determines what type the item is. This can be one of the following values:
SHDID_ROOT_REGITEM | The item is a registered item on the desktop.
SHDID_FS_FILE | The item is a file.
SHDID_FS_DIRECTORY | The item is a folder.
SHDID_FS_OTHER | The item is an unidentified item in the file system.
SHDID_COMPUTER_DRIVE35 | The item is a 3.5-inch floppy drive.
SHDID_COMPUTER_DRIVE525 | The item is a 5.25-inch floppy drive.
SHDID_COMPUTER_REMOVABLE | The item is a removable disk drive.
SHDID_COMPUTER_FIXED | The item is a fixed disk drive.
SHDID_COMPUTER_NETDRIVE | The item is a drive that is mapped to a network share.
SHDID_COMPUTER_CDROM | The item is a CD-ROM drive.
SHDID_COMPUTER_RAMDISK | The item is a RAM disk.
SHDID_COMPUTER_OTHER | The item is an unidentified system device.
SHDID_NET_DOMAIN | The item is a network domain.
SHDID_NET_SERVER | The item is a network server.
SHDID_NET_SHARE | The item is a network share.
SHDID_NET_RESTOFNET | Not currently used.
SHDID_NET_OTHER | The item is an unidentified network resource.
clsid
Receives the CLSID of the object to which the item belongs.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


SHDRAGIMAGE

Contains the information needed to create a drag image.

typedef struct
{
    SIZE        sizeDragImage;
    POINT       ptOffset;
    HBITMAP     hbmpDragImage;
    COLORREF    crColorKey;
} SHDRAGIMAGE, *LPSHDRAGIMAGE;

Members

sizeDragImage
SIZE structure with the length and width of the drag image.
ptOffset
POINT structure that specifies the location of the cursor within the drag image. The structure should contain the offset from the upper-left corner of the drag image to the location of the cursor.
hbmpDragImage
Drag image's bitmap handle.
crColorKey
Color used by the control to fill the background of the drag image.

Remarks

Use the following procedure to create the drag image:

  1. Create a bitmap of the size specified by sizeDragImage with an HDC that is compatible with the screen.
  2. Draw the bitmap.
  3. Select the bitmap out of the HDC it was created with.
  4. Destroy the HDC.
  5. Assign the bitmap handle to hbmpDragImage.

Note: Turn off antialiasing when drawing text. Otherwise, artifacts could occur at the edges, between the text color and the color key.

See Also

IDragSourceHelper::InitializeFromBitmap, IDragSourceHelper::InitializeFromWindow

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


SHELLDETAILS

Returns detailed information on an item in a Shell folder.

typedef struct _SHELLDETAILS
{
    int     fmt;
    int     cxChar;
    STRRET  str;
} SHELLDETAILS, *LPSHELLDETAILS;

Members

fmt
Alignment of the column heading and the subitem text in the column. This member can be one of the following values.
Flag | Description
LVCFMT_CENTER | Text is centered.
LVCFMT_COL_HAS_IMAGES | Version 4.70. Header item contains an image in the image list.
LVCFMT_LEFT | Text is left-aligned.
LVCFMT_RIGHT | Text is right-aligned.

The alignment of the leftmost column is always left-justified and cannot be changed.

cxChar
Number of average-sized characters in the header.
str
STRRET structure that includes a string with the requested information. To convert this structure to a string, use StrRetToBuf or StrRetToStr.

See Also

IShellDetails::GetDetailsOf

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


SHELLEXECUTEINFO

Contains information used by ShellExecuteEx.

typedef struct _SHELLEXECUTEINFO{
    DWORD cbSize;
    ULONG fMask;
    HWND hwnd;
    LPCTSTR lpVerb;
    LPCTSTR lpFile;
    LPCTSTR lpParameters;
    LPCTSTR lpDirectory;
    int nShow;
    HINSTANCE hInstApp;

    // Optional members
    LPVOID lpIDList;
    LPCSTR lpClass;
    HKEY hkeyClass;
    DWORD dwHotKey;
    union {
        HANDLE hIcon;
        HANDLE hMonitor;
    };
    HANDLE hProcess;
} SHELLEXECUTEINFO, *LPSHELLEXECUTEINFO;

Members

cbSize
Size of the structure, in bytes.
fMask
Array of flags that indicate the content and validity of the other structure members. This can be a combination of the following values.
SEE_MASK_CLASSKEY | Use the class key given by the hkeyClass member.
SEE_MASK_CLASSNAME | Use the class name given by the lpClass member.
SEE_MASK_CONNECTNETDRV | Validate the share and connect to a drive letter. The lpFile member is a Universal Naming Convention (UNC) path of a file on a network.
SEE_MASK_DOENVSUBST | Expand any environment variables specified in the string given by the lpDirectory or lpFile member.
SEE_MASK_FLAG_DDEWAIT | Wait for the DDE conversation to terminate before returning (if the ShellExecuteEx function causes a DDE conversation to start). For circumstances in which this flag is necessary, see the Remarks section.
SEE_MASK_FLAG_NO_UI | Do not display an error message box if an error occurs.
SEE_MASK_HMONITOR | Use this flag when specifying a monitor on multimonitor systems. The monitor is specified in the hMonitor member. This flag cannot be combined with SEE_MASK_ICON.
SEE_MASK_HOTKEY | Use the hot key given by the dwHotKey member.
SEE_MASK_ICON | Use the icon given by the hIcon member. This flag cannot be combined with SEE_MASK_HMONITOR.
SEE_MASK_IDLIST | Use the item identifier list given by the lpIDList member. The lpIDList member must point to an ITEMIDLIST structure.
SEE_MASK_INVOKEIDLIST | Use the IContextMenu interface of the selected item's shortcut menu handler. Use either lpFile to identify the item by its file system path or lpIDList to identify the item by its PIDL. This flag allows applications to use ShellExecuteEx to invoke verbs from shortcut menu extensions instead of the static verbs listed in the registry.
SEE_MASK_NOCLOSEPROCESS | Use to indicate that the hProcess member receives the process handle. This handle is typically used to allow an application to find out when a process created with ShellExecuteEx terminates. In some cases, such as when execution is satisfied through a DDE conversation, no handle will be returned. The calling application is responsible for closing the handle when it is no longer needed.
SEE_MASK_NO_CONSOLE | Use to create a console for the new process instead of having it inherit the parent's console. It is equivalent to using a CREATE_NEW_CONSOLE flag with CreateProcess.
SEE_MASK_UNICODE | Use this flag to indicate a Unicode application.
hwnd
Window handle to any message boxes that the system might produce while executing this function.
lpVerb
String, referred to as a verb, that specifies the action to be performed. The set of available verbs depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available verbs. For more specific information about verbs, see Object Verbs. For further discussion of shortcut menus, see Extending Shortcut Menus. The following verbs are commonly used.
edit | Launches an editor and opens the document for editing. If lpFile is not a document file, the function will fail.
explore | Explores the folder specified by lpFile.
find | Initiates a search starting from the specified directory.
open | Opens the file specified by the lpFile parameter. The file can be an executable file, a document file, or a folder.
print | Prints the document file specified by lpFile. If lpFile is not a document file, the function will fail.
properties | Displays the file or folder's properties.

If you set this parameter to NULL:

  • For systems prior to Microsoft® Windows® 2000, the default verb is used if it is valid and available in the registry. If not, the "open" verb is used.
  • For Windows 2000 and later systems, the default verb is used if available. If not, the "open" verb is used. If neither verb is available, the system uses the first verb listed in the registry.
lpFile
Address of a null-terminated string that specifies the name of the file or object on which ShellExecuteEx will perform the action specified by the lpVerb parameter. The system registry verbs that are supported by the ShellExecuteEx function include "open" for executable files and document files and "print" for document files for which a print handler has been registered. Other applications might have added Shell verbs through the system registry, such as "play" for AVI and WAV files. To specify a Shell namespace object, pass the fully qualified parse name and set the SEE_MASK_INVOKEIDLIST flag in the fMask parameter.

Note If the path is not included with the name, the current directory is assumed.

lpParameters
Address of a null-terminated string that contains the application parameters. The parameters must be separated by spaces. To include double quotation marks, enclose each mark in a pair of quotation marks, as in the following example.
sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

In this case, the application receives three parameters: An, example:, and "quoted text".

If the lpFile member specifies a document file, this member should be NULL.

lpDirectory
Address of a null-terminated string that specifies the name of the working directory. If this member is not specified, the current directory is used as the working directory.
nShow
Flags that specify how an application is to be shown when it is opened. It can be one of the SW_ values listed for the ShellExecute function. If lpFile specifies a document file, the flag is simply passed to the associated application. It is up to the application to decide how to handle it.
hInstApp
If the function succeeds, it sets this member to a value greater than 32. If the function fails, it is set to an SE_ERR_XXX error value that indicates the cause of the failure. Although hInstApp is declared as an HINSTANCE for compatibility with 16-bit Windows applications, it is not a true HINSTANCE. It can be cast only to an integer and compared to either 32 or the following SE_ERR_XXX error codes.
SE_ERR_FNF | File not found.
SE_ERR_PNF | Path not found.
SE_ERR_ACCESSDENIED | Access denied.
SE_ERR_OOM | Out of memory.
SE_ERR_DLLNOTFOUND | Dynamic-link library not found.
SE_ERR_SHARE | Cannot share an open file.
SE_ERR_ASSOCINCOMPLETE | File association information not complete.
SE_ERR_DDETIMEOUT | DDE operation timed out.
SE_ERR_DDEFAIL | DDE operation failed.
SE_ERR_DDEBUSY | DDE operation is busy.
SE_ERR_NOASSOC | File association not available.
lpIDList
Address of an ITEMIDLIST structure to contain an item identifier list uniquely identifying the file to execute. This member is ignored if the fMask member does not include SEE_MASK_IDLIST.
lpClass
Address of a null-terminated string that specifies the name of a file class or a globally unique identifier (GUID). This member is ignored if fMask does not include SEE_MASK_CLASSNAME.
hkeyClass
Handle to the registry key for the file class. This member is ignored if fMask does not include SEE_MASK_CLASSKEY.
dwHotKey
Hot key to associate with the application. The low-order word is the virtual key code, and the high-order word is a modifier flag (HOTKEYF_). For a list of modifier flags, see the description of the WM_SETHOTKEY message. This member is ignored if fMask does not include SEE_MASK_HOTKEY.
hIcon
Handle to the icon for the file class. This member is ignored if fMask does not include SEE_MASK_ICON.
hMonitor
Handle to the monitor upon which the document is to be displayed. This member is ignored if fMask does not include SEE_MASK_HMONITOR.
hProcess
Handle to the newly started application. This member is set on return and is always NULL unless fMask is set to SEE_MASK_NOCLOSEPROCESS. Even if fMask is set to SEE_MASK_NOCLOSEPROCESS, hProcess will be NULL if no process was launched. For example, if a document to be launched is a URL and an instance of Microsoft® Internet Explorer is already running, it will display the document. No new process is launched, and hProcess will be NULL.

Remarks

The SEE_MASK_FLAG_DDEWAIT flag must be specified if the thread calling ShellExecuteEx does not have a message loop or if the thread or process will terminate soon after ShellExecuteEx returns. Under such conditions, the calling thread will not be available to complete the DDE conversation, so it is important that ShellExecuteEx complete the conversation before returning control to the caller. Failure to complete the conversation can result in an unsuccessful launch of the document.

If the calling thread has a message loop and will exist for some time after the call to ShellExecuteEx returns, the SEE_MASK_FLAG_DDEWAIT flag is optional. If the flag is omitted, the calling thread's message pump will be used to complete the DDE conversation. The calling application regains control sooner, since the DDE conversation can be completed in the background.

Requirements

Windows NT/2000: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


SHELLFLAGSTATE

Contains a set of flags that indicate the current Shell settings. This structure is used with the SHGetSettings function.

typedef struct {
    BOOL fShowAllObjects : 1;
    BOOL fShowExtensions : 1;
    BOOL fNoConfirmRecycle : 1;
    BOOL fShowSysFiles : 1;
    BOOL fShowCompColor : 1;
    BOOL fDoubleClickInWebView : 1;
    BOOL fDesktopHTML : 1;
    BOOL fWin95Classic : 1;
    BOOL fDontPrettyPath : 1;
    BOOL fShowAttribCol : 1;
    BOOL fMapNetDrvBtn : 1;
    BOOL fShowInfoTip : 1;
    BOOL fHideIcons : 1;
    UINT fRestFlags : 3;
} SHELLFLAGSTATE, * LPSHELLFLAGSTATE;

Members

fShowAllObjects
Nonzero if the Show All Files option is enabled or zero otherwise.
fShowExtensions
Nonzero if the Hide File Extensions for Known File Types option is disabled or zero otherwise.
fNoConfirmRecycle
Nonzero if the Display Delete Confirmation Dialog box in the Recycle Bin is enabled or zero otherwise.
fShowSysFiles
Nonzero if the Do Not Show Hidden Files option is selected or zero otherwise.
fShowCompColor
Nonzero if the Display Compressed Files and Folders with Alternate Color option is enabled or zero otherwise.
fDoubleClickInWebView
Nonzero if the Double-Click to Open an Item option is enabled or zero otherwise.
fDesktopHTML
Nonzero if the Active Desktop – View as Web Page option is enabled or zero otherwise.
fWin95Classic
Nonzero if the Classic Style option is enabled or zero otherwise.
fDontPrettyPath
Nonzero if the Allow All Uppercase Names option is enabled or zero otherwise.
fShowAttribCol
Nonzero if the Show File Attributes in Detail View option is enabled or zero otherwise.
fMapNetDrvBtn
Nonzero if the Show Map Network Drive Button in Toolbar option is enabled or zero otherwise.
fShowInfoTip
Nonzero if the Show Info Tips for Items in Folders & Desktop option is enabled or zero otherwise.
fHideIcons
Not used.
fRestFlags
Not used.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


SHFILEINFO

Contains information about a file object.

typedef struct _SHFILEINFO{
    HICON hIcon;
    int   iIcon;
    DWORD dwAttributes;
    TCHAR szDisplayName[MAX_PATH];
    TCHAR szTypeName[80];
} SHFILEINFO;

Members

hIcon
Handle to the icon that represents the file. You are responsible for destroying this handle with DestroyIcon when you no longer need it.
iIcon
Index of the icon image within the system image list.
dwAttributes
Array of values that indicates the attributes of the file object. For information about these values, see the IShellFolder::GetAttributesOf method.
szDisplayName
String that contains the name of the file as it appears in the Windows Shell, or the path and file name of the file that contains the icon representing the file.
szTypeName
String that describes the type of file.

Remarks

This structure is used with the SHGetFileInfo function.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


SHFILEOPSTRUCT

Contains information that the SHFileOperation function uses to perform file operations.

typedef struct _SHFILEOPSTRUCT{
    HWND hwnd;
    UINT wFunc;
    LPCTSTR pFrom;
    LPCTSTR pTo;
    FILEOP_FLAGS fFlags;
    BOOL fAnyOperationsAborted;
    LPVOID hNameMappings;
    LPCSTR lpszProgressTitle;
} SHFILEOPSTRUCT, *LPSHFILEOPSTRUCT;

Members

hwnd
Window handle to the dialog box to display information about the status of the file operation.
wFunc
Value that indicates which operation to perform. This member can be one of the following values:
FO_COPY
Copy the files specified in the pFrom member to the location specified in the pTo member.
FO_DELETE
Delete the files specified in pFrom.
FO_MOVE
Move the files specified in pFrom to the location specified in pTo.
FO_RENAME
Rename the file specified in pFrom. You cannot use this flag to rename multiple files with a single function call. Use FO_MOVE instead.
pFrom
Address of a buffer to specify one or more source file names. These names must be fully qualified paths. Standard DOS wild cards, such as "*", are permitted in the file-name position. Although this member is declared as a null-terminated string, it is used as a buffer to hold multiple file names. Each file name must be terminated by a single NULL character. An additional NULL character must be appended to the end of the final name to indicate the end of pFrom.
pTo
Address of a buffer to contain the name of the destination file or directory. This parameter must be set to NULL if it is not used. Like pFrom, the pTo member is also a double-NULL terminated string and is handled in much the same way. However, pTo must meet the following specifications:
  • Wildcard characters are not supported.
  • Copy and Move operations can specify destination directories that do not exist and the system will attempt to create them. The system normally displays a dialog box to ask the user if they want to create the new directory. To suppress this dialog box and have the directories created silently, set the FOF_NOCONFIRMMKDIR flag in fFiles.
  • For Copy and Move operations, the buffer can contain multiple destination file names if the fFlags member specifies FOF_MULTIDESTFILES.
  • Pack multiple names into the string in the same way as for pFrom.
  • Use only fully-qualified path names. Using relative pathnames will have unpredictable results.
fFlags
Flags that control the file operation. This member can take a combination of the following flags:
Flag | Description
FOF_ALLOWUNDO | Preserve Undo information, if possible. If pFrom does not contain fully qualified path and file names, this flag is ignored.
FOF_FILESONLY | Perform the operation on files only if a wildcard file name (*.*) is specified.
FOF_MULTIDESTFILES | The pTo member specifies multiple destination files (one for each source file) rather than one directory where all source files are to be deposited.
FOF_NOCONFIRMATION | Respond with "Yes to All" for any dialog box that is displayed.
FOF_NOCONFIRMMKDIR | Do not confirm the creation of a new directory if the operation requires one to be created.
FOF_NO_CONNECTED_ELEMENTS | Version 5.0. Do not move connected files as a group. Only move the specified files.
FOF_NOCOPYSECURITYATTRIBS | Version 4.71. Do not copy the security attributes of the file.
FOF_NOERRORUI | Do not display a user interface if an error occurs.
FOF_NORECURSION | Only operate in the local directory. Don't operate recursively into subdirectories.
FOF_RENAMEONCOLLISION | Give the file being operated on a new name in a move, copy, or rename operation if a file with the target name already exists.
FOF_SILENT | Do not display a progress dialog box.
FOF_SIMPLEPROGRESS | Display a progress dialog box but do not show the file names.
FOF_WANTMAPPINGHANDLE | If FOF_RENAMEONCOLLISION is specified and any files were renamed, assign a name mapping object containing their old and new names to the hNameMappings member.
FOF_WANTNUKEWARNING | Version 5.0. Send a warning if a file is being destroyed during a delete operation rather than recycled. This flag partially overrides FOF_NOCONFIRMATION.
fAnyOperationsAborted
Value that receives TRUE if the user aborted any file operations before they were completed, or FALSE otherwise.
hNameMappings
A handle to a name mapping object containing the old and new names of the renamed files. This member is used only if the fFlags member includes the FOF_WANTMAPPINGHANDLE flag. Treat hNameMappings as a pointer to a structure whose first member is an INT value, followed by an array of SHNAMEMAPPING structures. The INT value will be set to the number of structures in the array. Each SHNAMEMAPPING structure will contain the old and new path name for one of the renamed files.

Note: The handle must be freed with SHFreeNameMappings.

lpszProgressTitle
Address of a string to use as the title of a progress dialog box. This member is used only if fFlags includes the FOF_SIMPLEPROGRESS flag.

Remarks

If the pFrom or pTo members are unqualified names, the current directories are taken from the global current drive and directory settings as managed by the GetCurrentDirectory and SetCurrentDirectory functions.

If pFrom is set to a file name, deleting the file with FO_DELETE will not move it to the Recycle Bin, even if the FOF_ALLOWUNDO flag is set. You must use a full pathname.

See Also

For a complete application that uses the SHFILEOPSTRUCT structure and explains how to set up the SHNAMEMAPPING structure, see the Knowledge Base Article Q151799 at http://support.microsoft.com/support/kb/articles/Q151/7/99.asp.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


SHITEMID

Defines an item identifier.

typedef struct _SHITEMID {
    USHORT cb;
    BYTE   abID[1];
} SHITEMID, * LPSHITEMID;
typedef const SHITEMID  * LPCSHITEMID;

Members

cb
Size of identifier, in bytes, including cb itself.
abID
Variable-length item identifier.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


SHNAMEMAPPING

Contains the old and new path names for each file that was moved, copied, or renamed by the SHFileOperation function.

typedef struct _SHNAMEMAPPING {
    LPSTR pszOldPath;
    LPSTR pszNewPath;
    int   cchOldPath;
    int   cchNewPath;
} SHNAMEMAPPING, *LPSHNAMEMAPPING;

Members

pszOldPath
Address of a character buffer that contains the old path name.
pszNewPath
Address of a character buffer that contains the new path name.
cchOldPath
Number of characters in pszOldPath.
cchNewPath
Number of characters in pszNewPath.

See Also

SHFILEOPSTRUCT

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


SHQUERYRBINFO

Contains the size and item count information retrieved by the SHQueryRecycleBin function.

typedef struct _SHQUERYRBINFO {
    DWORD cbSize;
    __int64 i64Size;
    __int64 i64NumItems;
} SHQUERYRBINFO, *LPSHQUERYRBINFO;

Members

cbSize
Size of the structure, in bytes. This member must be filled in prior to calling the function.
i64Size
Total size of all the objects in the specified Recycle Bin, in bytes.
i64NumItems
Total number of items in the specified Recycle Bin.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shellapi.h.


SLOWAPPINFO Structure

This is preliminary documentation and is subject to change.

Not supported. Provides specialized application information to the Add/Remove Programs control panel applet.

Syntax

typedef struct {
    ULONGLONG ullSize;
    FILETIME ftLastUsed;
    int iTimesUsed;
    LPWSTR pszImage;
} SLOWAPPINFO;

Members

ullSize
Size of the application in bytes.
ftLastUsed
Time the application was last used.
iTimesUsed
integer count of times the application has been used.
pszImage
Pointer to a string containing the path to the image that represents the application. The string buffer must be allocated using the Shell task allocator (cf. SHGetMalloc).

Remarks

This structure is used by IShellApp::GetSlowAppInfo and IShellApp::GetCachedSlowAppInfo, neither of which are applicable to published applications. Therefore this structure is also not applicable to published applications and is documented here for completeness.

Structure Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IAppPublisher


STRRET

Contains strings returned from the IShellFolder interface methods.

typedef struct _STRRET {
   UINT uType;
   union
   {
      LPWSTR pOleStr;
      LPSTR pStr;
      UINT uOffset;
      char cStr[MAX_PATH];
   } DUMMYUNIONNAME;
} STRRET, *LPSTRRET;

Members

uType
Value that specifies the desired format of the string. This can be one of the following values:
STRRET_CSTR | The string is returned in the cStr member.
STRRET_OFFSET | The uOffset member value indicates the number of bytes from the beginning of the item identifier list where the string is located.
STRRET_WSTR | The string is at the address pointed to in the pOleStr member.
pOleStr
Address of the OLE string. This memory must be allocated with the Shell's allocator (see SHGetMalloc). It is the calling application's responsibility to free this memory when it is no longer needed. The Shell's allocator must be used to free the memory.
pStr
This member is not used.
uOffset
Offset into item identifier list.
cStr
Buffer to receive the display name.

See Also

IShellFolder::GetDisplayNameOf

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


SV2CVW2_PARAMS

Holds the parameters for the IShellView2::CreateViewWindow2 method.

typedef struct _SV2CVW2_PARAMS
{
    DWORD cbSize;
    IShellView *psvPrev;
    LPFOLDERSETTINGS pfs;
    IShellBrowser *psbOwner;
    RECT *prcView;
    SHELLVIEWID const *pvid;
    HWND hwndView;
} SV2CVW2_PARAMS, *LPSV2CVW2_PARAMS;

Members

cbSize
Size of the structure.
psvPrev
Pointer to the IShellView interface of the previous view. A Shell View can use this parameter to communicate with a previous view with the same implementation. It can also be used to optimize browsing between like views. This parameter may be NULL.
pfs
FOLDERSETTINGS structure with information needed to create the view.
psbOwner
Pointer to the current instance of the IShellBrowser interface of the parent Shell browser. CreateViewWindow2 should call this interface's AddRef method and store the interface pointer. It can be used for communication with the Windows® Explorer window.
prcView
RECT structure that defines the view's display region.
pvid
View mode's globally unique identifier (GUID).
hwndView
Window handle for the new Shell View.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


URLINVOKECOMMANDINFO

Contains information for use with the IUniformResourceLocator method.

typedef struct  {
    DWORD    dwcbSize;
    DWORD    dwFlags;
    HWND     hwndParent;
    LPCSTR  pcszVerb;
} URLINVOKECOMMANDINFO, *PURLINVOKECOMMANDINFO;

Members

dwcbSize
Size of this structure, in bytes.
dwFlags
Flag value that specifies how the IUniformResourceLocator::InvokeCommand method will execute. This value can be a combination of the following:
IURL_INVOKECOMMAND_FL_ALLOW_UI
Interaction with the user is allowed and the hwndParent member of this structure is valid. If this is not set, interaction with the user is not allowed and the hwndParent member is ignored.
IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB
Default verb for the Internet Shortcut's protocol is to be used and the pcszVerb member is ignored. If this bit is not set, the verb is specified by pcszVerb.
hwndParent
Handle to the parent window. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.
pcszVerb
Address of a zero-terminated string that contains the verb to be invoked by IUniformResourceLocator::InvokeCommand. If dwFlags is set to IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB, this member is ignored.

Requirements

Version 4.00 and later of Shell32.dll

Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


WALLPAPEROPT

Contains the wallpaper options.

typedef struct _tagWALLPAPEROPT {
    DWORD dwSize;
    DWORD dwStyle;
} WALLPAPEROPT;

Members

dwSize
Unsigned long integer value that contains the size of the WALLPAPEROPT structure.
dwStyle
Unsigned long integer value that contains the wallpaper style. Can be one of the following values:
WPSTYLE_CENTER
WPSTYLE_TILE
WPSTYLE_STRETCH
WPSTYLE_MAX

Requirements

Version 4.71 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 4.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.


SOARCINFO

Contains information that defines the arc to be drawn.

Syntax

typedef struct SOARCINFOtag {
    SORECT Rect;
    SOANGLE StartAngle;
    SOANGLE EndAngle;
} SOARCINFO, VWPTR *PSOARCINFO;

Members

Rect
Rectangle that bounds the ellipse containing the arc.
StartAngle
Angle specifying the starting point of the arc. The angle is defined in tenths of a degree, counterclockwise from the positive x-axis. To set this member, use the SOANGLETENTHS macro.
EndAngle
Angle specifying the ending point of the arc. The angle is defined in tenths of a degree, counterclockwise from the positive x-axis. To set this member, use the SOANGLETENTHS macro.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOBITMAPHEADER

Contains information about the bitmap to be output.

typedef struct SOBITMAPHEADERtag {
    WORD wStructSize;
    WORD wImageFlags;
    WORD wImageWidth;
    WORD wImageLength;
    WORD wTileWidth;
    WORD wTileLength;
    WORD wBitsPerPixel;
    WORD wNPlanes;
    WORD wHDpi;
    WORD wVDpi;
} SOBITMAPHEADER, VWPTR *PSOBITMAPHEADER;

Members

wStructSize
Size, in bytes, of the structure.
wImageFlags
Image flags. This member can be one (and only one) of the color format values combined with one or more of the other attribute values.
The color format can be one of these values:
SO_BGRCOLOR | Pixel values are RGB color values (24-bit only); bytes are stored consecutively in the order B,G,R.
SO_BLACKANDWHITE | Pixels are black or white (1 bit per pixel only).
SO_COLORPALETTE | Pixel values are indexes into the color palette for the bitmap.
SO_GRAYSCALE | Pixel values are gray scale values.
SO_RGBCOLOR | Pixel values are RGB color values (24-bit only); bytes are stored consecutively in the order R,G,B.
Other attributes can be a combination of these values:
SO_BOTTOMTOTOP | The image is provided in scan lines from the bottom up. The default is top to bottom.
SO_WHITEZERO | For gray scale images and black-and-white images only, a pixel with a value of zero is a white pixel, and increasing pixel values become darker. By default, a value of zero is defined as a black pixel with increasing values becoming lighter.
wImageWidth
Width, in pixels, of the image.
wImageLength
Height, in pixels, of the image.
wTileWidth
Width, in pixels, of the tile.
wTileLength
Height, in pixels, of the tile.
wBitsPerPixel
Number of consecutive bits that define the pixel color. The number is currently limited to 1, 4, 8, or 24.
wNPlanes
Color planes. This member must be 1.
wHDpi
Horizontal resolution, in pixels per inch, of the display on which the image originated. If the resolution is not known, this member can be zero.
wVDpi
Vertical resolution, in pixels per inch, of the display on which the image originated. If the resolution is not known, this member can be zero.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOBORDER

Contains information about the border around a cell in table.

typedef struct SOBORDERtag {
    WORD wWidth;
    SOCOLORREF rgbColor;
    WORD wFlags;
} SOBORDER, VWPTR * PSOBORDER;

Members

wWidth
Width, in TWIPS, of the border.
rgbColor
Color of the border. This member can be an RGB color value. To set this member, use the SORGB macro.
wFlags
Type of border and the edges to which it applies. This member can be a combination of the following values:
SO_BORDERNONE
SO_BORDERDOUBLE
SO_BORDERHAIRLINE
SO_BORDERTHICK
SO_BORDERSHADOW
SO_BORDERDOTTED

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOCOLUMN

Contains information about the columns that are contained in a spreadsheet.

typedef struct SOCOLUMNtag {
    WORD wStructSize;
    LONG dwWidth;
    char szName[40];
} SOCOLUMN, VWPTR * PSOCOLUMN;

Members

wStructSize
Size, in bytes, of the structure.
dwWidth
Width, in characters, of the column.
szName
Null-terminated string specifying the name of the column.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOCPARCANGLE

Contains information defining an arc for use in vector graphics output.

Syntax

typedef struct SOCPARCANGLEtag {
    SOPOINT Center;
    SOANGLE SweepAngle;
} SOCPARCANGLE, VWPTR *PSOCPARCANGLE;

Members

Center
Center point of the arc.
SweepAngle
Sweep angle of the arc.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOCPPIEANGLE

Contains information defining a pie shape for use in vector graphics output.

Syntax

typedef struct SOCPPIEANGLEtag {
    INT nRadius;
    SOANGLE StartAngle;
    SOANGLE SweepAngle;
} SOCPPIEANGLE, VWPTR *PSOCPPIEANGLE;

Members

nRadius
Radius of the pie shape.
StartAngle
Starting angle of the pie shape.
SweepAngle
Sweep angle of the pie shape.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOCPTEXTATPOINT

Contains information defining the format and length of text for use in vector graphics output.

Syntax

typedef struct SOCPTEXTATPOINTtag {
    WORD wFormat;
    INT nTextLength;
} SOCPTEXTATPOINT, VWPTR *PSOCPTEXTATPOINT;

Members

wFormat
Format of the text.
nTextLength
Text length, in characters.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SODATACELL

Contains information about the data to be placed in a cell of a spreadsheet.

typedef struct SODATACELLtag {
    WORD wStructSize;
    WORD wStorage;
    WORD wDisplay;
    DWORD dwSubDisplay;
    WORD wPrecision;
    WORD wAlignment;
    WORD wAttribute;
    union {
        SOINT32S Int32S;
        SOINT32U Int32U;
        BYTE IEEE4[4];
        BYTE IEEE8[8];
        BYTE IEEE10[10];
        BYTE BCD8[8];
    } uStorage;
} SODATACELL, VWPTR * PSODATACELL;

Members

wStructSize
Size, in bytes, of the structure.
wStorage
Storage type. This member can be one of these values:
SO_CELLBCD8I | Packed BCD excess-63. See BCD8 for more information.
SO_CELLEMPTY | The cell is empty.
SO_CELLERROR | The cell has an error condition.
SO_CELLIEEE4I | IEEE 4-byte in Intel® (PC) ordering. See IEEE4 for more information.
SO_CELLIEEE8I | IEEE 8-byte in Intel (PC) ordering. See IEEE8 for more information.
SO_CELLIEEE10I | IEEE 10-byte in Intel (PC) ordering. See IEEE10 for more information.
SO_CELLINT32S | 32-bit signed integer. See Int32S for more information.
SO_CELLINT32U | 32-bit unsigned integer. See Int32U for more information.
wDisplay
Display type. This member can be one of these values:
SO_CELLBOOL | Boolean (0 = FALSE and 1 = TRUE).
SO_CELLDATE | Julian days since the base date. wStorage may be either an IEEE or integer value.
SO_CELLDATETIME | Julian days since the base date. wStorage may be either an IEEE or integer value.
SO_CELLDECIMAL | Decimal notation.
SO_CELLDOLLARS | Dollar sign.
SO_CELLEXPONENT | Exponential notation.
SO_CELLNUMBER | General number format.
SO_CELLPERCENT | Percent (not constrained to 0–100).
SO_CELLTIME | Decimal part of a day if wStorage is an IEEE value, or seconds since 00:00 if wStorage is an integer value.
dwSubDisplay
Display subtype. The values depend on wDisplay value.

For SO_CELLNUMBER and SO_CELLDOLLARS, this member can be a combination of one negative-number format, thousands separator, and cell multiplier.
Negative Number Format
SO_CELLNEG_MINUS | Negative numbers have a minus sign.
SO_CELLNEG_MINUSRED | Negative numbers have a minus sign and are red.
SO_CELLNEG_PAREN | Negative numbers have parentheses.
SO_CELLNEG_PARENRED | Negative numbers have parentheses and are red.
Thousands Separator
SO_CELL1000SEP_COMMA | Comma as thousands separator.
SO_CELL1000SEP_NONE | No thousands separator.
Cell Multiplier
SO_CELLMULT_1 | Used for all file parsers.
SO_CELLMULT_01 | Used only for Microsoft® Excel viewer.
SO_CELLMULT_05 | Used only for Lotus viewer.
SO_CELLMULT_005 | Used only for Lotus viewer.
SO_CELLMULT_0005 | Used only for Lotus viewer.
SO_CELLMULT_00005 | Used only for Lotus viewer.
SO_CELLMULT_500 | Used only for Lotus viewer.
SO_CELLMULT_5000 | Used only for Lotus viewer.
SO_CELLMULT_0625 | Used only for Lotus viewer.
SO_CELLMULT_015625 | Used only for Lotus viewer.

For SO_CELLDATETIME, SO_CELLDATE, and SO_CELLTIME, this member can be a combination of one date separator, day format, month format, year format, day of week format, and time format.
Date Separator
SO_CELLDATESEP_MINUS
SO_CELLDATESEP_NONE
SO_CELLDATESEP_PERIOD
SO_CELLDATESEP_SPACE
Day Format
SO_CELLDAY_NONE
SO_CELLDAY_NUMBER
Month Format
SO_CELLMONTH_ABBREV
SO_CELLMONTH_FULL
SO_CELLMONTH_NONE
SO_CELLMONTH_NUMBER
Year Format
SO_CELLYEAR_ABBREV
SO_CELLYEAR_FULL
SO_CELLYEAR_NONE
Day of Week Format
SO_CELLDAYOFWEEK_ABBREV
SO_CELLDAYOFWEEK_FULL
SO_CELLDAYOFWEEK_NONE
Time Format
SO_CELLTIME_HHMM24
SO_CELLTIME_HHMMAM
SO_CELLTIME_HHMMHMS | For example, 14h45m
SO_CELLTIME_HHMMSS24
SO_CELLTIME_HHMMSSAM
SO_CELLTIME_HHMMSSHMS | For example, 14h45m34s
SO_CELLTIME_NONE

wPrecision
Precision or positioning value, depending on the wDisplay value.

For SO_CELLNUMBER and SO_CELLDOLLARS, this member specifies the number of places to the right of the decimal point.

For SO_CELLDATETIME, SO_CELLDATE, and SO_CELLTIME, this member specifies the position in the date/time string of each element. It must contain one value for each of these: day of week position, month position, day position, year position, and time position.
Day of Week Position
SO_CELLDAYOFWEEK_1
SO_CELLDAYOFWEEK_2
SO_CELLDAYOFWEEK_3
SO_CELLDAYOFWEEK_4
SO_CELLDAYOFWEEK_5
Month Position
SO_CELLMONTH_1
SO_CELLMONTH_2
SO_CELLMONTH_3
SO_CELLMONTH_4
SO_CELLMONTH_5
Day Position
SO_CELLDAY_1
SO_CELLDAY_2
SO_CELLDAY_3
SO_CELLDAY_4
SO_CELLDAY_5
Year Position
SO_CELLYEAR_1
SO_CELLYEAR_2
SO_CELLYEAR_3
SO_CELLYEAR_4
SO_CELLYEAR_5
Time Position
SO_CELLTIME_1
SO_CELLTIME_2
SO_CELLTIME_3
SO_CELLTIME_4
SO_CELLTIME_5

wAlignment
Alignment of data in the cell. This member can be the SO_CELLLEFT, SO_CELLRIGHT, or SO_CELLCENTER value.
wAttribute
Attribute of data in the cell. This member can be a combination of the SO_CELLBOLD, SO_CELLITALIC, SO_CELLUNDERLINE, and SO_CELLSTRIKEOUT values.
Int32S
Signed 32-bit integer.
Int32U
Unsigned 32-bit integer.
IEEE4
4-byte array representing an IEEE 4-byte floating-point number.
IEEE8
8-byte array representing an IEEE 8-byte floating-point number.
IEEE10
10-byte array representing an IEEE 10-byte floating-point number.
BCD8
8-byte array representing an excess-63 floating-point packed BCD.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEMBEDDEDGRAPHIC

Contains information about the size and positioning of an embedded graphics object.

typedef struct SOEMBEDDEDGRAPHICtag {
    SOPOINT Size;
    SORECT Crop;
    SOPOINT ScaledSize;
    WORD wBorder;
    DWORD dwFlags;
} SOEMBEDDEDGRAPHIC;

Members

Size
Initial size of the image before scaling and cropping.
Crop
Cropping amount on the top, bottom, left, and right edges.
ScaledSize
Final size of the image after scaling and cropping.
wBorder
Border thickness, in TWIPs. If this member is zero, there is no border.
dwFlags
Flags. This member can be one or both of these values:
SO_CENTERIMAGE | The image is centered in its final rectangle.
SO_MAINTAINASPECT | The image aspect ratio is preserved.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEMBEDDEDOBJECT

Contains information about an embedded object.

typedef struct SOEMBEDDEDOBJECTtag {
    WORD wStructSize;
    WORD wObjectType;
    char szFile[144];
    WORD wFIType;
    DWORD dwFileOffset;
    SOEMBEDINFO Info;
} SOEMBEDDEDOBJECT, VWPTR * PSOEMBEDDEDOBJECT;

Members

wStructSize
Size, in bytes, of the structure.
wObjectType
Type of object. This member can be the SOEMBED_GRAPHIC or SO_UNKNOWN value.
szFile
Null-terminated string specifying the path and file name of the file that contains the object. If the object is in the current file, this member is NULL.
wFIType
Identifier for the object's file. If the object type is the SO_UNKNOWN value, this member is zero.
dwFileOffset
Offset, in bytes, to the embedded object from the start of the given file.
Info
Union containing object-specific information.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOEMBEDINFO

Contains information specific to embedded graphics objects.

typedef union SOEMBEDINFOtag {
    SOEMBEDDEDGRAPHIC Graphic;
} SOEMBEDINFO;

Members

Graphic
SOEMBEDDEDGRAPHIC structure that defines the embedded graphic object.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOFIELD

Contains information about a field in a database.

typedef struct SOFIELDtag {
    WORD wStructSize;
    LONG dwWidth;
    char szName[40];
    WORD wStorage;
    WORD wDisplay;
    DWORD dwSubDisplay;
    WORD wPrecision;
    WORD wAlignment;
} SOFIELD, VWPTR * PSOFIELD;

Members

wStructSize
Size, in bytes, of the structure.
dwWidth
Width, in characters, of the column.
szName
Null-terminated string specifying the name of the field.
wStorage
Storage type. This member can be one of these values:
SO_CELLBCD8I | Packed BCD excess-63. See BCD8 for more information.
SO_CELLEMPTY | The cell is empty.
SO_CELLERROR | The cell has an error condition.
SO_CELLIEEE4I | IEEE 4-byte in Intel® (PC) ordering. See IEEE4 for more information.
SO_CELLIEEE8I | IEEE 8-byte in Intel (PC) ordering. See IEEE8 for more information.
SO_CELLIEEE10I | IEEE 10-byte in Intel (PC) ordering. See IEEE10 for more information.
SO_CELLINT32S | 32-bit signed integer. See Int32S for more information.
SO_CELLINT32U | 32-bit unsigned integer. See Int32U for more information.
SO_FIELDTEXTFIX | The field contains a string of fixed length.
SO_FIELDTEXTVAR | The field contains a string of unknown length.
wDisplay
Display type. For more information, see the wDisplay member in the SODATACELL structure.
dwSubDisplay
Display subtype. For more information, see the dwSubDisplay member in the SODATACELL structure.
wPrecision
Precision or positioning value. For more information, see the wPrecision member in the SODATACELL structure.

If wStorage is the SO_FIELDTEXTFIX value, this member specifies the number of characters in the string.

wAlignment
Alignment of data in the cell. This member can be the SO_CELLLEFT, SO_CELLRIGHT, or SO_CELLCENTER value.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOFILTERINFO

Contains information identifying the file parser.

Syntax

typedef struct SOFILTERINFOtag {
    INT wFilterCharSet;
    U_BYTE szFilterName[32];
} SOFILTERINFO;

Members

wFilterCharSet
Character set used for text by the file parser. This member must be the SO_WINDOWS value.
szFilterName
Null-terminated string specifying the name of the file parser. The name should identify either the format of the files being parsed or the product that created the files.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOGROUPINFO

Contains information about a group for use with vector graphics output.

typedef struct SOGROUPINFOtag {
    WORD wStructSize;
    SORECT BoundingRect;
    INT nTransforms;
} SOGROUPINFO, VWPTR *PSOGROUPINFO;

Members

wStructSize
Size, in bytes, of the structure.
BoundingRect
Rectangle that bounds all points displayed in the group. This rectangle does not cause clipping to occur. If clipping is needed, a clipping path must be selected.
nTransforms
Number of transformation structures following this structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOLOGBRUSH

Contains information defining a logical brush for use with vector graphics output.

typedef struct SOLOGBRUSHtag {
    WORD lbStyle;
    SOCOLORREF lbColor;
    INT lbHatch;
} SOLOGBRUSH, VWPTR *PSOLOGBRUSH;

Members

lbStyle
Brush style. This member can be one of the following values:
SOBS_HATCHED | Hatched brush.
SOBS_HOLLOW | Hollow brush.
SOBS_SOLID | Solid brush.
lbColor
Color of the brush. This member can be an RGB or palette-relative value. To set this member, use the SORGB or SOPALETTERGB macro.
lbHatch
Hatch style. This member is used only if lbStyle is SO_HATCHED. This member can be one of the following values:
SOHS_BDIAGONAL | A 45-degree upward, left-to-right hatch.
SOHS_CROSS | Horizontal and vertical cross-hatch.
SOHS_DIAGCROSS | 45-degree cross-hatch.
SOHS_FDIAGONAL | A 45-degree downward, left-to-right hatch.
SOHS_HORIZONTAL | Horizontal hatch.
SOHS_VERTICAL | Vertical hatch.

See Also

LOGBRUSH

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOLOGFONT

Contains information that defines a logical font for use with vector graphics output.

Syntax

typedef struct SOLOGFONTtag {
    INT lfHeight;
    INT lfWidth;
    INT lfEscapement;
    INT lfOrientation;
    INT lfWeight;
    BYTE lfItalic;
    BYTE lfUnderline;
    BYTE lfStrikeOut;
    BYTE lfCharSet;
    BYTE lfOutputPrecision;
    BYTE lfClipPrecision;
    BYTE lfQuality;
    BYTE lfPitchAndFamily;
    BYTE lfFaceName[SOLF_FACESIZE];
} SOLOGFONT, VWPTR *PSOLOGFONT;

Remarks

For a description of the members, see the LOGFONT structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOLOGPEN

Contains information that defines a logical pen for use with vector graphics output.

Syntax

typedef struct SOLOGPENtag {
    INT loPenStyle;
    SOPOINT loWidth;
    SOCOLORREF loColor;
} SOLOGPEN, VWPTR *PSOLOGPEN;

Members

loPenStyle
Pen style. This member can be the SOPS_SOLID, SOPS_DASH, SOPS_DOT, SOPS_DASHDOT, SOPS_DASHDOTDOT, SOPS_NULL, or SOPS_INSIDEFRAME value.
loWidth
Width, in logical units, of the pen. The x member in the POINT structure is used, and the y member is ignored.
loColor
Color of the brush. This member can be an RGB or palette-relative value. To set this member, use the SORGB or SOPALETTERGB macro.

Remarks

For a complete definition of the members, see the LOGPEN structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPARAINDENTS

Contains information about paragraph indents for use with vector graphics output.

Syntax

typedef struct SOPARAINDENTStag {
    INT FirstLineIndent;
    INT LeftIndent;
    INT RightIndent;
} SOPARAINDENTS, VWPTR *PSOPARAINDENTS;

Members

FirstLineIndent
Distance, from the left edge of the frame, to indent the first line of each paragraph.
LeftIndent
Distance, from the left edge of the frame, to indent all lines but the the first line of each paragraph.
RightIndent
Distance, from the right edge of the frame, to indent all lines of each paragraph.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPATHINFO

Contains information about a path for use with vector graphics output.

Syntax

typedef struct SOPATHINFOtag {
    WORD wStructSize;
    SORECT BoundingRect;
    INT nTransforms;
} SOPATHINFO, VWPTR *PSOPATHINFO;

Members

wStructSize
Size, in bytes, of the structure.
BoundingRect
Rectangle that bounds all points displayed in the path. This rectangle does not cause clipping to occur. If clipping is needed, a clipping path must be selected.
nTransforms
Number of transformation structures following this structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPOINT

Contains coordinates for a point.

typedef struct SOPOINTtag {
    INT x;
    INT y;
} SOPOINT, VWPTR *PSOPOINT;

Members

x
X-coordinate for the point.
y
Y-coordinate for the point.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOPOLYINFO

Contains information about the format type and the number of vertices of a polyline, polygon, spline, or Bezier curve.

typedef struct SOPOLYINFOtag {
    WORD wFormat;
    INT nPoints;
} SOPOLYINFO, VWPTR *PSOPOLYINFO;

Members

wFormat
Format type. This member can be one of these values:
SOPT_BEZIERCLOSE
SOPT_POLYGON
SOPT_BEZIEROPEN
SOPT_POLYLINE
SOPT_CPPOLYGON
SOPT_SPLINECLOSE
SOPT_CPPOLYLINE
SOPT_SPLINEOPEN
nPoints
Number of vertices in the object.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SORECT

Contains the dimensions of a rectangle.

typedef struct SORECTtag {
    INT left;
    INT top;
    INT right;
    INT bottom;
} SORECT, VWPTR *PSORECT;

Members

left
X-coordinate of upper left corner.
top
Y-coordinate of upper left corner.
right
X-coordinate of lower right corner.
bottom
Y-coordinate of lower right corner.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTAB

Contains information about tab stops.

typedef struct SOTABtag {
    WORD wType;
    WORD wChar;
    WORD wLeader;
    LONG dwOffset;
} SOTAB, VWPTR * PSOTAB;

Members

wType
Type of tab stop. This member can be the SO_TABLEFT, SO_TABRIGHT, SO_TABCENTER, or SO_TABCHAR value.
wChar
Alignment character if wType is SO_TABCHAR. Tabs are aligned on this character.
wLeader
Repeating leader character for the tab. If this member is zero, there is no leader.
dwOffset
Offset of the tab from the left page margin.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTABLECELLINFO

Contains information about cells in a table.

typedef struct SOTABLECELLINFOtag {
    WORD wWidth;
    WORD wMerge;
    WORD wShading;
    PSOBORDER pLeftBorder;
    PSOBORDER pRightBorder;
    PSOBORDER pTopBorder;
    PSOBORDER pBottomBorder;
} SOTABLECELLINFO, VWPTR *PSOTABLECELLINFO;

Members

wWidth
Width, in TWIPs, of the cell.
wMerge
Merge flag specifying whether the cell is merged with any neighboring cells. This member can be a combination of the SO_MERGELEFT, SO_MERGERIGHT, SO_MERGEABOVE, and SO_MERGEBELOW values.
wShading
Intensity value for background shading in the range of 0 to 255. If this member is zero, there is no background shading.
pLeftBorder
Left border.
pRightBorder
Right border.
pTopBorder
Top border.
pBottomBorder
Bottom border.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTEXTATARCANGLE

Contains information about text for use with vector graphics output.

typedef struct SOTEXTATARCANGLEtag {
    SOARCINFO ArcInfo;
    WORD wFormat;
    INT nTextLength;
} SOTEXTATARCANGLE, VWPTR *PSOTEXTATARCANGLE;

Members

ArcInfo
Arc information that defines the bounding rectangle of the arc relative to the text baseline. Only the starting angle is used to locate the point; the ending angle is ignored.
wFormat
Alignment format, which indicates the relationship between the given point and the base line or bounding rectangle of the text. This member can be a combination of these values:
SOTA_BASELINE | Aligns the point and base line of the font.
SOTA_BOTTOM | Aligns the point and bottom of the bounding rectangle.
SOTA_CENTER | Aligns the point and horizontal center of the bounding rectangle.
SOTA_LEFT | Aligns the point and left side of the bounding rectangle.
SOTA_RIGHT | Aligns the point and right side of the bounding rectangle.
SOTA_TOP | Aligns the point and top of the bounding rectangle.
nTextLength
Length of the text string that follows the structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTEXTATPOINT

Contains information about text at a point.

typedef struct SOTEXTATPOINTtag {
    SOPOINT Point;
    WORD wFormat;
    INT nTextLength;
} SOTEXTATPOINT, VWPTR *PSOTEXTATPOINT;

Members

Point
Point that locates the text.
wFormat
Alignment format, which indicates the relationship between the point and the base line or bounding rectangle of the text. This member can be a combination of these values:
SOTA_BASELINE | Aligns the point and base line of the font.
SOTA_BOTTOM | Aligns the point and bottom of the bounding rectangle.
SOTA_CENTER | Aligns the point and horizontal center of the bounding rectangle.
SOTA_LEFT | Aligns the point and left side of the bounding rectangle.
SOTA_RIGHT | Aligns the point and right side of the bounding rectangle.
SOTA_TOP | Aligns the point and top of the bounding rectangle.
nTextLength
Length of the text string that follows the structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTEXTCELL

Contains information about the alignment and attributes of text in a spreadsheet cell.

typedef struct SOTEXTCELLtag {
    WORD wStructSize;
    WORD wAlignment;
    WORD wAttribute;
} SOTEXTCELL, VWPTR * PSOTEXTCELL;

Members

wStructSize
Size, in bytes, of the structure.
wAlignment
Alignment. This member can be one of the following values:
SO_CELLLEFT | Indicates the text is aligned left within the cell.
SO_CELLRIGHT | Indicates the text is aligned right within the cell.
SO_CELLCENTER | Indicates the text is centered within the cell.
SO_CELLFILL | Indicates the text is aligned to fill the cell.
wAttribute
Attributes. This member can be a combination of the following values:
SO_CELLBOLD | Indicates the text is bold.
SO_CELLITALIC | Indicates the text is italic.
SO_CELLUNDERLINE | Indicates the text is underlined.
SO_CELLSTRIKEOUT | Indicates the text is drawn as strikeout.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTEXTINRECT

Contains information about text for use with vector graphics output.

typedef struct SOTEXTINRECTtag {
    SORECT Rect;
    WORD wFormat;
    INT nTextLength;
} SOTEXTINRECT, VWPTR *PSOTEXTINRECT;

Members

Rect
Rectangle in which text is formatted.
wFormat
Format of the string. This member can be a combination of these values:
SODT_BOTTOMSODT_NOPREFIX
SODT_CALCRECTSODT_RIGHT
SODT_CENTERSODT_SINGLELINE
SODT_EXPANDTABSSODT_TABSTOP
SODT_EXTERNALLEADINGSODT_TOP
SODT_LEFTSODT_VCENTER
SODT_NOCLIPSODT_WORDBREAK
nTextLength
Length of the text string that follows the structure.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOTRANSFORM

Contains information about a transformation for use with vector graphics output.

typedef struct SOTRANSFORMtag {
    WORD wTransformFlags;
    SOPOINT Origin;
    INT xOffset;
    INT yOffset;
    SORATIO xScale;
    SORATIO yScale;
    SORATIO xSkew;
    SORATIO ySkew;
    SOANGLE RotationAngle;
} SOTRANSFORM, VWPTR *PSOTRANSFORM;

Members

wTransformFlags
Type of transformation. This member can be a combination of these values:
SOTF_NOTRANSFORM | SOTF_XSKEW
SOTF_ROTATE | SOTF_YOFFSET
SOTF_XOFFSET | SOTF_YSCALE
SOTF_XSCALE | SOTF_YSKEW

SOTF_ROTATE may be combined only with SOTF_XOFFSET and SOTF_YOFFSET. Also, no other values may be combined with SOTF_NOTRANSFORM.

Origin
Point of origin for all transformations except SOTF_XOFFSET and SOTF_YOFFSET.
xOffset and yOffset
Offset values to use for the SOTF_XOFFSET and SOTF_YOFFSET transformations. The x and y members of this value are added to the x- and y-coordinates of all points in the transformed object.
xScale
Ratio to use for SOTF_XSCALE transformations. This ratio is used to scale the image on the x-axis from the given origin. To set this member, use the SOSETRATIO macro.
yScale
Ratio to use for SOTF_YSCALE transformations. This ratio is used to scale the image on the y-axis from the given origin. To set this member, use the SOSETRATIO macro.
xSkew
Ratio to use for SOTF_XSKEW transformations. This ratio is used to skew the image horizontally from the given origin. To set this member, use the SOSETRATIO macro.
ySkew
Ratio to use for SOTF_YSKEW transformations. This ratio is used to skew the image vertically from the given origin. To set this member, use the SOSETRATIO macro.
RotationAngle
Angle, in tenths of a degree, to use for SOTF_ROTATE transformations. All points are rotated this number of degrees about the given origin. This value must be set by using the SOANGLETENTHS macro. A SOANGLE variable should not be set directly.

The transformation equation follows:

x' = Origin.x + (xScale * (x-Origin.x)) + (xSkew*(y-Origin.y)) + xOffset
y' = Origin.y + (yScale * (y-Origin.y)) + (ySkew*(x-Origin.x)) + yOffset

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


SOVECTORHEADER

Contains information defining the size and attributes of the rectangle in which vector graphics are drawn.

typedef struct SOVECTORHEADERtag {
    WORD wStructSize;
    SORECT BoundingRect;
    WORD wHDPI;
    WORD wVDPI;
    WORD wImageFlags;
    SOCOLOR BkgColor;
} SOVECTORHEADER, VWPTR *PSOVECTORHEADER;

Members

wStructSize
Size, in bytes, of the structure.
BoundingRect
Rectangle that bounds all drawing commands.
wHDpI
Dots-per-inch resolution along the x-axis.
wVDpI
Dots-per-inch resolution along the y-axis.
wImageFlags
Image flags. This member can be a combination of these values:
SO_VECTORCOLORPALETTE | Uses a color palette. Color values must be palette entry indexes or palette-relative RGB values.
SO_VECTORRGBCOLOR | Uses RGB color values.
SO_XISLEFT | Has positive x-coordinates left of the y-axis.
SO_YISUP | Has positive y-coordinates up from the x-axis.
BkgColor
Color of the background in the bounding rectangle. This value must be set by using one of the three color macros: SOPALETTEINDEX, SORGB, or SOPALETTERGB. However, SORGB should not be used if a palette is defined.

Requirements

Windows NT: Supported by Windows NT 4.0. Not supported by Windows 2000.
Windows: Supported by Windows 95. Not supported by Windows 98 or Windows Me.


APPINFODATAFLAGS Enumerated Type

This is preliminary documentation and is subject to change.

Specifies application information to return from IShellApp::GetAppInfo. These flags are bit masks used in the dwMask member of the APPINFODATA structure.

Syntax

typedef enum {
    AIM_DISPLAYNAME = 0x00000001,
    AIM_VERSION = 0x00000002,
    AIM_PUBLISHER = 0x00000004,
    AIM_PRODUCTID = 0x00000008,
    AIM_REGISTEREDOWNER = 0x00000010,
    AIM_REGISTEREDCOMPANY = 0x00000020,
    AIM_LANGUAGE = 0x00000040,
    AIM_SUPPORTURL = 0x00000080,
    AIM_SUPPORTTELEPHONE = 0x00000100,
    AIM_HELPLINK = 0x00000200,
    AIM_INSTALLLOCATION = 0x00000400,
    AIM_INSTALLSOURCE = 0x00000800,
    AIM_INSTALLDATE = 0x00001000,
    AIM_REQUIREDBYPOLICY = 0x00002000,
    AIM_CONTACT = 0x00004000,
    AIM_COMMENTS = 0x00008000,
    AIM_IMAGE = 0x00020000,
    AIM_READMEURL = 0x00040000,
    AIM_UPDATEINFOURL = 0x00080000
} APPINFODATAFLAGS;

Constants

AIM_DISPLAYNAME

Return the display name.

AIM_VERSION

Return the version.

AIM_PUBLISHER

Return the application publisher.

AIM_PRODUCTID

Return the application's product identifier (ID).

AIM_REGISTEREDOWNER

Return the application's registered owner.

AIM_REGISTEREDCOMPANY

Return the application's registered company.

AIM_LANGUAGE

Return the language.

AIM_SUPPORTURL

Return the support URL.

AIM_SUPPORTTELEPHONE

Return the support telephone number.

AIM_HELPLINK

Return the Help link.

AIM_INSTALLLOCATION

Return the application's install location.

AIM_INSTALLSOURCE

Return the install source.

AIM_INSTALLDATE

Return the application's install date.

AIM_REQUIREDBYPOLICY

Obsolete.

AIM_CONTACT

Return the application's contact information.

AIM_COMMENTS

Return application comments.

AIM_IMAGE

Return the application image.

AIM_READMEURL

Return the URL of the application's ReadMe file.

AIM_UPDATEINFOURL

Return the URL of the application's update information.

Remarks

The Add/Remove Programs control panel applet only uses AIM_DISPLAYNAME and AIM_SUPPORTURL.

Enumerated Type Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler


APPACTIONFLAGS Enumerated Type

This is preliminary documentation and is subject to change.

Specifies application management actions supported by an application publisher. These flags are bit masks passed to IShellApp::GetPossibleActions.

Syntax

typedef enum {
    APPACTION_INSTALL = 0x00000001,
    APPACTION_UNINSTALL = 0x00000002,
    APPACTION_MODIFY = 0x00000004,
    APPACTION_REPAIR = 0x00000008,
    APPACTION_UPGRADE = 0x00000010,
    APPACTION_CANGETSIZE = 0x00000020,
    APPACTION_MODIFYREMOVE = 0x00000080,
    APPACTION_ADDLATER = 0x00000100,
    APPACTION_UNSCHEDULE = 0x00000200
} APPACTIONFLAGS;

Constants

APPACTION_INSTALL

The application can be installed. Published applications always set this bit.

APPACTION_UNINSTALL

Not applicable to published applications.

APPACTION_MODIFY

Not applicable to published applications.

APPACTION_REPAIR

Not applicable to published applications.

APPACTION_UPGRADE

Not applicable to published applications.

APPACTION_CANGETSIZE

Not applicable to published applications.

APPACTION_MODIFYREMOVE

Not applicable to published applications.

APPACTION_ADDLATER

The application supports scheduled installation. If this bit is set, the Add/Remove Programs contnrol panel applet will present an Add Later button in the user interface. If you select Add Later, you are prompted to select the desired time of installation. The IPublishedApp::Install method is then called with the installation time.

APPACTION_UNSCHEDULE

Obsolete.

Remarks

The Add/Remove Programs in control panel applet only uses APPACTION_INSTALL and APPACTION_ADDLATER for published applications.

Enumerated Type Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler


ASSOCDATA

Used by IQueryAssociations::GetData to define the type of data that is to be returned.

typedef enum {
    ASSOCDATA_MSIDESCRIPTOR = 1,
    ASSOCDATA_NOACTIVATEHANDLER,
    ASSOCDATA_QUERYCLASSSTORE,
} ASSOCDATA;

Members

ASSOCDATA_MSIDESCRIPTOR
Component descriptor to pass to the Microsoft® Installation API.
ASSOCDATA_NOACTIVATEHANDLER
Attempts to activate a window are restricted. There is no data associated with this value.
ASSOCDATA_QUERYCLASSSTORE
If this value is present, applications should check the Microsoft® Windows® 2000 class store.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


ASSOCF

Used to provide information to the IQueryAssociations interface methods.

enum {
    ASSOCF_INIT_BYEXENAME,
    ASSOCF_OPEN_BYEXENAME,
    ASSOCF_INIT_DEFAULTTOSTAR,
    ASSOCF_INIT_DEFAULTTOFOLDER,
    ASSOCF_NOUSERSETTINGS,
    ASSOCF_NOTRUNCATE,
    ASSOCF_VERIFY,
    ASSOCF_REMAPRUNDLL,
    ASSOCF_NOFIXUPS,
    ASSOCF_IGNOREBASECLASS
};

typedef DWORD ASSOCF;

Members

ASSOCF_INIT_BYEXENAME
Used when the pwszAssoc parameter of IQueryAssociations::Init is set to an executable file name. If this flag is not set in this case, the root key will be set to the ProgID associated with the .exe key instead of the executable file's ProgID.
ASSOCF_OPEN_BYEXENAME
This value is identical to ASSOCF_INIT_BYEXENAME.
ASSOCF_INIT_DEFAULTTOSTAR
If an IQueryAssociations method does not find the requested value under the root key, it will attempt to retrieve the comparable value from the * subkey.
ASSOCF_INIT_DEFAULTTOFOLDER
If an IQueryInterface method does not find the requested value under the root key, it will attempt to retrieve the comparable value from the Folder subkey.
ASSOCF_NOUSERSETTINGS
Only search HKEY_CLASSES_ROOT. Ignore HKEY_CURRENT_USER.
ASSOCF_NOTRUNCATE
Don't truncate the return string. Return an error value and the required size for the complete string.
ASSOCF_VERIFY
Verify that data is accurate. This setting allows IQueryAssociations methods to read data from the user's hard drive. For example, they can check the friendly name in the registry against the one stored in the .exe file. Setting this flag normally reduces the efficiency of the method.
ASSOCF_REMAPRUNDLL
IQueryAssociations methods normally return information about the first .exe or .dll in a command string. If a command uses Rundll.exe, setting this flag tells the method to ignore Rundll.exe and return information about its target.
ASSOCF_NOFIXUPS
Do not fix errors in the registry, such as the friendly name of a function not matching the one found in the .exe file.
ASSOCF_IGNOREBASECLASS
Ignore the BaseClass value.

See Also

AssocQueryKey, AssocQueryString, AssocQueryStringByKey

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


ASSOCKEY

Used to specify the type of key to be returned by IQueryAssociations::GetKey.

typedef enum {
    ASSOCKEY_SHELLEXECCLASS = 1,
    ASSOCKEY_APP,
    ASSOCKEY_CLASS,
    ASSOCKEY_BASECLASS,
} ASSOCKEY;

Members

ASSOCKEY_SHELLEXECCLASS
Key that is passed to ShellExec(hkeyClass).
ASSOCKEY_APP
Application key for the file class.
ASSOCKEY_CLASS
ProgID or class key.
ASSOCKEY_BASECLASS
BaseClass value.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


ASSOCSTR

Used by IQueryAssociations::GetString to define the type of string that is to be returned.

typedef enum {
    ASSOCSTR_COMMAND,
    ASSOCSTR_EXECUTABLE,
    ASSOCSTR_FRIENDLYDOCNAME,
    ASSOCSTR_FRIENDLYAPPNAME,
    ASSOCSTR_NOOPEN,
    ASSOCSTR_SHELLNEWVALUE,
    ASSOCSTR_DDECOMMAND,
    ASSOCSTR_DDEIFEXEC,
    ASSOCSTR_DDEAPPLICATION,
    ASSOCSTR_DDETOPIC,
} ASSOCSTR;

Members

ASSOCSTR_COMMAND
Command string associated with a Shell verb.
ASSOCSTR_EXECUTABLE
Executable from a Shell verb command string. If the command uses Rundll.exe, set the ASSOCF_REMAPRUNDLL flag in the flags parameter of IQueryAssociations::GetString to retrieve the target executable.
ASSOCSTR_FRIENDLYDOCNAME
Friendly name of a document type.
ASSOCSTR_FRIENDLYAPPNAME
Friendly name of an executable.
ASSOCSTR_NOOPEN
Ignore the information associated with the open subkey.
ASSOCSTR_SHELLNEWVALUE
Look under the ShellNew subkey.
ASSOCSTR_DDECOMMAND
Template for DDE commands.
ASSOCSTR_DDEIFEXEC
DDECOMMAND to use to just create a process.
ASSOCSTR_DDEAPPLICATION
Application name in a DDE broadcast.
ASSOCSTR_DDETOPIC
Topic name in a DDE broadcast.

Requirements

Version 5.00 and later of Shlwapi.dll

Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with Internet Explorer 5.0 or later).
Windows 95/98/Me: Requires Windows 98 (or Windows 95 with Internet Explorer 5.0 or later).
Header: Declared in Shlwapi.h.
Import Library: Shlwapi.lib.


CATEGORYINFO_FLAGS Enumerated Type

This is preliminary documentation and is subject to change.

Provides a set of flags for use with the CATEGORY_INFO structure.

Syntax

typedef enum {
    CATINFO_NORMAL = 0x00000000,
    CATINFO_COLLAPSED = 0x00000001,
    CATINFO_HIDDEN = 0x00000002
} CATEGORYINFO_FLAGS;

Constants

CATINFO_NORMAL

Supplies information, such as the name of the category.

CATINFO_COLLAPSED

Not currently implemented.

CATINFO_HIDDEN

Not currently implemented.

Enumerated Type Information

Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


CATSORT_FLAGS Enumerated Type

This is preliminary documentation and is subject to change.

Used to specify methods for sorting category data.

Syntax

typedef enum {
    CATSORT_DEFAULT = 0x00000000,
    CATSORT_NAME = 0x00000001
} CATSORT_FLAGS;

Constants

CATSORT_DEFAULT

Use the default sort.

CATSORT_NAME

Use a method that sorts on category names.

Enumerated Type Information

Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


FOLDERFLAGS

Set of flags used to specify folder view options. They are independent of each other, and can be used in any combination.

typedef enum{
    FWF_AUTOARRANGE,
    FWF_ABBREVIATEDNAMES,
    FWF_SNAPTOGRID,
    FWF_OWNERDATA,
    FWF_BESTFITWINDOW,
    FWF_DESKTOP,
    FWF_SINGLESEL,
    FWF_NOSUBFOLDERS,
    FWF_TRANSPARENT,
    FWF_NOCLIENTEDGE,
    FWF_NOSCROLL,
    FWF_ALIGNLEFT,
    FWF_NOICONS,
    FWF_SHOWSELALWAYS
    FWF_SINGLECLICKACTIVATE,
} FOLDERFLAGS;

Members

FWF_AUTOARRANGE
Automatically arrange the elements in the view. This implies LVS_AUTOARRANGE if the list view control is used to implement the view.
FWF_ABBREVIATEDNAMES
Names should be abbreviated. This flag is not currently supported.
FWF_SNAPTOGRID
Items should be arranged on a grid. This flag is not currently supported.
FWF_OWNERDATA
This flag is not currently supported.
FWF_BESTFITWINDOW
Enable the best-fit window mode. Let the view size the window so that its contents fit inside the view window in the best possible manner.
FWF_DESKTOP
Make the folder behave like the desktop. This value applies only to the desktop view and is not used for typical Shell folders.
FWF_SINGLESEL
Do not allow more than a single item to be selected. This is used in the common dialog boxes.
FWF_NOSUBFOLDERS
Do not show subfolders.
FWF_TRANSPARENT
Draw transparently. This is used only for the desktop.
FWF_NOCLIENTEDGE
Do not add the WS_EX_CLIENTEDGE value to the view. This is used only for the desktop.
FWF_NOSCROLL
Do not add scroll bars. This is used only for the desktop.
FWF_ALIGNLEFT
The view should be left-aligned. This implies LVS_ALIGNLEFT if the list view control is used to implement the view.
FWF_NOICONS
The view should not display icons.
FWF_SHOWSELALWAYS
Always show the selection.
FWF_SINGLECLICKACTIVATE
This flag is not currently supported.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


FOLDERVIEWMODE

Set of constants used to specify the folder view type.

typedef enum {
    FVM_ICON      = 1,
    FVM_SMALLICON = 2,
    FVM_LIST      = 3,
    FVM_DETAILS   = 4
} FOLDERVIEWMODE;

Members

FVM_ICON
The view should display large icons.
FVM_SMALLICON
The view should display small icons.
FVM_LIST
Object names are displayed in a list view.
FVM_DETAILS
Object names and other selected information, such as the size or date last updated, are shown.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


IMAGESTATUS Enumerated Type

This is preliminary documentation and is subject to change.

Used to specify changes in the state of an image associated with an IShellImageData interface.

Syntax

typedef enum {
    ImgStatus_InitialDecodeComplete = 0x00000000,
    ImgStatus_AdditionalFrameComplete = 0x00000001,
    ImgStatus_ImageEdited = 0x00000002
} IMAGESTATUS;

Constants

ImgStatus_InitialDecodeComplete

Decoding of the first page or frame of an image is complete.

ImgStatus_AdditionalFrameComplete

Decoding of an additional page or frame of an image is complete.

ImgStatus_ImageEdited

The image was changed.

Enumerated Type Information

Header and IDL files | shimgdata.h, shimgdata.idl
Minimum operating systems | Whistler

See Also

IShellImageData


IURL_SETURL_FLAGS

The values of this enumeration are used with the IUniformResourceLocator::SetURL to specify the protocol scheme.

typedef enum iurl_seturl_flags{
    IURL_SETURL_FL_GUESS_PROTOCOL,
    IURL_SETURL_FL_USE_DEFAULT_PROTOCOL
}  IURL_SETURL_FLAGS;

Members

IURL_SETURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to IUniformResourceLocator::SetURL, the system automatically chooses a scheme and adds it to the URL.
IURL_SETURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to IUniformResourceLocator::SetURL, the system adds the default protocol to the URL.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


IURL_SETURL_INVOKECOMMAND_FLAGS

The following enumerated values are used in the dwFlags member of the URLINVOKECOMMANDINFO structure.

typedef enum iurl_invokecommand_flags{
    IURL_INVOKECOMMAND_FL_ALLOW_UI           = 0x0001,
    IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB   = 0x0002,
}  IURL_INVOKECOMMAND_FLAGS;

Members

IURL_INVOKECOMMAND_FL_ALLOW_UI
If this bit is set, interaction with the user is allowed and the hwndParent member of the URLINVOKECOMMANDINFO structure is valid. If this bit is clear, interaction with the user is not allowed and the hwndParent member is ignored.
IURL_INVOKECOMMAND_FL_USE_DEFAULT_VERB
If this bit is set, the default verb for the Internet Shortcut's protocol is to be used and the pcszVerb member of the URLINVOKECOMMANDINFO structure is ignored. If this bit is clear, the verb is specified by pcszVerb.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


PUBAPPINFOFLAGS Enumerated Type

This is preliminary documentation and is subject to change.

Specifies which members in the PUBAPPINFO structure are valid. These flags are bit masks set in the dwMask member and passed to IPublishedApp::GetPublishedAppInfo.

Syntax

typedef enum {
    PAI_SOURCE = 0x00000001,
    PAI_ASSIGNEDTIME = 0x00000002,
    PAI_PUBLISHEDTIME = 0x00000004,
    PAI_SCHEDULEDTIME = 0x00000008,
    PAI_EXPIRETIME = 0x00000010
} PUBAPPINFOFLAGS;

Constants

PAI_SOURCE

The pszSource string is valid and contains the display name of the publishing source. If multiple sources publish an application of the same name, Add/Remove Programs identifies them by "<application name> : <publishing source>".

PAI_ASSIGNEDTIME

The stAssigned member is valid and contains the time when the application should be installed as assigned by an application administrator.

PAI_PUBLISHEDTIME

Not used.

PAI_SCHEDULEDTIME

The stScheduled member is valid and contain the time when the application should be installed as assigned by the user.

PAI_EXPIRETIME

The stExpired member is valid and contains the time after which Add/Remove Programs should no longer install the program.

Enumerated Type Information

Header and IDL files | shappmgr.h, shappmgr.idl
Minimum operating systems | Windows 98, Windows NT 2000, Whistler

See Also

IPublishedApp::GetPublishedAppInfo


SHCONTF

Determines the type of items included in an enumeration. These values are used with the IShellFolder::EnumObjects method.

typedef enum tagSHCONTF{
    SHCONTF_FOLDERS,
    SHCONTF_NONFOLDERS,
    SHCONTF_INCLUDEHIDDEN,
    SHCONTF_INIT_ON_FIRST_NEXT,
    SHCONTF_NETPRINTERSRCH,
} SHCONTF;

Members

SHCONTF_FOLDERS
Include items that are folders in the enumeration.
SHCONTF_NONFOLDERS
Include items that are not folders in the enumeration.
SHCONTF_INCLUDEHIDDEN
Include hidden items in the enumeration.
SHCONTF_INIT_ON_FIRST_NEXT
IShellFolder::EnumObjects can return without validating the enumeration object. Validation can be postponed until the first call to IEnumIDList::Next. This flag is intended to be used when a user-interface may be displayed prior to the first IEnumIDList::Next call. For a user-interface to be presented, hwndOwner must be set to a valid window handle.
SHCONTF_NETPRINTERSRCH
The caller is looking for printer objects.

Remarks

By setting the SHCONTF_INIT_ON_FIRST_NEXT flag the caller is suggesting that the IShellFolder::EnumObjects method can expedite the enumeration process by returning an uninitialized enumeration object. Initialization can be deferred until the enumeration process starts. If initialization of the enumeration object will be a lengthy process, the method implementation should immediately return an uninitialized object. Defer initialization until the first time the IEnumIDList::Next method is called. If initialization requires user input, the method implementation should use hwndOwner as the parent window for the user-interface. See the IShellFolder::EnumObjects reference for a discussion of how to handle the case where hwndOwner is set to NULL.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


SHGNO

Defines the values used with the IShellFolder::GetDisplayNameOf and IShellFolder::SetNameOf methods.

typedef enum tagSHGDN {
    SHGDN_NORMAL,
    SHGDN_INFOLDER,
    SHGDN_FOREDITING,
    SHGDN_FORADDRESSBAR,
    SHGDN_FORPARSING,
} SHGNO;

Members

This enumeration consists of two groups of values. The first group specifies the name's type and has two possible values.

SHGDN_NORMAL | Full name. The name is relative to the desktop and not to a specific folder. This name is used for generic display.
SHGDN_INFOLDER | Relative name. The name is relative to the folder that is processing it.

The second group consists of modifiers to the first group that specify name retrieval options. It has the following values.

SHGDN_FOREDITING | The name is used for in-place editing when the user renames the item.
SHGDN_FORADDRESSBAR | The name is displayed in an address bar combo box.
SHGDN_FORPARSING | The name is used for parsing. That is, it can be passed to ParseDisplayName to recover the object's PIDL. The form this name takes depends on the particular object.

Remarks

If SHGDN_FORPARSING is set and SHGDN_INFOLDER is not set, IShellFolder::GetDisplayNameOf can accept a PIDL that contains more than an SHITEMID structure. Otherwise, only a single-level PIDL can be passed.

Note While the parsing name returned by file system objects is the object's fully qualified path, virtual folders might use something quite different. For example, some virtual folders use a GUID as the parsing name and return a string of the form "::{GUID}". To check whether the object is part of the file system, call IShellFolder::GetAttributesOf and see if the SFGAO_FILESYSTEM flag is set. Developers who implement IShellFolder::GetDisplayNameOf are encouraged to return parse names that are as close to the display names as possible, because the end user often needs to type or edit these names.

The numeric value of SHGDN_NORMAL is zero, so you cannot test for the presence of this bit. Consider SHGDN_NORMAL a default setting that is used if no other flag in that group is set.

Example

The following tables illustrate an example of possible return values for five different flag options and three different item types.

These are the flag options.

Number | Flags | Description
1 | SHGNO_NORMAL | SHGNO_FORPARSING | Returns the fully qualified parsing name.
2 | SHGNO_INFOLDER | SHGNO_FORPARSING | Returns the parsing name relative to the parent folder.
3 | SHGNO_INFOLDER | SHGNO_FOREDITING | Returns the editing name relative to the parent folder.
4 | SHGNO_INFOLDER | Returns the display name relative to the parent folder.
5 | SHGNO_NORMAL | Returns the display name relative to the desktop.

These are the sample item types.

Letter | Description
A | The C: drive on the local computer, whose volume label is C_DRIVE.
B | A printer named Laser on a computer called Mailroom.
C | The file C:\Directory\File.txt (when file-name extensions are hidden).

The following table describes the display names as they would be returned.

 | A | B | C
1 | C:\ | \\Mailroom\Laser | C:\Directory\File.txt
2 | C:\ | Laser | File.txt
3 | C_DRIVE | Laser | File
4 | C_DRIVE (C:) | Laser | File
5 | C_DRIVE (C:) | Laser on Mailroom | File
Remarks on examples
  • A3: The C: drive presents its volume name for editing, rather than the entire string "C_DRIVE (C:)".
  • B1-B5: The display name of the remote printer changes depending on whether it is being shown relative to its parent. When shown relative to its parent, it needs only its printer name, but when shown outside its parent, it shows both its printer name and its computer name.
  • C3: File.txt presents only its base name for editing instead of its full name.

For further discussion of the IShellFolder interface, see Getting Information About the Contents of a Folder.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Shlobj.h.


SIGDN Enumerated Type

This is preliminary documentation and is subject to change.

Used to request the type of display name to return.

Syntax

typedef enum {
    SIGDN_NORMALDISPLAY = 0x00000000,
    SIGDN_PARENTRELATIVEPARSING = 0x80018001,
    SIGDN_DESKTOPABSOLUTEPARSING = 0x80028000,
    SIGDN_PARENTRELATIVEEDITING = 0x80031001,
    SIGDN_DESKTOPABSOLUTEEDITING = 0x8004c000,
    SIGDN_FILESYSPATH = 0x80058000,
    SIGDN_URL = 0x80068000
} SIGDN;

Constants

SIGDN_NORMALDISPLAY

Returns the display name relative to the desktop.

SIGDN_PARENTRELATIVEPARSING

Returns the parsing name relative to the parent folder.

SIGDN_DESKTOPABSOLUTEPARSING

Returns the parsing name relative to the desktop.

SIGDN_PARENTRELATIVEEDITING

Returns the editing name relative to the parent folder.

SIGDN_DESKTOPABSOLUTEEDITING

Returns the editing name relative to the desktop.

SIGDN_FILESYSPATH

Returns the display name relative to the file system path.

SIGDN_URL

Returns the display name relative to a URL.

Enumerated Type Information

Header and IDL files | shobjidl.h, shobjidl.idl
Minimum operating systems | Whistler


TRANSLATEURL_IN_FLAGS

The following enumerated values are used with the TranslateURL function to determine how it will execute.

typedef enum translateurl_in_flags {
    TRANSLATEURL_FL_GUESS_PROTOCOL,
    TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL,
} TRANSLATEURL_IN_FLAGS;

Members

TRANSLATEURL_FL_GUESS_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system automatically chooses a scheme and adds it to the URL.
TRANSLATEURL_FL_USE_DEFAULT_PROTOCOL
If the protocol scheme is not specified in the pcszURL parameter to TranslateURL, the system adds the default protocol to the URL.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


URLASSOCIATIONDIALOG_IN_FLAGS

The following enumerated values are used with URLAssociationDialog to determine how it executes.

typedef enum urlassociationdialog_in_flags {
    URLASSOCDLG_FL_USE_DEFAULT_NAME ,
    URLASSOCDLG_FL_REGISTER_ASSOC
} URLASSOCIATIONDIALOG_IN_FLAGS;

Members

URLASSOCDLG_FL_USE_DEFAULT_NAME
Use the default file name (that is, "Internet Shortcut").
URLASSOCDLG_FL_REGISTER_ASSOC
Register the selected application as the handler for the protocol specified in the pcszURL parameter of URLAssociationDialog. The application is registered only if this flag is set and the user indicates that a persistent association is desired.

Requirements

Version 4.00 and later of Shell32.dll
Windows NT/2000: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in intshcut.h.


Theme Reference

[This is preliminary documentation and subject to change.]

This section describes the following API elements used with theming.

  • Theme Property Types
  • Theme Property Typedefs
  • Theme Parts and States
  • Theme Enumerated Types
  • Theme Functions
  • Theme Structures


Theme Property Types

This is preliminary documentation and is subject to change.

This section describes the predefined primitive property types and their associated value format. When values have multiple parts, the parts optionally can be separated by commas.

Property Types

The following table list the primitive property types.

Property | Description | Format
bool | TRUE or FALSE | Standard Microsoft® Win32® BOOL
color | RGB color value | COLORREF Online link structure
enum | Enumerated type name declared in themes.inc | Standard Win32 INT
filename | Filename relative to the theme directory | WCHAR Online link array
font | Font description | LOGFONT Online link structure
int | Signed number | Standard Win32 INT
margins | Margins: left, top, right, and bottom | MARGINS structure
position | Location of an item | POINT Online link structure
rect | Size and location of a rectangle | RECT Online link structure
size | Size of an item | SIZE Online link structure
string | String in Unicode | WCHAR array


Theme Property Typedefs

This is preliminary documentation and is subject to change.

The Themes.inc file defines the enumerated types and type definitions used in Microsoft® Windows® Themes.

Property Typedefs

The following table lists typedefs defined by the Theme rendering routines.

Types | Typedefs
bool | Transparent, AutoSize, FlatMenu, BorderOnly, MenuDropShadows
color | BorderColor, FillColor, TextColor, TransparentColor, GradientColor1, GradientColor2, GradientColor3, GradientColor4, GradientColor5, ShadowColor, GlowColor, TextBorderColor, TextShadowColor
filename | ImageFile
int | ImageCount, AlphaLevel, BorderSize, RoundCornerWidth, RoundCornerHeight, GradientRatio1, GradientRatio2, GradientRatio3, GradientRatio4, GradientRatio5, ProgressChunkSize, ProgressSpaceSize, Saturation, TextBorderSize
margins | SizingMargins, ContentMargins, CaptionMargins
position | Offset, TextShadowOffset
size | width, height, x, y

The following table lists enumerated type properties that are defined by rendering routines.

Enumerated types | Properties
BgType | ImageFile, BorderFill
BorderType | Rect, RoundRect, Ellipse
ContentAlignment | left, center, right
FillType | Solid, VertGradient, HorzGradient, RadialGradient, TileImage
HAlign | left, center, right
IconEffect | None, Glow, Shadow, Pulse, Alpha
OffsetType | TopLeft, TopRight, TopMiddle, BottomLeft, BottomRight, BottomMiddle, MiddleLeft, MiddleRight, LeftOfCaption, RightOfCaption, LeftOfLastButton, RightOfLastButton, AboveLastButton, BelowLastButton
SizingType | TrueSize, Stretch, Tile, TileHorz, TileVert, TileCenter
TextShadowType | Single, Continuous
VAlign | top, vcenter, bottom


Theme Parts and States

This is preliminary documentation and is subject to change.

Controls and windows are defined in drawable parts, such as a parent part and zero or more child parts. Most parts have a state—for example disabled, active, or selected. When you author a control, you decide which aspects of the control will be theme-aware. You divide the control into a main part and zero or more named, theme-aware child parts. Examples of parts are text areas, drawn shapes, images, and lines. For each part, you can define one or more background images in a single bitmap file. The different backgrounds are usually associated with different states of the control, but do not have to be. For example, if the control is disabled, a grayed background might be used. At run time, the appropriate image can be selected by using an iStateId value as the 1-based index to the correct image.

Parts and States of Standard Controls and Windows

The following table shows how the common controls are broken into parts and states.

Control | Part | States
BUTTON | BP_CHECKBOX | CBS_CHECKEDDISABLED, CBS_CHECKEDHOT, CBS_CHECKEDNORMAL, CBS_CHECKEDPRESSED, CBS_MIXEDDISABLED, CBS_MIXEDHOT, CBS_MIXEDNORMAL, CBS_UNCHECKEDDISABLED, CBS_UNCHECKEDHOT, CBS_UNCHECKEDNORMAL, CBS_UNCHECKEDPRESSED
 | BP_GROUPBOX |
 | BP_PUSHBUTTON | PBS_DEFAULTED, PBS_DISABLED, PBS_HOT, PBS_NORMAL
 | BP_RADIOBUTTON | RBS_CHECKEDDISABLED, RBS_CHECKEDHOT, RBS_CHECKEDNORMAL, RBS_CHECKEDPRESSED, RBS_UNCHECKEDDISABLED, RBS_UNCHECKEDHOT, RBS_UNCHECKEDNORMAL, RBS_UNCHECKEDPRESSED
 | BP_USERBUTTON |
CLOCK | CLP_TIME | CLS_NORMAL
COMBOBOX | CP_DROPDOWNBUTTON | CBXS_DISABLED, CBXS_HOT, CBXS_NORMAL, CBXS_PRESSED
EDIT | EP_CARET |
 | EP_EDITTEXT | ETS_ASSIST, ETS_DISABLED, ETS_FOCUSED, ETS_HOT, ETS_NORMAL, ETS_READONLY, ETS_SELECTED
GLOBALS | GP_BORDER | BSS_FLAT, BSS_RAISED, BSS_SUNKEN
 | GP_LINEHORZ | LHS_FLAT, LHS_RAISED, LHS_SUNKEN
 | GP_LINEVERT | LVS_FLAT, LVS_RAISED, LVS_SUNKEN
HEADER | HP_HEADERITEM | HIS_HOT, HIS_NORMAL, HIS_PRESSED
 | HP_HEADERITEMLEFT | HILS_HOT, HILS_NORMAL, HILS_PRESSED
 | HP_HEADERITEMRIGHT | HIRS_HOT, HIRS_NORMAL, HIRS_PRESSED
 | HP_HEADERSORTARROW | HSAS_SORTEDDOWN, HSAS_SORTEDUP
LISTVIEW | LVP_EMPTYTEXT |
 | LVP_LISTDETAIL |
 | LVP_LISTGROUP |
 | LVP_LISTITEM | LIS_DISABLED, LIS_HOT, LIS_NORMAL, LIS_SELECTED, LIS_SELECTEDNOTFOCUS
 | LVP_LISTSORTEDDETAIL |
MENU | MP_MENUBARDROPDOWN | MS_DEMOTED, MS_NORMAL, MS_SELECTED
 | MP_MENUBARITEM | MS_DEMOTED, MS_NORMAL, MS_SELECTED
 | MP_CHEVRON | MS_DEMOTED, MS_NORMAL, MS_SELECTED
 | MP_MENUDROPDOWN | MS_DEMOTED, MS_NORMAL, MS_SELECTED
 | MP_MENUITEM | MS_DEMOTED, MS_NORMAL, MS_SELECTED
 | MP_SEPARATOR | MS_DEMOTED, MS_NORMAL, MS_SELECTED
PAGE | PGRP_DOWN |
 | PGRP_DOWNHORZ |
 | PGRP_UP |
 | PGRP_UPHORZ |
PROGRESS | PP_BAR |
 | PP_BARVERT |
 | PP_CHUNK |
 | PP_CHUNKVERT |
REBARPARTS | RP_BAND |
 | RP_CHEVRON | CHEVS_HOT, CHEVS_NORMAL, CHEVS_PRESSED
 | RP_GRIPPER |
 | RP_GRIPPERVERT |
SCROLLBAR | SBP_ARROWBTN | ABS_DOWNDISABLED, ABS_DOWNHOT, ABS_DOWNNORMAL, ABS_DOWNPRESSED, ABS_UPDISABLED, ABS_UPHOT, ABS_UPNORMAL, ABS_UPPRESSED, ABS_LEFTDISABLED, ABS_LEFTHOT, ABS_LEFTNORMAL, ABS_LEFTPRESSED, ABS_RIGHTDISABLED, ABS_RIGHTHOT, ABS_RIGHTNORMAL, ABS_RIGHTPRESSED
 | SBP_GRIPPERHORZ |
 | SBP_GRIPPERVERT |
 | SBP_LOWERTRACKHORZ | SCRBS_DISABLED, SCRBS_HOT, SCRBS_NORMAL, SCRBS_PRESSED
 | SBP_LOWERTRACKVERT | SCRBS_DISABLED, SCRBS_HOT, SCRBS_NORMAL, SCRBS_PRESSED
 | SBP_THUMBBTNHORZ | SCRBS_DISABLED, SCRBS_HOT, SCRBS_NORMAL, SCRBS_PRESSED
 | SBP_THUMBBTNVERT | SCRBS_DISABLED, SCRBS_HOT, SCRBS_NORMAL, SCRBS_PRESSED
 | SBP_UPPERTRACKHORZ | SCRBS_DISABLED, SCRBS_HOT, SCRBS_NORMAL, SCRBS_PRESSED
 | SBP_UPPERTRACKVERT | SCRBS_DISABLED, SCRBS_HOT, SCRBS_NORMAL, SCRBS_PRESSED
 | SBP_SIZEBOX | SZB_LEFTALIGN, SZB_RIGHTALIGN
SPIN | SPNP_DOWN | DNS_DISABLED, DNS_HOT, DNS_NORMAL, DNS_PRESSED
 | SPNP_DOWNHORZ | DNHZS_DISABLED, DNHZS_HOT, DNHZS_NORMAL, DNHZS_PRESSED
 | SPNP_UP | UPS_DISABLED, UPS_HOT, UPS_NORMAL, UPS_PRESSED
 | SPNP_UPHORZ | UPHZS_DISABLED, UPHZS_HOT, UPHZS_NORMAL, UPHZS_PRESSED
STARTPANEL | SPP_LOGOFF |
 | SPP_LOGOFFBUTTONS | SPLS_HOT, SPLS_NORMAL, SPLS_PRESSED
 | SPP_MOREPROGRAMS |
 | SPP_MOREPROGRAMSARROW | SPS_HOT, SPS_NORMAL, SPS_PRESSED
 | SPP_PLACELIST |
 | SPP_PLACELISTSEPARATOR |
 | SPP_PREVIEW |
 | SPP_PROGLIST |
 | SPP_PROGLISTSEPARATOR |
 | SPP_USERPANE |
 | SPP_USERPICTURE |
STATUS | SP_GRIPPER |
 | SP_PANE |
TAB | TABP_BODY |
 | TABP_PANE |
 | TABP_TABITEM | TIS_DISABLED, TIS_FOCUSED, TIS_HOT, TIS_NORMAL, TIS_SELECTED
 | TABP_TABITEMBOTHEDGE | TIBES_DISABLED, TIBES_FOCUSED, TIBES_HOT, TIBES_NORMAL, TIBES_SELECTED
 | TABP_TABITEMLEFTEDGE | TILES_DISABLED, TILES_FOCUSED, TILES_HOT, TILES_NORMAL, TILES_SELECTED
 | TABP_TABITEMRIGHTEDGE | TIRES_DISABLED, TIRES_FOCUSED, TIRES_HOT, TIRES_NORMAL, TIRES_SELECTED
 | TABP_TOPTABITEM | TTIS_DISABLED, TTIS_FOCUSED, TTIS_HOT, TTIS_NORMAL, TTIS_SELECTED
 | TABP_TOPTABITEMBOTHEDGE | TTIBES_DISABLED, TTIBES_FOCUSED, TTIBES_HOT, TTIBES_NORMAL, TTIBES_SELECTED
 | TABP_TOPTABITEMLEFTEDGE | TTILES_DISABLED, TTILES_FOCUSED, TTILES_HOT, TTILES_NORMAL, TTILES_SELECTED
 | TABP_TOPTABITEMRIGHTEDGE | TTIRES_DISABLED, TTIRES_FOCUSED, TTIRES_HOT, TTIRES_NORMAL, TTIRES_SELECTED
TASKBAND | TDP_GROUPCOUNT |
TASKBAR | TBP_BACKGROUNDBOTTOM |
 | TBP_BACKGROUNDLEFT |
 | TBP_BACKGROUNDRIGHT |
 | TBP_BACKGROUNDTOP |
 | TBP_SIZINGBARBOTTOM |
 | TBP_SIZINGBARBOTTOMLEFT |
 | TBP_SIZINGBARRIGHT |
 | TBP_SIZINGBARTOP |
TOOLBAR | TP_DROPDOWNBUTTON | TS_CHECKED, TS_DISABLED, TS_HOT, TS_HOTCHECKED, TS_NORMAL, TS_PRESSED
 | TP_BUTTON | TS_CHECKED, TS_DISABLED, TS_HOT, TS_HOTCHECKED, TS_NORMAL, TS_PRESSED
 | TP_SPLITBUTTON | TS_CHECKED, TS_DISABLED, TS_HOT, TS_HOTCHECKED, TS_NORMAL, TS_PRESSED
 | TP_SPLITBUTTONDROPDOWN | TS_CHECKED, TS_DISABLED, TS_HOT, TS_HOTCHECKED, TS_NORMAL, TS_PRESSED
 | TP_SEPARATOR | TS_CHECKED, TS_DISABLED, TS_HOT, TS_HOTCHECKED, TS_NORMAL, TS_PRESSED
 | TP_SEPARATORVERT | TS_CHECKED, TS_DISABLED, TS_HOT, TS_HOTCHECKED, TS_NORMAL, TS_PRESSED
TOOLTIP | TTP_BALLOON | TTBS_LINK, TTBS_NORMAL
 | TTP_BALLOONTITLE | TTBS_LINK, TTBS_NORMAL
 | TTP_STANDARD | TTSS_LINK, TTSS_NORMAL
 | TTP_STANDARDTITLE | TTSS_LINK, TTSS_NORMAL
TRACKBAR | TKP_THUMB | TUS_DISABLED, TUS_FOCUSED, TUS_HOT, TUS_NORMAL, TUS_PRESSED
 | TKP_THUMBBOTTOM | TUBS_DISABLED, TUBS_FOCUSED, TUBS_HOT, TUBS_NORMAL, TUBS_PRESSED
 | TKP_THUMBLEFT | TUVLS_DISABLED, TUVLS_FOCUSED, TUVLS_HOT, TUVLS_NORMAL, TUVLS_PRESSED
 | TKP_THUMBRIGHT | TUVRS_DISABLED, TUVRS_FOCUSED, TUVRS_HOT, TUVRS_NORMAL, TUVRS_PRESSED
 | TKP_THUMBTOP | TUTS_DISABLED, TUTS_FOCUSED, TUTS_HOT, TUTS_NORMAL, TUTS_PRESSED
 | TKP_THUMBVERT | TUVS_DISABLED, TUVS_FOCUSED, TUVS_HOT, TUVS_NORMAL, TUVS_PRESSED
 | TKP_TICS | TSS_NORMAL
 | TKP_TICSVERT | TSVS_NORMAL
 | TKP_TRACK | TRS_NORMAL
 | TKP_TRACKVERT | TRVS_NORMAL
TRAYNOTIFYPARTS | TNP_ANIMBACKGROUND |
 | TNP_BACKGROUND |
TREEVIEW | TVP_BRANCH |
 | TVP_GLYPH | GLPS_CLOSED, GLPS_OPENED
 | TVP_TREEITEM | TREIS_DISABLED, TREIS_HOT, TREIS_NORMAL, TREIS_SELECTED, TREIS_SELECTEDNOTFOCUS
WINDOW | WP_CAPTION | CS_ACTIVE, CS_DISABLED, CS_INACTIVE
 | WP_CLOSEBUTTON | CBS_DISABLED, CBS_HOT, CBS_NORMAL, CBS_PUSHED
 | WP_DIALOG |
 | WP_FRAME | FS_ACTIVE, FS_DISABLED, FS_INACTIVE
 | WP_HELPBUTTON | HBS_DISABLED, HBS_HOT, HBS_NORMAL, HBS_PUSHED
 | WP_HORZSCROLL | HSS_DISABLED, HSS_HOT, HSS_NORMAL, HSS_PUSHED
 | WP_HORZTHUMB | HTS_DISABLED, HTS_HOT, HTS_NORMAL, HTS_PUSHED
 | WP_MAX_BUTTON | MAXBS_DISABLED, MAXBS_HOT, MAXBS_NORMAL, MAXBS_PUSHED
 | WP_MAXCAPTION | MXCS_ACTIVE, MXCS_DISABLED, MXCS_INACTIVE
 | WP_MDICLOSEBUTTON | CBS_DISABLED, CBS_HOT, CBS_NORMAL, CBS_PUSHED
 | WP_MDIHELPBUTTON | HBS_DISABLED, HBS_HOT, HBS_NORMAL, HBS_PUSHED
 | WP_MDIMINBUTTON | MINBS_DISABLED, MINBS_HOT, MINBS_NORMAL, MINBS_PUSHED
 | WP_MDIRESTOREBUTTON | RBS_DISABLED, RBS_HOT, RBS_NORMAL, RBS_PUSHED
 | WP_MDISYSBUTTON | SBS_DISABLED, SBS_HOT, SBS_NORMAL, SBS_PUSHED
 | WP_MINBUTTON | MINBS_DISABLED, MINBS_HOT, MINBS_NORMAL, MINBS_PUSHED
 | WP_MINCAPTION | MNCS_ACTIVE, MNCS_DISABLED, MNCS_INACTIVE
 | WP_RESTOREBUTTON | RBS_DISABLED, RBS_HOT, RBS_NORMAL, RBS_PUSHED
 | WP_SMALLCAPTION | CS_ACTIVE, CS_DISABLED, CS_INACTIVE
 | WP_SMALLCLOSEBUTTON | CBS_DISABLED, CBS_HOT, CBS_NORMAL, CBS_PUSHED
 | WP_SMALLFRAME | FS_ACTIVE, FS_DISABLED, FS_INACTIVE
 | WP_SMALLHELPBUTTON | HBS_DISABLED, HBS_HOT, HBS_NORMAL, HBS_PUSHED
 | WP_SMALLMAXBUTTON | MAXBS_DISABLED, MAXBS_HOT, MAXBS_NORMAL, MAXBS_PUSHED
 | WP_SMALLMAXCAPTION | MXCS_ACTIVE, MXCS_DISABLED, MXCS_INACTIVE
 | WP_SMALLMINBUTTON | MINBS_DISABLED, MINBS_HOT, MINBS_NORMAL, MINBS_PUSHED
 | WP_SMALLMINCAPTION | MNCS_ACTIVE, MNCS_DISABLED, MNCS_INACTIVE
 | WP_SMALLRESTOREBUTTON | RBS_DISABLED, RBS_HOT, RBS_NORMAL, RBS_PUSHED
 | WP_SMALLSYSBUTTON | SBS_DISABLED, SBS_HOT, SBS_NORMAL, SBS_PUSHED
 | WP_SYSBUTTON | SBS_DISABLED, SBS_HOT, SBS_NORMAL, SBS_PUSHED
 | WP_VERTSCROLL | VSS_DISABLED, VSS_HOT, VSS_NORMAL, VSS_PUSHED
 | WP_VERTTHUMB | VTS_DISABLED, VTS_HOT, VTS_NORMAL, VTS_PUSHED


Theme Enumerated Types

This is preliminary documentation and is subject to change.

This section describes the enumerated types associated with themes.

PROPERTYORIGIN | Used to specify where a property was found.
THEME_CONTROL_FLAGS | Controls the nature of theming in an application. These values can be combined using the logical OR operator when read from GetThemeAppProperties or passed to SetThemeAppProperties.
THEME_METRICS_BOOLS | Identifies a Boolean value from the SysMetrics section of theme data. These constants are passed to GetThemeBool to retrieve the desired Boolean value.
THEME_METRICS_COLORS | Specifies a color from the SysMetrics section of theme data. These constants are passed to GetThemeColor or GetThemeSysColor to return the desired color value.
THEME_METRICS_FONTS | Identifies a specific font from the SysMetrics section of theme data when calling GetThemeSysFont.
THEME_METRICS_INTS | Identifies a specific integer from the SysMetrics section of theme data when calling GetThemeSysInt.
THEME_METRICS_SIZES | Identifies a specific user interface element size from the SysMetrics section of theme data.
THEME_METRICS_STRINGS | Identifies a specific string from the SysMetrics section of theme data when calling GetThemeSysString.
THEME_SIZE | Identifies the size of the theme part to retrieve.


PROPERTYORIGIN Enumerated Type

This is preliminary documentation and is subject to change.

Used to specify where a property was found.

Syntax

typedef enum {
    PO_STATE = 0,
    PO_PART = 1,
    PO_CLASS = 2,
    PO_GLOBAL = 3,
    PO_NOTFOUND = 4
} PROPERTYORIGIN;

Constants

PO_STATE

Property was found in the state section.

PO_PART

Property was found in the part section.

PO_CLASS

Property was found in the class section.

PO_GLOBAL

Property was found in the list of global variables.

PO_NOTFOUND

Property was not found.

Enumerated Type Information

Header | uxtheme.h
Minimum operating systems | Whistler


THEME_METRICS_BOOLS Enumerated Type

This is preliminary documentation and is subject to change.

Identifies a Boolean value from the SysMetrics section of theme data. These constants are passed to GetThemeBool to retrieve the desired Boolean value.

Syntax

typedef enum {
    TMT_FLATMENUS = 800,
    TMT_DROPSHADOWS = 801,
    TMT_MOUSEVANISH = 802,
    TMT_CURSORSHADOW = 803,
    TMT_TOOLTIPFADE = 804,
    TMT_TOOLTIPANIMATION = 805,
    TMT_SELECTIONFADE = 806,
    TMT_ANIMATION = 807,
    TMT_LISTBOXSMOOTHSCROLL = 808,
    TMT_COMBOBOXANIMATION = 809,
    TMT_MENUANIMATION = 810,
    TMT_MENUFADE = 811,
    TMT_FIRSTBOOL = TMT_FLATMENUS,
    TMT_LASTBOOL = TMT_MENUFADE
} THEME_METRICS_BOOLS;

Constants

TMT_FLATMENUS

Specifies the flat menu Boolean value.

TMT_DROPSHADOWS

Specifies the drop shadows Boolean value.

TMT_MOUSEVANISH

Specifies the mouse vanish Boolean value.

TMT_CURSORSHADOW

Specifies the cursor shadow Boolean value.

TMT_TOOLTIPFADE

Specifies the fading ToolTips Boolean value.

TMT_TOOLTIPANIMATION

Specifies the animated ToolTips Boolean value.

TMT_SELECTIONFADE

Specifies the selection fade Boolean value.

TMT_ANIMATION

Specifies the Boolean value for system animation—for example, window zooming, menu effects, and so forth.

TMT_LISTBOXSMOOTHSCROLL

Specifies the smooth scrolling list box Boolean value.

TMT_COMBOBOXANIMATION

Specifies the animated combo box Boolean value.

TMT_MENUANIMATION

Specifies the animated menu Boolean value.

TMT_MENUFADE

Specifies the fading menu Boolean value.

TMT_FIRSTBOOL

Specifies a convenience constant equal to the first constant in THEME_METRICS_BOOLS.

TMT_LASTBOOL

Specifies a convenience constant equal to the last constant in THEME_METRICS_BOOLS.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


THEME_METRICS_COLORS Enumerated Type

This is preliminary documentation and is subject to change.

Specifies a color from the SysMetrics section of theme data. These constants are passed to GetThemeColor or GetThemeSysColor to return the desired color value.

Syntax

typedef enum {
    TMT_SCROLLBAR = 1600,
    TMT_BACKGROUND = 1601,
    TMT_ACTIVECAPTION = 1602,
    TMT_INACTIVECAPTION = 1603,
    TMT_MENU = 1604,
    TMT_WINDOW = 1605,
    TMT_WINDOWFRAME = 1606,
    TMT_MENUTEXT = 1607,
    TMT_WINDOWTEXT = 1608,
    TMT_CAPTIONTEXT = 1609,
    TMT_ACTIVEBORDER = 1610,
    TMT_INACTIVEBORDER = 1611,
    TMT_APPWORKSPACE = 1612,
    TMT_HIGHLIGHT = 1613,
    TMT_HIGHLIGHTTEXT = 1614,
    TMT_BTNFACE = 1615,
    TMT_BTNSHADOW = 1616,
    TMT_GRAYTEXT = 1617,
    TMT_BTNTEXT = 1618,
    TMT_INACTIVECAPTIONTEXT = 1619,
    TMT_BTNHIGHLIGHT = 1620,
    TMT_DKSHADOW3D = 1621,
    TMT_LIGHT3D = 1622,
    TMT_INFOTEXT = 1623,
    TMT_INFOBK = 1624,
    TMT_BUTTONALTERNATEFACE = 1625,
    TMT_HOTTRACKING = 1626,
    TMT_GRADIENTACTIVECAPTION = 1627,
    TMT_GRADIENTINACTIVECAPTION = 1628,
    TMT_MENUHILIGHT = 1629,
    TMT_MENUBAR = 1630,
    TMT_FIRSTCOLOR = TMT_SCROLLBAR,
    TMT_LASTCOLOR = TMT_MENUBAR
} THEME_METRICS_COLORS;

Constants

TMT_SCROLLBAR

Specifies the scroll bar color.

TMT_BACKGROUND

Specifies the window background color.

TMT_ACTIVECAPTION

Specifies the color of an active caption.

TMT_INACTIVECAPTION

Specifies the color of an inactive caption.

TMT_MENU

Specifies the menu color.

TMT_WINDOW

Specifies the window client area color.

TMT_WINDOWFRAME

Specifies the window frame color.

TMT_MENUTEXT

Specifies the menu text color.

TMT_WINDOWTEXT

Specifies the window text color.

TMT_CAPTIONTEXT

Specifies the caption color.

TMT_ACTIVEBORDER

Specifies the active border color.

TMT_INACTIVEBORDER

Specifies the inactive border color.

TMT_APPWORKSPACE

Specifies the application workspace color.

TMT_HIGHLIGHT

Specifies the highlight color.

TMT_HIGHLIGHTTEXT

Specifies the highlighted text color.

TMT_BTNFACE

Specifies the button face color.

TMT_BTNSHADOW

Specifies the button shadow color.

TMT_GRAYTEXT

Specifies the color of gray or disabled text.

TMT_BTNTEXT

Specifies the button text color.

TMT_INACTIVECAPTIONTEXT

Specifies the inactive caption text color.

TMT_BTNHIGHLIGHT

Specifies the button highlight color.

TMT_DKSHADOW3D

Specifies the color of the dark portion of a 3-D shadow.

TMT_LIGHT3D

Specifies the color of the light portion of a 3-D shadow.

TMT_INFOTEXT

Specifies the info text color, that is, the Help or ToolTip text color.

TMT_INFOBK

Specifies the info background color, that is, the Help or ToolTip background color.

TMT_BUTTONALTERNATEFACE

Specifies the alternate button face color.

TMT_HOTTRACKING

Specifies the hot tracking color.

TMT_GRADIENTACTIVECAPTION

Specifies the gradient active caption color.

TMT_GRADIENTINACTIVECAPTION

Specifies the gradient inactive caption color.

TMT_MENUHILIGHT

Specifies the menu highlight color.

TMT_MENUBAR

Specifies the menu bar color.

TMT_FIRSTCOLOR

Specifies a convenience constant equal to the first constant in THEME_METRICS_COLORS.

TMT_LASTCOLOR

Specifies a convenience constant equal to the last constant in THEME_METRICS_COLORS.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


THEME_CONTROL_FLAGS Enumerated Type

This is preliminary documentation and is subject to change.

Controls the nature of theming in an application. These values can be combined using the logical OR operator when read from GetThemeAppProperties or passed to SetThemeAppProperties.

Syntax

typedef enum {
    STAP_ALLOW_NONCLIENT = 1,
    STAP_ALLOW_NONCLIENT = 2,
    STAP_ALLOW_WEBCONTENT = 4
} THEME_CONTROL_FLAGS;

Constants

STAP_ALLOW_NONCLIENT

Specifies that the nonclient area of an application's windows should be themed.

STAP_ALLOW_NONCLIENT

Specifies that controls in an application should be themed.

STAP_ALLOW_WEBCONTENT

Specifies that all Web content in an application should be themed.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


THEME_METRICS_FONTS Enumerated Type

This is preliminary documentation and is subject to change.

Identifies a specific font from the SysMetrics section of theme data when calling GetThemeSysFont.

Syntax

typedef enum {
    TMT_CAPTIONFONT = 800,
    TMT_SMALLCAPTIONFONT = 801,
    TMT_MENUFONT = 802,
    TMT_STATUSFONT = 803,
    TMT_MSGBOXFONT = 804,
    TMT_ICONTITLEFONT = 805,
    TMT_FIRSTFONT = TMT_CAPTION,
    TMT_LASTFONT = TMT_ICONTITLEFONT
} THEME_METRICS_FONTS;

Constants

TMT_CAPTIONFONT

Specifies the window caption font.

TMT_SMALLCAPTIONFONT

Specifies the window caption font when small fonts are selected.

TMT_MENUFONT

Specifies the menu font.

TMT_STATUSFONT

Specifies the status bar font.

TMT_MSGBOXFONT

Specifies the message box text font.

TMT_ICONTITLEFONT

Specifies the font used next to or under icons in Microsoft® Windows® Explorer, on the desktop, and so forth.

TMT_FIRSTFONT

Specifies a convenience constant equal to the first constant in THEME_METRICS_FONTS.

TMT_LASTFONT

Specifies a convenience constant equal to the last constant in THEME_METRICS_FONTS.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


THEME_METRICS_INTS Enumerated Type

This is preliminary documentation and is subject to change.

Identifies a specific integer from the SysMetrics section of theme data when calling GetThemeSysInt.

Syntax

typedef enum {
    TMT_DPIX = 1300,
    TMT_DPIY = 1301,
    TMT_MINCOLORDEPTH = 1302,
    TMT_FIRSTINT = TMT_DPIX,
    TMT_LASTINT = TMT_MINCOLORDEPTH
} THEME_METRICS_INTS;

Constants

TMT_DPIX

Specifies the number of dots per inch, measured in the X direction, that the theme is designed for.

TMT_DPIY

Specifies the number of dots per inch, measured in the Y direction, that the theme is designed for.

TMT_MINCOLORDEPTH

Specifies the minimum number of monitor colors that the theme is designed for, typically 15 colors.

TMT_FIRSTINT

Specifies a convenience constant equal to the first constant in THEME_METRICS_INTS.

TMT_LASTINT

Specifies a convenience constant equal to the last constant in THEME_METRICS_INTS.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


THEME_SIZE Enumerated Type

This is preliminary documentation and is subject to change.

Identifies the size of the theme part to retrieve.

Syntax

typedef enum {
    TS_MIN,
    TS_TRUE
} THEME_SIZE;

Constants

TS_MIN

Receives the minimum size of a theme part.

TS_TRUE

Receives the size of the theme part that will best fit the available space.

Remarks

The GetThemePartSize function retrieves the minimum and best-fit sizes of a part and places the information in a THEME_SIZE structure.

Enumerated Type Information

Header | uxtheme.h
Minimum operating systems | Whistler


THEME_METRICS_SIZES Enumerated Type

This is preliminary documentation and is subject to change.

Identifies a specific user interface element size from the SysMetrics section of theme data.

Syntax

typedef enum {
    TMT_BORDERWIDTH = 1200,
    TMT_SCROLLBARWIDTH = 1201,
    TMT_SCROLLBARHEIGHT = 1202,
    TMT_CAPTIONBARWIDTH = 1203,
    TMT_CAPTIONBARHEIGHT = 1204,
    TMT_SMCAPTIONBARWIDTH = 1205,
    TMT_SMCAPTIONBARHEIGHT = 1206,
    TMT_MENUBARWIDTH = 1207,
    TMT_MENUBARHEIGHT = 1208,
    TMT_FIRSTSIZE = TMT_BORDERWIDTH,
    TMT_LASTSIZE = TMT_MENUBARHEIGHT
} THEME_METRICS_SIZES;

Constants

TMT_BORDERWIDTH

Specifies the border width.

TMT_SCROLLBARWIDTH

Specifies the scroll bar width.

TMT_SCROLLBARHEIGHT

Specifies the scroll bar height.

TMT_CAPTIONBARWIDTH

Specifies the caption bar width.

TMT_CAPTIONBARHEIGHT

Specifies the caption bar height.

TMT_SMCAPTIONBARWIDTH

Specifies the small window caption bar width.

TMT_SMCAPTIONBARHEIGHT

Specifies the small window caption bar height.

TMT_MENUBARWIDTH

Specifies the menu bar width.

TMT_MENUBARHEIGHT

Specifies the menu bar height.

TMT_FIRSTSIZE

Specifies a convenience constant equal to the first constant in THEME_METRICS_SIZES.

TMT_LASTSIZE

Specifies a convenience constant equal to the last constant in THEME_METRICS_SIZES.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


THEME_METRICS_STRINGS Enumerated Type

This is preliminary documentation and is subject to change.

Identifies a specific string from the SysMetrics section of theme data when calling GetThemeSysString.

Syntax

typedef enum {
    TMT_CSSNAME = 1400,
    TMT_XMLNAME = 1401,
    TMT_FIRSTSTRING = TMT_CSSNAME,
    TMT_LASTSTRING = TMT_XMLNAME
} THEME_METRICS_STRINGS;

Constants

TMT_CSSNAME

Specifies the Cascading Style Sheets (CSS) string value.

TMT_XMLNAME

Specifies the Extensible Markup Language (XML) string value.

TMT_FIRSTSTRING

Specifies a convenience constant equal to the first constant in THEME_METRICS_STRINGS.

TMT_LASTSTRING

Specifies a convenience constant equal to the last constant in THEME_METRICS_STRINGS.

Enumerated Type Information

Header | Tmschema.h
Minimum operating systems | Whistler


Theme Functions

This is preliminary documentation and is subject to change.

This section describes the functions associated with themes.

CloseThemeData | Closes the theme data handle.
DrawThemeBackground | Draws the theme-defined background image for the specified control part.
DrawThemeBorder | Draws the theme-defined border within a specified rectangle.
DrawThemeEdge | Draws one or more theme-defined edges of a rectangle.
DrawThemeIcon | Draws an image from an image list with the theme-defined icon effect.
DrawThemeLine | Draws a theme-defined line within a specified rectangle.
DrawThemeText | Draws the text using the theme-defined color and font.
FormatThemeMessage | Formats an error message in a specified language using a THEME_ERROR_CONTEXT.
GetCurrentThemeName | Retrieves the name of the current theme, and optionally retrieves the color scheme name and size name.
GetThemeAppProperties | Retrieves the property flags that control how themes are applied in the current application.
GetThemeBackgroundContentRect | Retrieves the size of the content area for the theme-defined background.
GetThemeBackgroundExtent | Calculates the size and location of the theme-defined background given the content area.
GetThemeBackgroundRegion | Computes the region for a regular or partially transparent background that is bounded by a specified rectangle.
GetThemeBool | Retrieves the value of a BOOL property from the SysMetrics section of theme data.
GetThemeColor | Retrieves the value of a color property.
GetThemeDocumentationProperty | Retrieves the value for a theme property from the documentation section of the Themes.ini file.
GetThemeEnumValue | Retrieves the value of an enumerated type property.
GetThemeFilename | Retrieves the value of a filename property.
GetThemeFont | Retrieves the value of a font property.
GetThemeInt | Retrieves the value of a integer property.
GetThemeIntList | Retrieves a list of integer data from a theme.
GetThemeLastErrorContext | Retrieves the full error context information for the last theme application programming interface (API) error on the current thread.
GetThemeMargins | Retrieves the value of a MARGINS property.
GetThemeMetric | Retrieves the value of a metric property.
GetThemePartSize | Calculates the original size of the theme-defined part.
GetThemePosition | Retrieves the value of a position property.
GetThemePropertyOrigin | Retrieves the location of the theme property definition for a property.
GetThemeRect | Retrieves the value of a RECT Online link property.
GetThemeString | Retrieves the value of a string property.
GetThemeSysBool | Retrieves the Boolean value of a system metric such as flat menus, fading tool tips, and so forth.
GetThemeSysColor | Retrieves the value of a system color.
GetThemeSysColorBrush | Retrieves a system color brush.
GetThemeSysFont | Retrieves the LOGFONT Online link of a system font.
GetThemeSysInt | Retrieves the value of a system integer.
GetThemeSysSize | Retrieves the value of a system size metric from theme data.
GetThemeSysString | Retrieves the value of a system string.
GetThemeTextExtent | Calculates the size and location of the specified text when rendered in the theme font.
GetThemeTextMetrics | Retrieves information about the theme-specified font for a particular part.
GetWindowTheme | If the window is themed, the GetWindowTheme function returns the most recent theme handle from OpenThemeData. If the window is not themed, GetWindowTheme returns NULL.
HitTestThemeBackground | Retrieves a hit test code for a point in the theme-specified background.
IsAppThemed | Reports whether the current application's user interface is being displayed using themes.
IsThemeActive | Tests if a theme for the current application is active.
IsThemeBackgroundPartiallyTransparent | Retrieves whether the theme-specified background has transparent pieces or alpha-blended pieces.
IsThemePartDefined | Retrieves whether a theme has defined parameters for the specified part and state.
OpenThemeData | Opens the theme data for a window and its associated class.
SetThemeAppProperties | Sets the flags that determine how themes are implemented in the calling application.
SetWindowTheme | Causes a window to use a different set of theme information than its class normally uses.
SetWindowThemeStyle | Causes a window to be themed using a different nonclient style.


CloseThemeData Function

This is preliminary documentation and is subject to change.

Closes the theme data handle.

Syntax

HRESULT CloseThemeData(
    HTHEME hTheme
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


DrawThemeBackground Function

This is preliminary documentation and is subject to change.

Draws the theme-defined background image for the specified control part.

Syntax

HRESULT DrawThemeBackground(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    const RECT *pRect,
    const RECT *pClipRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC) used for drawing the theme-defined background image.
iPartId
[in] integer that specifies the part to draw. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part to draw. See Theme Parts and States.
pRect
[in] Pointer to a RECT Online link structure that contains the rectangle, in logical coordinates, in which the background image is drawn.
pClipRect
[in] [optional] Pointer to a RECT structure that contains a clipping rectangle.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Drawing operations are scaled to fit and not exceed the rectangle specified in pRect. Your application should not draw outside the rectangle specified by pClipRect.

The theme-defined background can be based on a bitmap file, a border, or fill pattern.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


DrawThemeBorder Function

This is preliminary documentation and is subject to change.

Draws the theme-defined border within a specified rectangle.

Syntax

HRESULT DrawThemeBorder(
    HTHEME hTheme,
    HDC hdc,
    int iStateId,
    const RECT *pRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC).
iStateId
[in] integer that specifies the border type—for example, flat, raised, or lowered. See Theme Parts and States.
pRect
[in] Pointer to a RECT Online link structure that contains, in logical coordinates, the rectangle in which the border is drawn.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


DrawThemeEdge Function

This is preliminary documentation and is subject to change.

Draws one or more theme-defined edges of a rectangle.

Syntax

HRESULT DrawThemeEdge(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    const RECT *pDestRect,
    UINT uEdge,
    UINT uFlags,
    RECT *pContentRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC).
iPartId
[in] integer that specifies the part that contains the rectangle. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
pDestRect
[in] Pointer to a RECT Online link structure that contains, in logical coordinates, the rectangle.
uEdge
[in] UINT that specifies the type of inner and outer edges to draw. This parameter must be a combination of one inner-border flag and one outer-border flag, or one of the combination flags. The border flags are:
BDR_RAISEDINNER
Raised inner edge
BDR_SUNKENINNER
Sunken inner edge
BDR_RAISEDOUTER
Raised outer edge
BDR_SUNKENOUTER
Sunken outer edge
EDGE_BUMP
Combination of BDR_RAISEDOUTER and BDR_SUNKENINNER
EDGE_ETCHED
Combination of BDR_SUNKENOUTER and BDR_RAISEDINNER
EDGE_RAISED
Combination of BDR_RAISEDOUTER and BDR_RAISEDINNER
EDGE_SUNKEN
Combination of BDR_SUNKENOUTER and BDR_SUNKENINNER
uFlags
[in] UINT that specifies the type of border to draw. This parameter can be a combination of the following values.
BF_ADJUST
The rectangle pointed to by the pDestRect parameter is shrunk to exclude the edges that were drawn; otherwise the rectangle does not change.
BF_BOTTOM
Bottom of border rectangle.
BF_BOTTOMLEFT
Bottom and left side of border rectangle.
BF_BOTTOMRIGHT
Bottom and right side of border rectangle.
BF_DIAGONAL
Diagonal border.
BF_DIAGONAL_ENDBOTTOMLEFT
Diagonal border. The end point is the lower-left corner of the rectangle; the origin is the upper-right corner.
BF_DIAGONAL_ENDBOTTOMRIGHT
Diagonal border. The end point is the lower-right corner of the rectangle; the origin is the upper-left corner.
BF_DIAGONAL_ENDTOPLEFT
Diagonal border. The end point is the upper-left corner of the rectangle; the origin is the lower-right corner.
BF_DIAGONAL_ENDTOPRIGHT
Diagonal border. The end point is the upper-right corner of the rectangle; the origin is the lower-left corner.
BF_FLAT
Flat border.
BF_LEFT
Left side of border rectangle.
BF_MIDDLE
Interior of the rectangle is to be filled.
BF_MONO
One-dimensional border.
BF_RECT
Entire border rectangle.
BF_RIGHT
Right side of border rectangle.
BF_SOFT
Soft buttons instead of tiles.
BF_TOP
Top of border rectangle.
BF_TOPLEFT
Top and left side of border rectangle.
BF_TOPRIGHT
Top and right side of border rectangle.
pContentRect
[out] [optional] Pointer to a RECT structure that contains, in logical coordinates, the rectangle that receives the interior rectangle, if uFlags is set to BF_ADJUST.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


DrawThemeIcon Function

This is preliminary documentation and is subject to change.

Draws an image from an image list with the theme-defined icon effect.

Syntax

HRESULT DrawThemeIcon(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    const RECT *pRect,
    HIMAGELIST himl,
    int iImageIndex
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC).
iPartId
[in] integer that specifies the part in which the image is drawn. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
pRect
[in] Pointer to a RECT Online link structure that contains, in logical coordinates, the rectangle in which the image is drawn.
himl
[in] Handle to an image list that contains the image to draw.
iImageIndex
[in] integer that specifies the index of the image to draw.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


DrawThemeLine Function

This is preliminary documentation and is subject to change.

Draws a theme-defined line within a specified rectangle.

Syntax

HRESULT DrawThemeLine(
    HTHEME hTheme,
    HDC hdc,
    int iStateId,
    const RECT *pRect,
    DWORD dwDtlFlags
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC).
iStateId
[in] integer that specifies the line type—for example, flat, raised, or lowered. See Theme Parts and States.
pRect
[in] Pointer to a RECT Online link structure that contains, in logical coordinates, the rectangle in which the line is drawn.
dwDtlFlags
[in] DWORD that contains the flags that indicate where the line is drawn. The parameter value may be one or more of the following:
DTL_LEFT
Line is drawn on the left side of the rectangle specified by pRect.
DTL_TOP
Line is drawn at the top of the rectangle specified by pRect.
DTL_RIGHT
Line is drawn on the right side of the rectangle specified by pRect.
DTL_BOTTOM
Line is drawn at the bottom of the rectangle specified by pRect.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


DrawThemeText Function

This is preliminary documentation and is subject to change.

Draws the text using the theme-defined color and font.

Syntax

HRESULT DrawThemeText(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    LPCWSTR pszText,
    int iCharCount,
    DWORD dwTextFlags,
    DWORD dwTextFlags2,
    const RECT *pRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC) to use for drawing.
iPartId
[in] integer that specifies the part that contains the text. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
pszText
[in] Pointer to a string that contains the text to draw.
iCharCount
[in] integer that contains the number of characters to draw. If the parameter is set to -1, all the characters in the string are drawn.
dwTextFlags
[in] DWORD that contains one or more values that specify the string's formatting. See Format Values for possible parameter values.
dwTextFlags2
[in] [optional] The value for this flag is:
DTT_GRAYED 0x1
Draws a grayed-out string.
pRect
[in] Pointer to a RECT Online link structure that contains the rectangle, in logical coordinates, in which the text is to be drawn.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


FormatThemeMessage Function

This is preliminary documentation and is subject to change.

Formats an error message in a specified language using a THEME_ERROR_CONTEXT.

Syntax

HRESULT FormatThemeMessage(
    DWORD dwLanguageID,
    THEME_ERROR_CONTEXT *pContext,
    LPWSTR pszMessageBuff,
    DWORD dwMaxMessageChars
);

Parameters

dwLanguageID
[in] DWORD that specifies the desired language of the error message. Language identification codes are described in the Microsoft® Win32® Software Development Kit (SDK).
pContext
[in] Pointer to a THEME_ERROR_CONTEXT structure.
pszMessageBuff
[out] Pointer to a string that receives the formatted error message. If the message is too long, it is truncated.
dwMaxMessageChars
[in] DWORD that contains the maximum number of characters allowed in the error message.

Return Value

Returns S_OK if successful, otherwise an error code.

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

GetThemeLastErrorContext


GetCurrentThemeName Function

This is preliminary documentation and is subject to change.

Retrieves the name of the current theme, and optionally retrieves the color scheme name and size name.

Syntax

HRESULT GetCurrentThemeName(
    LPWSTR pszNameBuff,
    DWORD dwMaxNameChars,
    LPWSTR pszColorBuff,
    DWORD dwMaxColorChars,
    LPWSTR pszSizeBuff,
    DWORD dwMaxSizeChars
);

Parameters

pszNameBuff
[out] Pointer to a string that receives the theme file name.
dwMaxNameChars
[in] DWORD that contains the maximum number of characters allowed in the theme file name.
pszColorBuff
[out] [optional] Pointer to a string that receives the color scheme name.
dwMaxColorChars
[in] DWORD that contains the maximum number of characters allowed in the color scheme name.
pszSizeBuff
[out] [optional] Pointer to a string that receives the size name.
dwMaxSizeChars
[in] DWORD that contains the maximum number of characters allowed in the size name.

Return Value

Returns S_OK if successful, otherwise an error code.

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

GetThemeLastErrorContext


GetThemeAppProperties Function

This is preliminary documentation and is subject to change.

Retrieves the property flags that control how themes are applied in the current application.

Syntax

DWORD GetThemeAppProperties(VOID);

Return Value

The following return values are bit flags combined with a logical OR operator.

STAP_ALLOW_NONCLIENT | Specifies that the nonclient area of application windows are themed.
STAP_ALLOW_CONTROLS | Specifies that controls in application windows are themed.
STAP_ALLOW_WEBCONTENT | Specifies that all web content displayed in an application is rendered using themes.

Remarks

Individual flags can be extracted from the result by combining the result with the logical AND of the desired flag.

Example

The example extracts a single flag's state from the function result.

DWORD resultFlags = GetThemeAppProperties();
bool ctrlsAreThemed = ((resultFlags & STAP_ALLOW_CONTROLS) != 0);

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

SetThemeAppProperties


GetThemeBackgroundContentRect Function

This is preliminary documentation and is subject to change.

Retrieves the size of the content area for the theme-defined background.

Syntax

HRESULT GetThemeBackgroundContentRect(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    const RECT *pBoundingRect,
    RECT *pContentRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] [optional] Handle to a device context (HDC) to use when drawing.
iPartId
[in] integer that specifies the part that contains the content area. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part that contains the content area. See Theme Parts and States.
pBoundingRect
[in] [optional] Pointer to a RECT Online link structure that contains the total background rectangle, in logical coordinates. This is the area inside the borders or margins.
pContentRect
[out] Pointer to a RECT structure that receives the content area background rectangle, in logical coordinates. This rectangle is calculated to fit the content area.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

A theme can define a content area within each background image. This is the area where content such as text and icons can be placed without overwriting background borders.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeBackgroundExtent Function

This is preliminary documentation and is subject to change.

Calculates the size and location of the theme-defined background given the content area.

Syntax

HRESULT GetThemeBackgroundExtent(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    const RECT *pContentRect,
    RECT *pExtentRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] [optional] Handle to a device context (HDC) to use when drawing.
iPartId
[in] integer that specifies the part that contains the content. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part that contains the content. See Theme Parts and States.
pContentRect
[in] Pointer to a RECT Online link structure that contains the content background rectangle, in logical coordinates. This rectangle is returned from GetThemeBackgroundContentRect.
pExtentRect
[out] Pointer to a RECT structure that receives the background rectangle, in logical coordinates. This rectangle is based on the pContentRect.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

A theme can define a content area within each background image. This is the area where content such as text and icons can be placed without overwriting background borders.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeBackgroundRegion Function

This is preliminary documentation and is subject to change.

Computes the region for a regular or partially transparent background that is bounded by a specified rectangle.

Syntax

HRESULT GetThemeBackgroundRegion(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    const RECT *pRect,
    HRGN *pRegion
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the region. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
pRect
[in] Pointer to a RECT Online link structure that contains, in logical coordinates, the specified rectangle used to compute the region.
pRegion
[out] Pointer to the handle to the computed region.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeBool Function

This is preliminary documentation and is subject to change.

Retrieves the value of a BOOL property from the SysMetrics section of theme data.

Syntax

HRESULT GetThemeBool(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    BOOL *pfVal
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part which contains the BOOL property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types.
pfVal
[out] Pointer to a BOOL that receives the retrieved property value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeColor Function

This is preliminary documentation and is subject to change.

Retrieves the value of a color property.

Syntax

HRESULT GetThemeColor(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    COLORREF *pColor
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the color property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types.
pColor
[out] Pointer to a COLORREF Online link structure that receives the color value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Windows NT Whistler

See Also

Theme Property Typedefs


GetThemeDocumentationProperty Function

This is preliminary documentation and is subject to change.

Retrieves the value for a theme property from the documentation section of the Themes.ini file.

Syntax

HRESULT GetThemeDocumentationProperty(
    LPCWSTR pszThemeName,
    LPCWSTR pszPropertyName,
    LPWSTR pszValueBuff,
    DWORD dwMaxValChars
);

Parameters

pszThemeName
[in] Pointer to a string that contains the name of the theme to query.
pszPropertyName
[in] Pointer to a string that contains name of the theme property to query.
pszValueBuff
[out] Pointer to a string buffer that returns the property value.
dwMaxValChars
[in] Value of type DWORD that specifies the maximum number of characters to return in pszValueBuff.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

If the theme property has been localized in the theme files string table, this function returns the localized version.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Reference


GetThemeEnumValue Function

This is preliminary documentation and is subject to change.

Retrieves the value of an enumerated type property.

Syntax

HRESULT GetThemeEnumValue(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    int *piVal
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the enumerated type property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
piVal
[out] Pointer to an integer that receives the enumerated type value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeFilename Function

This is preliminary documentation and is subject to change.

Retrieves the value of a filename property.

Syntax

HRESULT GetThemeFilename(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    LPWSTR *pszBuff,
    DWORD dwMaxBuffChars
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the filename property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pszBuff
[out] Pointer to a buffer that receives the retrieved file name.
dwMaxBuffChars
[in] DWORD that receives the maximum number of characters in the file name

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeFont Function

This is preliminary documentation and is subject to change.

Retrieves the value of a font property.

Syntax

HRESULT GetThemeFont(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    LOGFONT *pFont
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the font property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pFont
[out] Pointer to a LOGFONT Online link structure that receives the font value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeInt Function

This is preliminary documentation and is subject to change.

Retrieves the value of a integer property.

Syntax

HRESULT GetThemeInt(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    int *piVal
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the integer property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
piVal
[out] Pointer to an integer that receives the retrieved value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeIntList Function

This is preliminary documentation and is subject to change.

Retrieves a list of integer data from a theme.

Syntax

HRESULT GetThemeIntList(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    INTLIST *pIntList
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the list of data to return. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types.
pIntList
[out] Pointer to an INTLIST structure that receives the integer data.

Return Value

Returns S_OK if successful, otherwise an error code.

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | UxTheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

INTLIST


GetThemeLastErrorContext Function

This is preliminary documentation and is subject to change.

Retrieves the full error context information for the last theme application programming interface (API) error on the current thread.

Syntax

HRESULT GetThemeLastErrorContext(
    THEME_ERROR_CONTEXT *pContext
);

Parameters

pContext
[out] Pointer to a THEME_ERROR_CONTEXT structure.

Return Value

Returns S_OK if successful, otherwise an error code.

Remarks

To retrieve the simple error code of the last failure on the current thread, use GetLastError.

Example

The following example shows how to call this function.

THEME_ERROR_CONTEXT myThemeErrorContext;
HRESULT hRslt = GetThemeLastErrorContext(&myThemeErrorContext);

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

FormatThemeMessage


GetThemeMargins Function

This is preliminary documentation and is subject to change.

Retrieves the value of a MARGINS property.

Syntax

HRESULT GetThemeMargins(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    MARGINS *pMargins
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the MARGINS property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pMargins
[out] Pointer to a MARGINS structure that receives the retrieved value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeMetric Function

This is preliminary documentation and is subject to change.

Retrieves the value of a metric property.

Syntax

HRESULT GetThemeMetric(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    int *piVal
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the metric property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
piVal
[out] Pointer to an integer that receives the metric property value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemePartSize Function

This is preliminary documentation and is subject to change.

Calculates the original size of the theme-defined part.

Syntax

HRESULT GetThemePartSize(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    THEMESIZE eSize,
    SIZE *psz
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC) to select fonts into.
iPartId
[in] integer that specifies the part to calculate the size of. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
eSize
[in] Enumerated type that specifies the type of size to retrieve. See THEME_SIZE for a list of type values.
psz
[out] Pointer to a SIZE Online link structure that receives the dimensions of the specified part.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemePosition Function

This is preliminary documentation and is subject to change.

Retrieves the value of a position property.

Syntax

HRESULT GetThemePosition(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    POINT *pPoint
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the position property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pPoint
[out] Pointer to a POINT Online link structure that receives the position value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The part in which the position is located determines the possible state values. For example, if the position is in a checkbox, the state could be checked or unchecked, but in a caption the possible states are active, inactive, or disabled.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemePropertyOrigin Function

This is preliminary documentation and is subject to change.

Retrieves the location of the theme property definition for a property.

Syntax

HRESULT GetThemePropertyOrigin(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    PROPERTYORIGIN *pOrigin
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the theme. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pOrigin
[out] Pointer to a PROPERTYORIGIN enumerated type that indicates where the property was or was not found.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeRect Function

This is preliminary documentation and is subject to change.

Retrieves the value of a RECT Online link property.

Syntax

HRESULT GetThemeRect(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    RECT *pRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part that contains the RECT property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pRect
[out] Pointer to a RECT structure that receives a rectangle.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeString Function

This is preliminary documentation and is subject to change.

Retrieves the value of a string property.

Syntax

HRESULT GetThemeString(
    HTHEME hTheme,
    int iPartId,
    int iStateId,
    int iPropId,
    LPWSTR pszBuff,
    DWORD dwMaxBuffChars
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part which contains the string property. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
iPropId
[in] integer that specifies the property to retrieve. See Theme Property Types
pszBuff
[out] Pointer to a buffer that receives the string value.
dwMaxBuffChars
[in] DWORD that specifies the maximum number of characters pszBuff can contain.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeSysBool Function

This is preliminary documentation and is subject to change.

Retrieves the Boolean value of a system metric such as flat menus, fading tool tips, and so forth.

Syntax

BOOL GetThemeSysBool(
    HTHEME hTheme,
    int iBoolID
);

Parameters

hTheme
[in] Handle to theme data.
iBoolID
[in] integer that specifies the system Boolean metric desired. These metrics are specified by the constants defined in THEME_METRICS_BOOLS.

Return Value

Value of desired system metric.

Remarks

If the theme data handle is non-NULL, this function returns the desired BOOL from the SysMetrics section of the theme. If the theme data handle is NULL, this function returns the value of the global system metric of the same type, that is, FLATMENUS.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeSysColor Function

This is preliminary documentation and is subject to change.

Retrieves the value of a system color.

Syntax

COLORREF GetThemeSysColor(
    HTHEME hTheme,
    int iColorID
);

Parameters

hTheme
[in] Handle to theme data.
iColorID
[in] integer that specifies the color number. The colors are specified by the theme metrics color constants defined in THEME_METRICS_COLORS.

Return Value

The value of the specified system color.

Remarks

If the theme data handle is non-NULL, this function returns the color from the SysMetrics section of the current theme. If the theme data handle is NULL, this function returns the color matching the global system color.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeSysColorBrush Function

This is preliminary documentation and is subject to change.

Retrieves a system color brush.

Syntax

HBRUSH GetThemeSysColorBrush(
    HTHEME hTheme,
    int iColorID
);

Parameters

hTheme
[in] Handle to theme data.
iColorID
[in] integer that specifies the number of the desired system color. The color constants are defined in THEME_METRICS_COLORS.

Return Value

Handle to brush data.

Remarks

If the theme data handle is non-NULL, GetThemeSysColor returns the brush that matches the specified color from the SysMetrics section of the theme. If the theme data handle is NULL, the function returns the brush matching the global system color.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeSysFont Function

This is preliminary documentation and is subject to change.

Retrieves the LOGFONT Online link of a system font.

Syntax

HRESULT GetThemeSysFont(
    HTHEME hTheme,
    int iFontID,
    LOGFONT *plf
);

Parameters

hTheme
[in] Handle to theme data.
iFontID
[in] integer that specifies a system font. These fonts are specified using the constants defined in THEME_METRICS_FONTS.
plf
[out] Pointer to a LOGFONT structure that receives the font information from this function.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

If the theme data handle is non-NULL, this function returns the desired LOGFONT from the SysMetrics section of the theme. If the theme data handle is NULL, the function returns the value of the global system metric of the same type, that is, CAPTIONFONT.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeSysInt Function

This is preliminary documentation and is subject to change.

Retrieves the value of a system integer.

Syntax

HRESULT GetThemeSysInt(
    HTHEME hTheme,
    int iIntID,
    int *piValue
);

Parameters

hTheme
[in] Handle to theme data.
iIntID
[in] integer that specifies the desired system integer. These integers are specified in THEME_METRICS_INTS.
piValue
[in] Pointer to an integer that receives the system integer value.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeSysSize Function

This is preliminary documentation and is subject to change.

Retrieves the value of a system size metric from theme data.

Syntax

int GetThemeSysSize(
    HTHEME hTheme,
    int iSizeID
);

Parameters

hTheme
[in] Handle to theme data.
iSizeID
[in] integer that specifies the system size metric desired. These metrics are specified in THEME_METRICS_SIZES.

Return Value

The size in pixels.

Remarks

If the theme data handle is non-NULL, this function returns the desired size from the SysMetrics section of the theme. If the theme data handle is NULL, the function returns the size of the global system metric of the same type, that is, BORDERWIDTH.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeSysString Function

This is preliminary documentation and is subject to change.

Retrieves the value of a system string.

Syntax

HRESULT GetThemeSysString(
    HTHEME hTheme,
    int iStringID,
    LPWSTR pszStringBuff,
    DWORD dwMaxStringChars
);

Parameters

hTheme
[in] Handle to theme data.
iStringID
[in] integer that specifies a system string. These strings are specified in THEME_METRICS_STRINGS.
pszStringBuff
[out] Pointer to the buffer that receives the string value from this function.
dwMaxStringChars
[in] DWORD that specifies the maximum number of characters the string buffer can hold.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

If the theme data handle is non-NULL, this function returns the desired string from the SysMetrics section of the theme. If the theme data handle is NULL, this function returns the value of the global system metric of the same type, that is, CSSNAME.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


GetThemeTextExtent Function

This is preliminary documentation and is subject to change.

Calculates the size and location of the specified text when rendered in the theme font.

Syntax

HRESULT GetThemeTextExtent(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    LPCWSTR pszText,
    int iCharCount,
    DWORD dwTextFlags,
    const RECT *pBoundingRect,
    RECT *pExtentRect
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] Handle to a device context (HDC) to select the font into.
iPartId
[in] integer that specifies the part in which the text will be drawn. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
pszText
[in] Pointer to a string that contains the text to draw.
iCharCount
[in] integer that contains the number of characters to draw. If the parameter is set to -1, all the characters in the string are drawn.
dwTextFlags
[in] DWORD that contains one or more values that specify the string's formatting. See Format Values for possible parameter values.
pBoundingRect
[in] [optional] Pointer to a RECT Online link structure that contains the rectangle used to control layout of the text.
pExtentRect
[out] Pointer to a RECT structure that contains, in logical coordinates, the rectangle required to fit the rendered text.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetThemeTextMetrics Function

This is preliminary documentation and is subject to change.

Retrieves information about the theme-specified font for a particular part.

Syntax

HRESULT GetThemeTextMetrics(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    TEXTMETRIC *ptm
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] [optional] Handle to a device context (HDC) to use for screen context.
iPartId
[in] integer that specifies the part to retrieve font information about. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
ptm
[out] Pointer to a TEXTMETRIC Online link structure that receives the font information.

Return Value

Returns S_OK if successful, or an error value otherwise.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


GetWindowTheme Function

This is preliminary documentation and is subject to change.

If the window is themed, the GetWindowTheme function returns the most recent theme handle from OpenThemeData. If the window is not themed, GetWindowTheme returns NULL.

Syntax

HTHEME GetWindowTheme(
    HWND hWnd
);

Parameters

hWnd
[in] Handle of the themed window.

Return Value

The most recent theme handle from OpenThemeData.

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


HitTestThemeBackground Function

This is preliminary documentation and is subject to change.

Retrieves a hit test code for a point in the theme-specified background.

Syntax

HRESULT HitTestThemeBackground(
    HTHEME hTheme,
    HDC hdc,
    int iPartId,
    int iStateId,
    DWORD dwOptions,
    const RECT *pRect,
    HRGN hrgn,
    POINT ptTest,
    WORD *pwHitTestCode
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
hdc
[in] [optional] Handle to a device context (HDC) to use when drawing.
iPartId
[in] integer that specifies the part. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.
dwOptions
[in] DWORD that specifies the hit test options. See Hit Test Options for a list of options.
pRect
[in] Pointer to a RECT Online link structure that contains, in logical coordinates, the rectangle that bounds the background.
hrgn
[in] [optional] Handle to a region that can be used to specify the bounds of a hit test area.
ptTest
[in] POINT Online link structure that contains the coordinates of the point.
pwHitTestCode
[out] WORD that receives the hit test code that indicates whether the point in ptTest is in the background area bounded by pRect or hrgn. See Hit Test Return Values for a list of values returned.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The values in ptTest and pRect should be in the same coordinate system, such as client or screen. If the hrgn parameter is used, it must be specified in the same coordinates as pRect and ptTest.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

Theme Property Typedefs


IsAppThemed Function

This is preliminary documentation and is subject to change.

Reports whether the current application's user interface is being displayed using themes.

Syntax

BOOL IsAppThemed(VOID);

Return Value

Returns one of the following values.

TRUE | The application is themed.
FALSE | The application is not themed.

Remarks

Theming can be turned off in a control panel; thus an application can support themes and still not be themed at a given time.

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


IsThemeActive Function

This is preliminary documentation and is subject to change.

Tests if a theme for the current application is active.

Syntax

BOOL IsThemeActive(VOID);

Return Value

Returns one of the following values.

TRUE | A theme is enabled, and theme-aware windows should call OpenThemeData to start using theme drawing services.
FALSE | A theme is not enabled, and the window message handler does not need to make another call to IsThemeActive until it receives a WM_THEMECHANGED message.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


IsThemeBackgroundPartiallyTransparent Function

This is preliminary documentation and is subject to change.

Retrieves whether the theme-specified background has transparent pieces or alpha-blended pieces.

Syntax

BOOL IsThemeBackgroundPartiallyTransparent(
    HTHEME hTheme,
    int iPartId,
    int iStateId
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.

Return Value

Returns one of the following values.

TRUE | The theme-specified background for a particular iPartId and iStateId has transparent pieces or alpha-blended pieces.
FALSE | The theme-specified background for a particular iPartId and iStateId does not have transparent pieces or alpha-blended pieces.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


IsThemePartDefined Function

This is preliminary documentation and is subject to change.

Retrieves whether a theme has defined parameters for the specified part and state.

Syntax

BOOL IsThemePartDefined(
    HTHEME hTheme,
    int iPartId,
    int iStateId
);

Parameters

hTheme
[in] Handle to a window's specified theme data. Use OpenThemeData to create an HTHEME.
iPartId
[in] integer that specifies the part. See Theme Parts and States.
iStateId
[in] integer that specifies the state of the part. See Theme Parts and States.

Return Value

Returns one of the following values.

TRUE | The theme has defined parameters for the specified iPartId and iStateId
FALSE | The theme does not have defined parameters for the specified iPartId and iStateId

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


OpenThemeData Function

This is preliminary documentation and is subject to change.

Opens the theme data for a window and its associated class.

Syntax

HTHEME OpenThemeData(
    HWND hwnd,
    LPCWSTR pszClassList
);

Parameters

hwnd
[in] Handle of the window for which theme data is required.
pszClassList
[in] Pointer to a string that contains a semicolon-separated list of classes.

Return Value

OpenThemeData tries to match each class, one at a time, to a class data section in the active theme. If a match is found, an associated HTHEME handle is returned. If no match is found NULL is returned.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


SetThemeAppProperties Function

This is preliminary documentation and is subject to change.

Sets the flags that determine how themes are implemented in the calling application.

Syntax

void SetThemeAppProperties(
    DWORD dwFlags
);

Parameters

dwFlags
DWORD that specifies one or more of the following bit flags, which can be combined with a logical OR.
STAP_ALLOW_NONCLIENT
Specifies that the nonclient areas of application windows will have themes applied.
STAP_ALLOW_CONTROLS
Specifies that the controls used in an application will have themes applied.
STAP_ALLOW_WEBCONTENT
Specifies that Web content displayed in an application will have themes applied.

Return Value

No return value.

Example

This example combines flags and calls this function as shown.

DWORD dwFlags = (STAP_ALLOW_NONCLIENT | STAP_ALLOW_CONTROLS | STAP_ALLOW_WEBCONTENT);
SetThemeAppProperties(dwFlags);

Function Information

Stock Implementation | UxTheme.dll version 1.0 or later
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler

See Also

GetThemeAppProperties


SetWindowTheme Function

This is preliminary documentation and is subject to change.

Causes a window to use a different set of theme information than its class normally uses.

Syntax

HRESULT SetWindowTheme(
    HWND hwnd,
    LPCWSTR pszSubAppName,
    LPCWSTR pszSubIdList
);

Parameters

hwnd
[in] Handle to the window whose theme information is to be changed.
pszSubAppName
[in] Pointer to a string that contains the application name to use in place of the calling application's name. If this parameter is NULL, the calling application's name is used.
pszSubIdList
[in] Pointer to a string that contains a semicolon-separated list of class identifier (CLSID) names to use in place of the actual list passed by the window's class. If this parameter is NULL, the identifier (ID) list from the calling class is used.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The theme manager retains the pszSubAppName and the pszSubIdList associations through the lifetime of the window, even if themes subsequently change. The window is sent a WM_THEMECHANGED message at the end of a SetWindowTheme call, so that the new theme can be found and applied.

When pszSubAppName and pszSubIdList are NULL, the theme manager removes the previously applied associations. To turn off theme-awareness for the specified window, pass an empty string, (L" "), which will not match any section entries.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


SetWindowThemeStyle Function

This is preliminary documentation and is subject to change.

Causes a window to be themed using a different nonclient style.

Syntax

HRESULT SetWindowThemeStyle(
    HWND hwnd,
    BOOL fApply,
    BOOL fFrame
);

Parameters

hwnd
[in] Handle to the window whose theme information is to be changed. Cannot be NULL.
fApply
[in] If TRUE, the style values are set on the target window. If FALSE, the previously set theme style values are cleared.
fFrame
[in] If TRUE, the target window should be themed as a nonclient frame. This is usually only the case for top-level windows.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

The Theme Manager retains these nonclient style settings through the lifetime of the window, even if themes are subsequently changed. The target window is sent a WM_THEMECHANGED message after completion of this call so that the new styles can be applied.

Function Information

Stock Implementation | UxTheme.dll
Custom Implementation | No
Header | uxtheme.h
Import library | UxTheme.lib
Minimum operating systems | Whistler


Theme Structures

This is preliminary documentation and is subject to change.

This section describes the data structures associated with themes.


INTLIST Structure

This is preliminary documentation and is subject to change.

Retrieve an array or list of integer data items from a theme.

Syntax

typedef struct _INTLIST {
    int iValueCount;
    int iValues[MAX_INTLIST_COUNT];
} INTLIST, *PINTLIST;

Members

iValueCount
Number of values in the list.
iValues[MAX_INTLIST_COUNT]
List of integers. The constant MAX_INTLIST_COUNT, by definition, is equal to 10.

Remarks

The lists are returned by GetThemeIntList.

Structure Information

Header | UxTheme.h
Minimum operating systems | Whistler


MARGINS Structure

This is preliminary documentation and is subject to change.

Defines the margins of theme-aware windows.

Syntax

typedef struct _MARGINS {
    int cxLeftWidth;
    int cxRightWidth;
    int cyTopHeight;
    int cyBottomHeight;
} MARGINS, *PMARGINS;

Members

cxLeftWidth
Width of the left border that retains its size.
cxRightWidth
Width of the right border that retains its size.
cyTopHeight
Height of the top border that retains its size.
cyBottomHeight
Height of the bottom border that retains its size.

Structure Information

Header | uxtheme.h
Minimum operating systems | Whistler


THEME_ERROR_CONTEXT Structure

This is preliminary documentation and is subject to change.

Contains the full error context information for the last theme application programming interface (API) failure on the current thread.

Syntax

typedef struct {
    HRESULT hr;
    WCHAR szMsgParam1[_MAX_PATH];
    WCHAR szMsgParam2[_MAX_PATH];
    WCHAR szFileName[_MAX_PATH];
    WCHAR szSourceLine[_MAX_PATH];
    int iLineNum;
} THEME_ERROR_CONTEXT, *PTHEME_ERROR_CONTEXT;

Members

hr
Error code from last error.
szMsgParam1[_MAX_PATH]
Value of first parameter for message.
szMsgParam2[_MAX_PATH]
Value of second parameter for message.
szFileName[_MAX_PATH]
Value of associated file name.
szSourceLine[_MAX_PATH]
Content of the relevant line of source code, if any.
iLineNum
The relevant line number in the source code.

Remarks

Pass a pointer to a structure of this type to GetThemeLastErrorContext to retrieve the full error-context information.

Structure Information

Header | UxTheme.h
Minimum operating systems | Whistler

See Also

GetThemeLastErrorContext


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Tuesday, February 13, 2001.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

Reason | Remedy
Destination topic not in the selected active subset. | Set active subset to an appropriate subset or to (Entire Collection).
Link is out-of-date. | Use the index or search function instead.
Link was authored incorrectly. | Use the index or search function instead.
Problems with the MSDN installation. | Uninstall the MSDN Library and then rerun Setup.


Animation Control Reference

This section contains information about the programming elements used with animation controls.

Animation Control Styles

Messages
ACM_OPEN
ACM_PLAY
ACM_STOP

Macros
Animate_Create
Animate_Close
Animate_Open
Animate_OpenEx
Animate_Play
Animate_Seek
Animate_Stop

Notifications
ACN_START
ACN_STOP


ComboBoxEx Control Reference

This section contains information about the programming elements used with ComboBoxEx controls.

ComboBoxEx control extended styles

Messages
CBEM_DELETEITEM
CBEM_GETCOMBOCONTROL
CBEM_GETEDITCONTROL
CBEM_GETEXTENDEDSTYLE
CBEM_GETIMAGELIST
CBEM_GETITEM
CBEM_GETUNICODEFORMAT
CBEM_HASEDITCHANGED
CBEM_INSERTITEM
CBEM_SETEXTENDEDSTYLE
CBEM_SETIMAGELIST
CBEM_SETITEM
CBEM_SETUNICODEFORMAT

Notifications
CBEN_BEGINEDIT
CBEN_DELETEITEM
CBEN_DRAGBEGIN
CBEN_ENDEDIT
CBEN_GETDISPINFO
CBEN_INSERTITEM
NM_SETCURSOR (ComboBoxEx)

Structures
COMBOBOXEXITEM
NMCBEDRAGBEGIN
NMCBEENDEDIT
NMCOMBOBOXEX


Common Control Reference

This section contains information about the programming elements used with the updated common controls delivered in Whistler.

Common Control Window Classes

Common Control Styles

Functions
GetEffectiveClientRect
GetMUILanguage
InitCommonControls
InitCommonControlsEx
InitMUILanguage
ShowHideMenuCtl

Messages
CCM_GETUNICODEFORMAT
CCM_GETVERSION
CCM_SETUNICODEFORMAT
CCM_SETVERSION
WM_NOTIFY
WM_NOTIFYFORMAT

Utility Macros
FORWARD_WM_NOTIFY
HANDLE_WM_NOTIFY
INDEXTOSTATEIMAGEMASK

Notifications
NM_CHAR
NM_CLICK
NM_CUSTOMDRAW
NM_DBLCLK
NM_HOVER
NM_KEYDOWN
NM_KILLFOCUS
NM_NCHITTEST
NM_OUTOFMEMORY
NM_RCLICK
NM_RDBLCLK
NM_RELEASEDCAPTURE
NM_RETURN
NM_SETCURSOR
NM_SETFOCUS
NM_TOOLTIPSCREATED

Structures
COLORSCHEME
INITCOMMONCONTROLSEX
NMCHAR
NMHDR
NMKEY
NMMOUSE
NMOBJECTNOTIFY
NMTOOLTIPSCREATED


Custom Draw Reference

This section contains information about the API elements used for performing custom draw.

Notifications
NM_CUSTOMDRAW
NM_CUSTOMDRAW (header)
NM_CUSTOMDRAW (list view)
NM_CUSTOMDRAW (rebar)
NM_CUSTOMDRAW (toolbar)
NM_CUSTOMDRAW (ToolTip)
NM_CUSTOMDRAW (trackbar)
NM_CUSTOMDRAW (tree view)

Structures
NMCUSTOMDRAW
NMLVCUSTOMDRAW
NMTBCUSTOMDRAW
NMTTCUSTOMDRAW
NMTVCUSTOMDRAW


Date and Time Picker Control Reference

This section contains information about the following API elements used with date and time picker controls.

Date and time picker control styles

Messages
DTM_GETMCCOLOR
DTM_GETMCFONT
DTM_GETMONTHCAL
DTM_GETRANGE
DTM_GETSYSTEMTIME
DTM_SETFORMAT
DTM_SETMCCOLOR
DTM_SETMCFONT
DTM_SETRANGE
DTM_SETSYSTEMTIME

Utility Macros
DateTime_GetMonthCal
DateTime_GetMonthCalColor
DateTime_GetMonthCalFont
DateTime_GetRange
DateTime_GetSystemtime
DateTime_SetFormat
DateTime_SetMonthCalColor
DateTime_SetMonthCalFont
DateTime_SetRange
DateTime_SetSystemtime

Notifications
DTN_CLOSEUP
DTN_DATETIMECHANGE
DTN_DROPDOWN
DTN_FORMAT
DTN_FORMATQUERY
DTN_USERSTRING
DTN_WMKEYDOWN
NM_KILLFOCUS (date time)
NM_SETFOCUS (date time)

Structures
NMDATETIMECHANGE
NMDATETIMEFORMAT
NMDATETIMEFORMATQUERY
NMDATETIMESTRING
NMDATETIMEWMKEYDOWN


Drag List Box Reference

The following functions, notification messages, and structures are associated with drag list boxes.

Functions
DrawInsert
LBItemFromPt
MakeDragList

Notifications
DL_BEGINDRAG
DL_CANCELDRAG
DL_DRAGGING
DL_DROPPED

Structures
DRAGLISTINFO


Flat Scroll Bars Reference

This section contains information on the following new APIs for controlling flat scroll bars:

InitializeFlatSB
FlatSB_EnableScrollBar
FlatSB_GetScrollInfo
FlatSB_GetScrollPos
FlatSB_GetScrollProp
FlatSB_GetScrollRange
FlatSB_SetScrollInfo
FlatSB_SetScrollPos
FlatSB_SetScrollProp
FlatSB_SetScrollRange
FlatSB_ShowScrollBar
UninitializeFlatSB


Hot Key Control Reference

This section contains information about the following programming elements used with hot key controls.

Hot Key Control Messages

The following messages are associated with hot key controls.

HKM_GETHOTKEY

HKM_SETHOTKEY

HKM_SETRULES


Image List Reference

This section contains information about the programming elements used with image lists.

Functions
ImageList_Add
ImageList_AddMasked
ImageList_BeginDrag
ImageList_Copy
ImageList_Create
ImageList_Destroy
ImageList_DragEnter
ImageList_DragLeave
ImageList_DragMove
ImageList_DragShowNolock
ImageList_Draw
ImageList_DrawEx
ImageList_DrawIndirect
ImageList_Duplicate
ImageList_EndDrag
ImageList_GetBkColor
ImageList_GetDragImage
ImageList_GetIcon
ImageList_GetIconSize
ImageList_GetImageCount
ImageList_GetImageInfo
ImageList_LoadImage
ImageList_Merge
ImageList_Read
ImageList_Remove
ImageList_Replace
ImageList_ReplaceIcon
ImageList_SetBkColor
ImageList_SetDragCursorImage
ImageList_SetIconSize
ImageList_SetImageCount
ImageList_SetOverlayImage
ImageList_Write

Macros
ImageList_AddIcon
ImageList_ExtractIcon
ImageList_LoadBitmap
ImageList_RemoveAll
INDEXTOOVERLAYMASK

Structures
IMAGEINFO
IMAGELISTDRAWPARAMS


IP Address Control Reference

This section contains information about the following API elements used with IP address controls.

Messages
IPM_CLEARADDRESS
IPM_GETADDRESS
IPM_ISBLANK
IPM_SETADDRESS
IPM_SETFOCUS
IPM_SETRANGE

Notifications
IPN_FIELDCHANGED

Utility Macros
MAKEIPRANGE
MAKEIPADDRESS
FIRST_IPADDRESS
SECOND_IPADDRESS
THIRD_IPADDRESS
FOURTH_IPADDRESS

Structures
NMIPADDRESS


List-View Control Reference

This section contains information about the programming elements used with list-view controls.

List-view window styles

Extended list-view styles

List-view item states

New for common controls version 6.0

Messages
LVM_ENABLEGROUPVIEW
LVM_GETGROUPINFO
LVM_GETGROUPMETRICS
LVM_GETINSERTMARK
LVM_GETINSERTMARKCOLOR
LVM_GETINSERTMARKRECT
LVM_GETTILEINFO
LVM_GETTILEVIEWINFO
LVM_HASGROUP
LVM_INSERTGROUP
LVM_INSERTGROUPSORTED
LVM_INSERTMARKHITTEST
LVM_REMOVEALLGROUPS
LVM_REMOVEGROUP
LVM_SETGROUPINFO
LVM_SETGROUPMETRICS
LVM_SETINSERTMARK
LVM_SETINSERTMARKCOLOR
LVM_SETTILEINFO
LVM_SETTILEVIEWINFO
LVM_SORTGROUPS

Structures
LV_GROUP
LVGROUPMETRICS
LVINSERTGROUPSORTED
LVINSERTMARK
LVITEM
LVTILEINFO
LVTILEVIEWINFO

List-view API for common controls version 5.81 and Earlier

Messages
LVM_APPROXIMATEVIEWRECT
LVM_ARRANGE
LVM_CREATEDRAGIMAGE
LVM_DELETEALLITEMS
LVM_DELETECOLUMN
LVM_DELETEITEM
LVM_EDITLABEL
LVM_ENSUREVISIBLE
LVM_FINDITEM
LVM_GETBKCOLOR
LVM_GETBKIMAGE
LVM_GETCALLBACKMASK
LVM_GETCOLUMN
LVM_GETCOLUMNORDERARRAY
LVM_GETCOLUMNWIDTH
LVM_GETCOUNTPERPAGE
LVM_GETEDITCONTROL
LVM_GETEXTENDEDLISTVIEWSTYLE
LVM_GETHEADER
LVM_GETHOTCURSOR
LVM_GETHOTITEM
LVM_GETHOVERTIME
LVM_GETIMAGELIST
LVM_GETISEARCHSTRING
LVM_GETITEM
LVM_GETITEMCOUNT
LVM_GETITEMPOSITION
LVM_GETITEMRECT
LVM_GETITEMSPACING
LVM_GETITEMSTATE
LVM_GETITEMTEXT
LVM_GETNEXTITEM
LVM_GETNUMBEROFWORKAREAS
LVM_GETORIGIN
LVM_GETSELECTEDCOUNT
LVM_GETSELECTIONMARK
LVM_GETSTRINGWIDTH
LVM_GETSUBITEMRECT
LVM_GETTEXTBKCOLOR
LVM_GETTEXTCOLOR
LVM_GETTOOLTIPS
LVM_GETTOPINDEX
LVM_GETUNICODEFORMAT
LVM_GETVIEWRECT
LVM_GETWORKAREAS
LVM_HITTEST
LVM_INSERTCOLUMN
LVM_INSERTITEM
LVM_REDRAWITEMS
LVM_SCROLL
LVM_SETBKCOLOR
LVM_SETBKIMAGE
LVM_SETCALLBACKMASK
LVM_SETCOLUMN
LVM_SETCOLUMNORDERARRAY
LVM_SETCOLUMNWIDTH
LVM_SETEXTENDEDLISTVIEWSTYLE
LVM_SETHOTCURSOR
LVM_SETHOTITEM
LVM_SETHOVERTIME
LVM_SETICONSPACING
LVM_SETIMAGELIST
LVM_SETITEM
LVM_SETITEMCOUNT
LVM_SETITEMPOSITION
LVM_SETITEMPOSITION32
LVM_SETITEMSTATE
LVM_SETITEMTEXT
LVM_SETSELECTIONMARK
LVM_SETTEXTBKCOLOR
LVM_SETTEXTCOLOR
LVM_SETTOOLTIPS
LVM_SETUNICODEFORMAT
LVM_SETWORKAREAS
LVM_SORTITEMS
LVM_SORTITEMSEX
LVM_SUBITEMHITTEST
LVM_UPDATE

Utility Macros
ListView_ApproximateViewRect
ListView_Arrange
ListView_CreateDragImage
ListView_DeleteAllItems
ListView_DeleteColumn
ListView_DeleteItem
ListView_EditLabel
ListView_EnsureVisible
ListView_FindItem
ListView_GetBkColor
ListView_GetBkImage
ListView_GetCallbackMask
ListView_GetCheckState
ListView_GetColumn
ListView_GetColumnOrderArray
ListView_GetColumnWidth
ListView_GetCountPerPage
ListView_GetEditControl
ListView_GetExtendedListViewStyle
ListView_GetHeader
ListView_GetHotCursor
ListView_GetHotItem
ListView_GetImageList
ListView_GetISearchString
ListView_GetItem
ListView_GetItemCount
ListView_GetItemPosition
ListView_GetItemRect
ListView_GetItemSpacing
ListView_GetItemState
ListView_GetItemText
ListView_GetNextItem
ListView_GetNumberOfWorkAreas
ListView_GetOrigin
ListView_GetSelectedCount
ListView_GetSelectionMark
ListView_GetStringWidth
ListView_GetSubItemRect
ListView_GetTextBkColor
ListView_GetTextColor
ListView_GetToolTips
ListView_GetTopIndex
ListView_GetUnicodeFormat
ListView_GetViewRect
ListView_GetWorkAreas
ListView_HitTest
ListView_InsertColumn
ListView_InsertItem
ListView_RedrawItems
ListView_Scroll
ListView_SetBkColor
ListView_SetBkImage
ListView_SetCallbackMask
ListView_SetCheckState
ListView_SetColumn
ListView_SetColumnOrderArray
ListView_SetColumnWidth
ListView_SetExtendedListViewStyle
ListView_SetExtendedListViewStyleEx
ListView_SetHotCursor
ListView_SetHotItem
ListView_SetIconSpacing
ListView_SetImageList
ListView_SetItem
ListView_SetItemCount
ListView_SetItemCountEx
ListView_SetItemPosition
ListView_SetItemPosition32
ListView_SetItemState
ListView_SetItemText
ListView_SetSelectionMark
ListView_SetTextBkColor
ListView_SetTextColor
ListView_SetToolTips
ListView_SetUnicodeFormat
ListView_SetWorkAreas
ListView_SortItems
ListView_SortItemsEx
ListView_SubItemHitTest
ListView_Update

Notifications
LVN_BEGINDRAG
LVN_BEGINLABELEDIT
LVN_BEGINRDRAG
LVN_COLUMNCLICK
LVN_DELETEALLITEMS
LVN_DELETEITEM
LVN_ENDLABELEDIT
LVN_GETDISPINFO
LVN_GETINFOTIP
LVN_HOTTRACK
LVN_INSERTITEM
LVN_ITEMACTIVATE
LVN_ITEMCHANGED
LVN_ITEMCHANGING
LVN_KEYDOWN
LVN_MARQUEEBEGIN
LVN_ODCACHEHINT
LVN_ODFINDITEM
LVN_ODSTATECHANGED
LVN_SETDISPINFO
NM_CLICK (list view)
NM_CUSTOMDRAW (list view)
NM_DBLCLK (list view)
NM_HOVER (list view)
NM_KILLFOCUS (list view)
NM_RCLICK (list view)
NM_RDBLCLK (list view)
NM_RELEASEDCAPTURE (list view)
NM_RETURN (list view)
NM_SETFOCUS (list view)

Structures
LV_COLUMN
LV_DISPINFO
LV_FINDINFO
LV_HITTESTINFO
LV_ITEM
LV_KEYDOWN
LVBKIMAGE
LVCOLUMN
LVFINDINFO
LVHITTESTINFO
LVITEM
NM_LISTVIEW
NMITEMACTIVATE
NMLISTVIEW
NMLVCACHEHINT
NMLVCUSTOMDRAW
NMLVDISPINFO
NMLVFINDITEM
NMLVGETINFOTIP
NMLVKEYDOWN
NMLVODSTATECHANGE

List-view window styles

Extended list-view styles

List-view item states

List-View Control Messages

List-View Control Macros

List-View Control Notification Messages

List-View Control Structures


List-View Control Macros

This section contains information about the macros used with list-view control messages.

ListView_ApproximateViewRect

ListView_Arrange

ListView_CreateDragImage

ListView_DeleteAllItems

ListView_DeleteColumn

ListView_DeleteItem

ListView_EditLabel

ListView_EnsureVisible

ListView_FindItem

ListView_GetBkColor

ListView_GetBkImage

ListView_GetCallbackMask

ListView_GetCheckState

ListView_GetColumn

ListView_GetColumnOrderArray

ListView_GetColumnWidth

ListView_GetCountPerPage

ListView_GetEditControl

ListView_GetExtendedListViewStyle

ListView_GetHeader

ListView_GetHotCursor

ListView_GetHotItem

ListView_GetHoverTime

ListView_GetImageList

ListView_GetISearchString

ListView_GetItem

ListView_GetItemCount

ListView_GetItemPosition

ListView_GetItemRect

ListView_GetItemSpacing

ListView_GetItemState

ListView_GetItemText

ListView_GetNextItem

ListView_GetNumberOfWorkAreas

ListView_GetOrigin

ListView_GetSelectedCount

ListView_GetSelectionMark

ListView_GetStringWidth

ListView_GetSubItemRect

ListView_GetTextBkColor

ListView_GetTextColor

ListView_GetToolTips

ListView_GetTopIndex

ListView_GetUnicodeFormat

ListView_GetViewRect

ListView_GetWorkAreas

ListView_HitTest

ListView_InsertColumn

ListView_InsertItem

ListView_RedrawItems

ListView_Scroll

ListView_SetBkColor

ListView_SetBkImage

ListView_SetCallbackMask

ListView_SetColumn

ListView_SetColumnOrderArray

ListView_SetColumnWidth

ListView_SetExtendedListViewStyle

ListView_SetExtendedListViewStyleEx

ListView_SetHotCursor

ListView_SetHotItem

ListView_SetHoverTime

ListView_SetIconSpacing

ListView_SetImageList

ListView_SetItem

ListView_SetItemCount

ListView_SetItemCountEx

ListView_SetItemPosition

ListView_SetItemPosition32

ListView_SetItemState

ListView_SetItemText

ListView_SetSelectionMark

ListView_SetTextBkColor

ListView_SetTextColor

ListView_SetToolTips

ListView_SetUnicodeFormat

ListView_SetWorkAreas

ListView_SortItems

ListView_SubItemHitTest

ListView_Update


List-View Control Messages

This section contains information about messages used with list-view controls.

LVM_APPROXIMATEVIEWRECT

LVM_ARRANGE

LVM_CREATEDRAGIMAGE

LVM_DELETEALLITEMS

LVM_DELETECOLUMN

LVM_DELETEITEM

LVM_EDITLABEL

LVM_ENSUREVISIBLE

LVM_FINDITEM

LVM_GETBKCOLOR

LVM_GETBKIMAGE

LVM_GETCALLBACKMASK

LVM_GETCOLUMN

LVM_GETCOLUMNORDERARRAY

LVM_GETCOLUMNWIDTH

LVM_GETCOUNTPERPAGE

LVM_GETEDITCONTROL

LVM_GETEXTENDEDLISTVIEWSTYLE

LVM_GETHEADER

LVM_GETHOTCURSOR

LVM_GETHOTITEM

LVM_GETHOVERTIME

LVM_GETIMAGELIST

LVM_GETISEARCHSTRING

LVM_GETITEM

LVM_GETITEMCOUNT

LVM_GETITEMPOSITION

LVM_GETITEMRECT

LVM_GETITEMSPACING

LVM_GETITEMSTATE

LVM_GETITEMTEXT

LVM_GETNEXTITEM

LVM_GETNUMBEROFWORKAREAS

LVM_GETORIGIN

LVM_GETSELECTEDCOUNT

LVM_GETSELECTIONMARK

LVM_GETSTRINGWIDTH

LVM_GETSUBITEMRECT

LVM_GETTEXTBKCOLOR

LVM_GETTEXTCOLOR

LVM_GETTOOLTIPS

LVM_GETTOPINDEX

LVM_GETUNICODEFORMAT

LVM_GETVIEWRECT

LVM_GETWORKAREAS

LVM_HITTEST

LVM_INSERTCOLUMN

LVM_INSERTITEM

LVM_REDRAWITEMS

LVM_SCROLL

LVM_SETBKCOLOR

LVM_SETBKIMAGE

LVM_SETCALLBACKMASK

LVM_SETCOLUMN

LVM_SETCOLUMNORDERARRAY

LVM_SETCOLUMNWIDTH

LVM_SETEXTENDEDLISTVIEWSTYLE

LVM_SETHOTCURSOR

LVM_SETHOTITEM

LVM_SETHOVERTIME

LVM_SETICONSPACING

LVM_SETIMAGELIST

LVM_SETITEM

LVM_SETITEMCOUNT

LVM_SETITEMPOSITION

LVM_SETITEMPOSITION32

LVM_SETITEMSTATE

LVM_SETITEMTEXT

LVM_SETSELECTIONMARK

LVM_SETTEXTBKCOLOR

LVM_SETTEXTCOLOR

LVM_SETTOOLTIPS

LVM_SETUNICODEFORMAT

LVM_SETWORKAREAS

LVM_SORTITEMS

LVM_SUBITEMHITTEST

LVM_UPDATE


List-View Control Notification Messages

This section contains information about the notification messages sent by list-view controls.

LVN_BEGINDRAG

LVN_BEGINLABELEDIT

LVN_BEGINRDRAG

LVN_COLUMNCLICK

LVN_DELETEALLITEMS

LVN_DELETEITEM

LVN_ENDLABELEDIT

LVN_GETDISPINFO

LVN_GETINFOTIP

LVN_INSERTITEM

LVN_HOTTRACK

LVN_ITEMACTIVATE

LVN_ITEMCHANGED

LVN_ITEMCHANGING

LVN_KEYDOWN

LVN_MARQUEEBEGIN

LVN_ODCACHEHINT

LVN_ODFINDITEM

LVN_ODSTATECHANGED

LVN_SETDISPINFO

NM_CLICK (list view)

NM_CUSTOMDRAW (list view)

NM_DBLCLK (list view)

NM_HOVER (list view)

NM_KILLFOCUS (list view)

NM_RCLICK (list view)

NM_RDBLCLK (list view)

NM_RELEASEDCAPTURE (list view)

NM_RETURN (list view)

NM_SETFOCUS (list view)


List-View Control Structures

This section contains information about the structures used with list-view controls.

LVBKIMAGE

LVCOLUMN

LVFINDINFO

LVHITTESTINFO

LVITEM

NMITEMACTIVATE

NMLISTVIEW

NMLVCACHEHINT

NMLVCUSTOMDRAW

NMLVDISPINFO

NMLVFINDITEM

NMLVGETINFOTIP

NMLVKEYDOWN

NMLVODSTATECHANGE


Month Calendar Control Reference

This section contains information about the following programming elements used with month calendar controls.

Month calendar control styles

Month calendar day numbers

Messages
MCM_GETCOLOR
MCM_GETCURSEL
MCM_GETFIRSTDAYOFWEEK
MCM_GETMAXSELCOUNT
MCM_GETMAXTODAYWIDTH
MCM_GETMINREQRECT
MCM_GETMONTHDELTA
MCM_GETMONTHRANGE
MCM_GETRANGE
MCM_GETSELRANGE
MCM_GETTODAY
MCM_GETUNICODEFORMAT
MCM_HITTEST
MCM_SETCOLOR
MCM_SETCURSEL
MCM_SETDAYSTATE
MCM_SETFIRSTDAYOFWEEK
MCM_SETMAXSELCOUNT
MCM_SETMONTHDELTA
MCM_SETRANGE
MCM_SETSELRANGE
MCM_SETTODAY
MCM_SETUNICODEFORMAT

Utility Macros
MonthCal_GetColor
MonthCal_GetCurSel
MonthCal_GetFirstDayOfWeek
MonthCal_GetMaxSelCount
MonthCal_GetMaxTodayWidth
MonthCal_GetMinReqRect
MonthCal_GetMonthDelta
MonthCal_GetMonthRange
MonthCal_GetRange
MonthCal_GetSelRange
MonthCal_GetToday
MonthCal_GetUnicodeFormat
MonthCal_HitTest
MonthCal_SetColor
MonthCal_SetCurSel
MonthCal_SetDayState
MonthCal_SetFirstDayOfWeek
MonthCal_SetMaxSelCount
MonthCal_SetMonthDelta
MonthCal_SetRange
MonthCal_SetSelRange
MonthCal_SetToday
MonthCal_SetUnicodeFormat

Notifications
MCN_GETDAYSTATE
MCN_SELCHANGE
MCN_SELECT
NM_RELEASEDCAPTURE (monthcal)

Structures and Data Types
MCHITTESTINFO
MONTHDAYSTATE
NMDAYSTATE
NMSELCHANGE

Month calendar control styles

Month calendar day numbers

Month Calendar Control Messages

Month Calendar Control Macros

Month Calendar Control Notification Messages

Month Calendar Control Structures

Month Calendar Control Data Types


Month Calendar Control Macros

This section contains information about the macros used with month calendar controls.

MonthCal_GetColor

MonthCal_GetCurSel

MonthCal_GetFirstDayOfWeek

MonthCal_GetMaxSelCount

MonthCal_GetMaxTodayWidth

MonthCal_GetMinReqRect

MonthCal_GetMonthDelta

MonthCal_GetMonthRange

MonthCal_GetRange

MonthCal_GetSelRange

MonthCal_GetToday

MonthCal_GetUnicodeFormat

MonthCal_HitTest

MonthCal_SetColor

MonthCal_SetCurSel

MonthCal_SetDayState

MonthCal_SetFirstDayOfWeek

MonthCal_SetMaxSelCount

MonthCal_SetMonthDelta

MonthCal_SetRange

MonthCal_SetSelRange

MonthCal_SetToday

MonthCal_SetUnicodeFormat


Month Calendar Control Messages

This section contains information about the messages used with month calendar controls.

MCM_GETCOLOR

MCM_GETCURSEL

MCM_GETFIRSTDAYOFWEEK

MCM_GETMAXSELCOUNT

MCM_GETMAXTODAYWIDTH

MCM_GETMINREQRECT

MCM_GETMONTHDELTA

MCM_GETMONTHRANGE

MCM_GETRANGE

MCM_GETSELRANGE

MCM_GETTODAY

MCM_GETUNICODEFORMAT

MCM_HITTEST

MCM_SETCOLOR

MCM_SETCURSEL

MCM_SETDAYSTATE

MCM_SETFIRSTDAYOFWEEK

MCM_SETMAXSELCOUNT

MCM_SETMONTHDELTA

MCM_SETRANGE

MCM_SETSELRANGE

MCM_SETTODAY

MCM_SETUNICODEFORMAT


Month Calendar Control Notification Messages

This section contains information about the notification messages used with month calendar controls.

MCN_GETDAYSTATE

MCN_SELCHANGE

MCN_SELECT

NM_RELEASEDCAPTURE (monthcal)


Month Calendar Control Structures

This section contains information about the structures used with month calendar controls.

MCHITTESTINFO

NMDAYSTATE

NMSELCHANGE


Month Calendar Control Data Types

This section contains information about the data types used with month calendar controls.

MONTHDAYSTATE


Pager Control Reference

This section contains information about the following API elements used with pager controls.

Pager Control Styles

Messages
PGM_FORWARDMOUSE
PGM_GETBKCOLOR
PGM_GETBORDER
PGM_GETBUTTONSIZE
PGM_GETBUTTONSTATE
PGM_GETDROPTARGET
PGM_GETPOS
PGM_RECALCSIZE
PGM_SETBKCOLOR
PGM_SETBORDER
PGM_SETBUTTONSIZE
PGM_SETCHILD
PGM_SETPOS

Utility Macros
Pager_ForwardMouse
Pager_GetBkColor
Pager_GetBorder
Pager_GetButtonSize
Pager_GetButtonState
Pager_GetDropTarget
Pager_GetPos
Pager_RecalcSize
Pager_SetBkColor
Pager_SetBorder
Pager_SetButtonSize
Pager_SetChild
Pager_SetPos

Notifications
NM_RELEASEDCAPTURE (pager)
PGN_CALCSIZE
PGN_SCROLL

Structures
NMPGCALCSIZE
NMPGSCROLL


Progress Bar Control Reference

This section contains information about the following programming elements used with progress bar controls.

Progress Bar Control Styles

Messages
PBM_DELTAPOS
PBM_GETPOS
PBM_GETRANGE
PBM_SETBARCOLOR
PBM_SETBKCOLOR
PBM_SETPOS
PBM_SETRANGE
PBM_SETRANGE32
PBM_SETSTEP
PBM_STEPIT

Structures
PBRANGE


Property Sheet Reference

This section contains information about the following programming elements used with property sheets.

Functions
AddPropSheetPageProc
CreatePropertySheetPage
DestroyPropertySheetPage
PropertySheet
PropSheetPageProc
PropSheetProc

Messages
PSM_ADDPAGE
PSM_APPLY
PSM_CANCELTOCLOSE
PSM_CHANGED
PSM_GETCURRENTPAGEHWND
PSM_GETRESULT
PSM_GETTABCONTROL
PSM_HWNDTOINDEX
PSM_IDTOINDEX
PSM_INDEXTOHWND
PSM_INDEXTOID
PSM_INDEXTOPAGE
PSM_INSERTPAGE
PSM_ISDIALOGMESSAGE
PSM_PAGETOINDEX
PSM_PRESSBUTTON
PSM_QUERYSIBLINGS
PSM_REBOOTSYSTEM
PSM_RECALCPAGESIZES
PSM_REMOVEPAGE
PSM_RESTARTWINDOWS
PSM_SETCURSEL
PSM_SETCURSELID
PSM_SETFINISHTEXT
PSM_SETHEADERSUBTITLE
PSM_SETHEADERTITLE
PSM_SETTITLE
PSM_SETWIZBUTTONS
PSM_UNCHANGED

Utility Macros
PropSheet_AddPage
PropSheet_Apply
PropSheet_CancelToClose
PropSheet_Changed
PropSheet_GetCurrentPageHwnd
PropSheet_GetResult
PropSheet_GetTabControl
PropSheet_HwndToIndex
PropSheet_IdToIndex
PropSheet_IndexToHwnd
PropSheet_IndexToId
PropSheet_IndexToPage
PropSheet_InsertPage
PropSheet_IsDialogMessage
PropSheet_PageToIndex
PropSheet_PressButton
PropSheet_QuerySiblings
PropSheet_RebootSystem
PropSheet_RecalcPageSizes
PropSheet_RemovePage
PropSheet_RestartWindows
PropSheet_SetCurSel
PropSheet_SetCurSelByID
PropSheet_SetFinishText
PropSheet_SetHeaderSubTitle
PropSheet_SetHeaderTitle
PropSheet_SetTitle
PropSheet_SetWizButtons
PropSheet_UnChanged

Notifications
PSN_APPLY
PSN_GETOBJECT
PSN_HELP
PSN_KILLACTIVE
PSN_QUERYCANCEL
PSN_QUERYINITIALFOCUS
PSN_RESET
PSN_SETACTIVE
PSN_TRANSLATEACCELERATOR
PSN_WIZBACK
PSN_WIZFINISH
PSN_WIZNEXT

Structures
PROPSHEETHEADER
PROPSHEETPAGE
PSHNOTIFY


Rebar Control Reference

This section contains information about the following new or updated API elements used with rebar controls.

Rebar Control Styles

Messages
RB_BEGINDRAG
RB_DELETEBAND
RB_DRAGMOVE
RB_ENDDRAG
RB_GETBANDBORDERS
RB_GETBANDCOUNT
RB_GETBANDINFO
RB_GETBARHEIGHT
RB_GETBARINFO
RB_GETBKCOLOR
RB_GETCOLORSCHEME
RB_GETDROPTARGET
RB_GETPALETTE
RB_GETRECT
RB_GETROWCOUNT
RB_GETROWHEIGHT
RB_GETTEXTCOLOR
RB_GETTOOLTIPS
RB_GETUNICODEFORMAT
RB_HITTEST
RB_IDTOINDEX
RB_INSERTBAND
RB_MAXIMIZEBAND
RB_MINIMIZEBAND
RB_MOVEBAND
RB_SETBANDINFO
RB_SETBARINFO
RB_SETBKCOLOR
RB_SETCOLORSCHEME
RB_SETPALETTE
RB_SETPARENT
RB_SETTEXTCOLOR
RB_SETTOOLTIPS
RB_SETUNICODEFORMAT
RB_SHOWBAND
RB_SIZETORECT

Notifications
NM_CUSTOMDRAW (rebar)
NM_NCHITTEST (rebar)
NM_RELEASEDCAPTURE (rebar)
RBN_AUTOSIZE
RBN_BEGINDRAG
RBN_CHEVRONPUSHED
RBN_CHILDSIZE
RBN_DELETEDBAND
RBN_DELETINGBAND
RBN_ENDDRAG
RBN_GETOBJECT
RBN_HEIGHTCHANGE
RBN_LAYOUTCHANGED
RBN_MINMAX

Structures
NMRBAUTOSIZE
NMREBAR
NMREBARCHEVRON
NMREBARCHILDSIZE
RBHITTESTINFO
REBARBANDINFO
REBARINFO


Status Bar Reference

This section contains information about the programming elements used with status bar controls.

Status Bar Styles

Functions
CreateStatusWindow
DrawStatusText
MenuHelp

Messages
SB_GETBORDERS
SB_GETICON
SB_GETPARTS
SB_GETRECT
SB_GETTEXT
SB_GETTEXTLENGTH
SB_GETTIPTEXT
SB_GETUNICODEFORMAT
SB_ISSIMPLE
SB_SETBKCOLOR
SB_SETICON
SB_SETMINHEIGHT
SB_SETPARTS
SB_SETTEXT
SB_SETTIPTEXT
SB_SETUNICODEFORMAT
SB_SIMPLE

Notifications
NM_CLICK (status bar)
NM_DBLCLK (status bar)
NM_RCLICK (status bar)
NM_RDBLCLK (status bar)
SBN_SIMPLEMODECHANGE


LM_GETIDEALHEIGHT Message

This is preliminary documentation and is subject to change.

Retrieves the preferred height of a link for the control's current width.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns int in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LM_GETIDEALHEIGHT,
  |     // message ID

   (WPARAM) wParam,
  |     // = 0; not used, must be zero
   (LPARAM) lParam
  |     // = 0; not used, must be zero

);

Parameters

wParam
[in] Must be zero.
lParam
[in] Must be zero.

Return Value

Integer representing the preferred height of the link text, in pixels.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LM_GETITEM Message

This is preliminary documentation and is subject to change.

Retrieves the states and attributes of an item.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LM_GETITEM,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) () wParam;
   (LPARAM) lParam
  |     // = (LPARAM) (PLITEM) lParam;

);

Parameters

wParam
Must be NULL.
lParam
[in, out] Pointer to a LITEM structure to be filled with information about the item.

Return Value

Returns TRUE if the message succeeds in getting the values and attributes specified.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LM_HITTEST Message

This is preliminary documentation and is subject to change.

Determines if the user clicked the specified link.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LM_HITTEST,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) () wParam;
   (LPARAM) lParam
  |     // = (LPARAM) (PLHITTESTINFO) lParam;

);

Parameters

wParam
Must be NULL.
lParam
[in, out] Pointer to a LHITTESTINFO structure to be filled with information about the link the user clicked, if any.

Return Value

Returns TRUE if user clicked on a link, otherwise returns FALSE.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LM_SETITEM Message

This is preliminary documentation and is subject to change.

Sets the states and attributes of an item.

To send this message, call the SendMessage function as follows.

lResult = SendMessage(
  |     // returns BOOL in lResult

   (HWND) hWndControl,
  |     // handle to destination control

   (UINT) LM_SETITEM,
  |     // message ID

   (WPARAM) wParam,
  |     // = (WPARAM) () wParam;
   (LPARAM) lParam
  |     // = (LPARAM) (PLITEM) lParam;

);

Parameters

wParam
Must be NULL.
lParam
[in] Pointer to a LITEM structure containing the new states and attributes desired for the link.

Return Value

Returns TRUE if the message succeeds in setting the values and attributes specified.

Message Requirements

Header | commctrl.h
Minimum operating systems | Whistler


LHITTESTINFO Structure

This is preliminary documentation and is subject to change.

Used to retrieve information about a link that a user clicked.

Syntax

typedef struct LHITTESTINFO {
    POINT pt;
    LITEM item;
} LHITTESTINFO, *PLHITTESTINFO;

Members

pt
POINT Online link structure that receives the coordinates of the link that was clicked.
item
LITEM structure that receives information about the link that was clicked.

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


LITEM Structure

This is preliminary documentation and is subject to change.

Used to set and retrieve information about a link item.

Syntax

typedef struct LITEM {
    UINT mask;
    int iLink;
    UINT state;
    UINT stateMask;
    CHAR szID;
    CHAR szUrl;
} LITEM, *PLITEM;

Members

mask
Combination of one or more of the following flags, describing the information to set or retrieve.
LIF_ITEMINDEX
Retrieve the item index for the ID value supplied in szID. Setting this flag in combination with LIF_ITEMID results in unpredictable behavior.
LIF_STATE
Use stateMask to get or set the state of the link.
LIF_ITEMID
Specify the item by the ID value given in szID.
LIF_URL
Set or get the URL for this item.
iLink
integer that contains the item index.
state
Combination of one or more of the following flags, describing the state of the item.
LIS_ENABLED
The link is able to respond to user input. This is the default unless the entire control was created with WS_DISABLED. In this case, all links are disabled.
LIS_FOCUSED
The link has the keyboard focus. Pressing ENTER sends a NM_CLICK notification.
LIS_VISITED
The link has been visited by the user. Changing the URL to one that has not been visited causes this flag to be cleared.
LIS_SHELLEXECURL
The URL is passed to the shell when the user either clicks the link or presses ENTER when the link has the focus.
stateMask
Combination of flags describing which state item to get or set. Allowable items are identical to those allowed in state.
szID
String that contains the ID name. The dimension of the array is [MAX_LINKID_TEXT].
szUrl
String containing the URL represented by the link. The dimension of the array is [L_MAX_URL_LENGTH].

Structure Information

Header | Commctrl.h
Minimum operating systems | Whistler


Tab Control Reference

This section contains information about the programming elements used with tab controls.

Tab Control Styles

Tab Control Extended Styles

Tab Control Item States

Messages
TCM_ADJUSTRECT
TCM_DELETEALLITEMS
TCM_DELETEITEM
TCM_DESELECTALL
TCM_GETCURFOCUS
TCM_GETCURSEL
TCM_GETEXTENDEDSTYLE
TCM_GETIMAGELIST
TCM_GETITEM
TCM_GETITEMCOUNT
TCM_GETITEMRECT
TCM_GETROWCOUNT
TCM_GETTOOLTIPS
TCM_GETUNICODEFORMAT
TCM_HIGHLIGHTITEM
TCM_HITTEST
TCM_INSERTITEM
TCM_REMOVEIMAGE
TCM_SETCURFOCUS
TCM_SETCURSEL
TCM_SETEXTENDEDSTYLE
TCM_SETIMAGELIST
TCM_SETITEM
TCM_SETITEMEXTRA
TCM_SETITEMSIZE
TCM_SETMINTABWIDTH
TCM_SETPADDING
TCM_SETTOOLTIPS
TCM_SETUNICODEFORMAT

Utility Macros
TabCtrl_AdjustRect
TabCtrl_DeleteAllItems
TabCtrl_DeleteItem
TabCtrl_DeselectAll
TabCtrl_GetCurFocus
TabCtrl_GetCurSel
TabCtrl_GetExtendedStyle
TabCtrl_GetImageList
TabCtrl_GetItem
TabCtrl_GetItemCount
TabCtrl_GetItemRect
TabCtrl_GetRowCount
TabCtrl_GetToolTips
TabCtrl_GetUnicodeFormat
TabCtrl_HighlightItem
TabCtrl_HitTest
TabCtrl_InsertItem
TabCtrl_RemoveImage
TabCtrl_SetCurFocus
TabCtrl_SetCurSel
TabCtrl_SetExtendedStyle
TabCtrl_SetImageList
TabCtrl_SetItem
TabCtrl_SetItemExtra
TabCtrl_SetItemSize
TabCtrl_SetMinTabWidth
TabCtrl_SetPadding
TabCtrl_SetToolTips
TabCtrl_SetUnicodeFormat

Notifications
NM_CLICK (tab)
NM_RCLICK (tab)
NM_RELEASEDCAPTURE (tab)
TCN_GETOBJECT
TCN_KEYDOWN
TCN_SELCHANGE
TCN_SELCHANGING

Structures
NMTCKEYDOWN
TC_HITTESTINFO
TC_ITEMHEADER
TC_KEYDOWN
TCHITTESTINFO
TCITEM
TCITEMHEADER


Toolbar Control Messages

This section contains information about the messages used with toolbar controls.

TB_ADDBITMAP

TB_ADDBUTTONS

TB_ADDSTRING

TB_AUTOSIZE

TB_BUTTONCOUNT

TB_BUTTONSTRUCTSIZE

TB_CHANGEBITMAP

TB_CHECKBUTTON

TB_COMMANDTOINDEX

TB_CUSTOMIZE

TB_DELETEBUTTON

TB_ENABLEBUTTON

TB_GETANCHORHIGHLIGHT

TB_GETBITMAP

TB_GETBITMAPFLAGS

TB_GETBUTTON

TB_GETBUTTONINFO

TB_GETBUTTONSIZE

TB_GETBUTTONTEXT

TB_GETCOLORSCHEME

TB_GETDISABLEDIMAGELIST

TB_GETEXTENDEDSTYLE

TB_GETHOTIMAGELIST

TB_GETHOTITEM

TB_GETIMAGELIST

TB_GETINSERTMARK

TB_GETINSERTMARKCOLOR

TB_GETITEMRECT

TB_GETMAXSIZE

TB_GETOBJECT

TB_GETPADDING

TB_GETRECT

TB_GETROWS

TB_GETSTATE

TB_GETSTYLE

TB_GETTEXTROWS

TB_GETTOOLTIPS

TB_GETUNICODEFORMAT

TB_HIDEBUTTON

TB_HITTEST

TB_INDETERMINATE

TB_INSERTBUTTON

TB_INSERTMARKHITTEST

TB_ISBUTTONCHECKED

TB_ISBUTTONENABLED

TB_ISBUTTONHIDDEN

TB_ISBUTTONHIGHLIGHTED

TB_ISBUTTONINDETERMINATE

TB_ISBUTTONPRESSED

TB_LOADIMAGES

TB_MAPACCELERATOR

TB_MARKBUTTON

TB_MOVEBUTTON

TB_PRESSBUTTON

TB_REPLACEBITMAP

TB_SAVERESTORE

TB_SETANCHORHIGHLIGHT

TB_SETBITMAPSIZE

TB_SETBUTTONINFO

TB_SETBUTTONSIZE

TB_SETBUTTONWIDTH

TB_SETCMDID

TB_SETCOLORSCHEME

TB_SETDISABLEDIMAGELIST

TB_SETDRAWTEXTFLAGS

TB_SETEXTENDEDSTYLE

TB_SETHOTIMAGELIST

TB_SETHOTITEM

TB_SETIMAGELIST

TB_SETINDENT

TB_SETINSERTMARK

TB_SETINSERTMARKCOLOR

TB_SETMAXTEXTROWS

TB_SETPADDING

TB_SETPARENT

TB_SETROWS

TB_SETSTATE

TB_SETSTYLE

TB_SETTOOLTIPS

TB_SETUNICODEFORMAT


Toolbar Control Reference

This section contains information about the following new or updated API elements used with toolbar controls.

Toolbar Control and Button Styles

Toolbar Extended Styles

Toolbar Button States

Toolbar Standard Button Image Index Values

Toolbar Control Functions

Toolbar Control Messages

Toolbar Control Notification Messages

Toolbar Control Structures

Functions
CreateMappedBitmap
CreateToolbarEx

Messages
TB_ADDBITMAP
TB_ADDBUTTONS
TB_ADDSTRING
TB_AUTOSIZE
TB_BUTTONCOUNT
TB_BUTTONSTRUCTSIZE
TB_CHANGEBITMAP
TB_CHECKBUTTON
TB_COMMANDTOINDEX
TB_CUSTOMIZE
TB_DELETEBUTTON
TB_ENABLEBUTTON
TB_GETANCHORHIGHLIGHT
TB_GETBITMAP
TB_GETBITMAPFLAGS
TB_GETBUTTON
TB_GETBUTTONINFO
TB_GETBUTTONSIZE
TB_GETBUTTONTEXT
TB_GETCOLORSCHEME
TB_GETDISABLEDIMAGELIST
TB_GETEXTENDEDSTYLE
TB_GETHOTIMAGELIST
TB_GETHOTITEM
TB_GETIMAGELIST
TB_GETINSERTMARK
TB_GETINSERTMARKCOLOR
TB_GETITEMRECT
TB_GETMAXSIZE
TB_GETOBJECT
TB_GETPADDING
TB_GETRECT
TB_GETROWS
TB_GETSTATE
TB_GETSTRING
TB_GETSTYLE
TB_GETTEXTROWS
TB_GETTOOLTIPS
TB_GETUNICODEFORMAT
TB_HIDEBUTTON
TB_HITTEST
TB_INDETERMINATE
TB_INSERTBUTTON
TB_INSERTMARKHITTEST
TB_ISBUTTONCHECKED
TB_ISBUTTONENABLED
TB_ISBUTTONHIDDEN
TB_ISBUTTONHIGHLIGHTED
TB_ISBUTTONINDETERMINATE
TB_ISBUTTONPRESSED
TB_LOADIMAGES
TB_MAPACCELERATOR
TB_MARKBUTTON
TB_MOVEBUTTON
TB_PRESSBUTTON
TB_REPLACEBITMAP
TB_SAVERESTORE
TB_SETANCHORHIGHLIGHT
TB_SETBITMAPSIZE
TB_SETBUTTONINFO
TB_SETBUTTONSIZE
TB_SETBUTTONWIDTH
TB_SETCMDID
TB_SETCOLORSCHEME
TB_SETDISABLEDIMAGELIST
TB_SETDRAWTEXTFLAGS
TB_SETEXTENDEDSTYLE
TB_SETHOTIMAGELIST
TB_SETHOTITEM
TB_SETIMAGELIST
TB_SETINDENT
TB_SETINSERTMARK
TB_SETINSERTMARKCOLOR
TB_SETMAXTEXTROWS
TB_SETPADDING
TB_SETPARENT
TB_SETROWS
TB_SETSTATE
TB_SETSTYLE
TB_SETTOOLTIPS
TB_SETUNICODEFORMAT

Notifications
NM_CHAR (toolbar)
NM_CUSTOMDRAW (toolbar)
NM_KEYDOWN (toolbar)
NM_RCLICK (toolbar)
NM_RDBLCLK (toolbar)
NM_RELEASEDCAPTURE (toolbar)
NM_TOOLTIPSCREATED (toolbar)
TBN_BEGINADJUST
TBN_BEGINDRAG
TBN_CUSTHELP
TBN_DELETINGBUTTON
TBN_DRAGOUT
TBN_DROPDOWN
TBN_ENDADJUST
TBN_ENDDRAG
TBN_GETBUTTONINFO
TBN_GETDISPINFO
TBN_GETINFOTIP
TBN_GETOBJECT
TBN_HOTITEMCHANGE
TBN_INITCUSTOMIZE
TBN_QUERYDELETE
TBN_QUERYINSERT
TBN_RESET
TBN_RESTORE
TBN_SAVE
TBN_TOOLBARCHANGE

Structures
COLORMAP
NMTBCUSTOMDRAW
NMTBDISPINFO
NMTBGETINFOTIP
NMTBHOTITEM
NMTBSAVE
NMTBRESTORE
NMTOOLBAR
TBADDBITMAP
TBBUTTON
TBBUTTONINFO
TBINSERTMARK
TBNOTIFY
TBREPLACEBITMAP
TBSAVEPARAMS


Toolbar Control Functions

This section contains information about the functions used with toolbar controls.

CreateMappedBitmap

CreateToolbarEx


Toolbar Control Notification Messages

This section contains information about the notification messages sent by toolbar controls.

NM_CHAR (toolbar)

NM_CUSTOMDRAW (toolbar)

NM_KEYDOWN (toolbar)

NM_RCLICK (toolbar)

NM_RDBLCLK (toolbar)

NM_RELEASEDCAPTURE (toolbar)

NM_TOOLTIPSCREATED (toolbar)

TBN_BEGINADJUST

TBN_BEGINDRAG

TBN_CUSTHELP

TBN_DELETINGBUTTON

TBN_DRAGOUT

TBN_DROPDOWN

TBN_ENDADJUST

TBN_ENDDRAG

TBN_GETBUTTONINFO

TBN_GETDISPINFO

TBN_GETINFOTIP

TBN_GETOBJECT

TBN_HOTITEMCHANGE

TBN_QUERYDELETE

TBN_QUERYINSERT

TBN_RESET

TBN_TOOLBARCHANGE


Toolbar Control Structures

This section contains information about the structures used with toolbar controls.

COLORMAP

NMTBCUSTOMDRAW

NMTBDISPINFO

NMTBGETINFOTIP

NMTBHOTITEM

NMTOOLBAR

TBADDBITMAP

TBBUTTON

TBBUTTONINFO

TBINSERTMARK

TBREPLACEBITMAP

TBSAVEPARAMS


ToolTip Control Reference

This section contains information about the following programming elements used with ToolTip controls.

ToolTip Styles

Messages
TTM_ACTIVATE
TTM_ADDTOOL
TTM_ADJUSTRECT
TTM_DELTOOL
TTM_ENUMTOOLS
TTM_GETBUBBLESIZE
TTM_GETCURRENTTOOL
TTM_GETDELAYTIME
TTM_GETMARGIN
TTM_GETMAXTIPWIDTH
TTM_GETTEXT
TTM_GETTIPBKCOLOR
TTM_GETTIPTEXTCOLOR
TTM_GETTOOLCOUNT
TTM_GETTOOLINFO
TTM_HITTEST
TTM_NEWTOOLRECT
TTM_POP
TTM_RELAYEVENT
TTM_SETDELAYTIME
TTM_SETMARGIN
TTM_SETMAXTIPWIDTH
TTM_SETTIPBKCOLOR
TTM_SETTIPTEXTCOLOR
TTM_SETTITLE
TTM_SETTOOLINFO
TTM_TRACKACTIVATE
TTM_TRACKPOSITION
TTM_UPDATE
TTM_UPDATETIPTEXT
TTM_WINDOWFROMPOINT

Notifications
NM_CUSTOMDRAW (ToolTip)
TTN_GETDISPINFO
TTN_NEEDTEXT
TTN_POP
TTN_SHOW

Structures
NMTTCUSTOMDRAW
NMTTDISPINFO
TOOLINFO
TOOLTIPTEXT
TTHITTESTINFO


Trackbar Control Reference

This section contains information about the following programming elements used with trackbar controls.

Trackbar Control Styles

Messages
TBM_CLEARSEL
TBM_CLEARTICS
TBM_GETBUDDY
TBM_GETCHANNELRECT
TBM_GETLINESIZE
TBM_GETNUMTICS
TBM_GETPAGESIZE
TBM_GETPOS
TBM_GETPTICS
TBM_GETRANGEMAX
TBM_GETRANGEMIN
TBM_GETSELEND
TBM_GETSELSTART
TBM_GETTHUMBLENGTH
TBM_GETTHUMBRECT
TBM_GETTIC
TBM_GETTICPOS
TBM_GETTOOLTIPS
TBM_GETUNICODEFORMAT
TBM_SETBUDDY
TBM_SETLINESIZE
TBM_SETPAGESIZE
TBM_SETPOS
TBM_SETRANGE
TBM_SETRANGEMAX
TBM_SETRANGEMIN
TBM_SETSEL
TBM_SETSELEND
TBM_SETSELSTART
TBM_SETTHUMBLENGTH
TBM_SETTIC
TBM_SETTICFREQ
TBM_SETTIPSIDE
TBM_SETTOOLTIPS
TBM_SETUNICODEFORMAT

Notifications
NM_CUSTOMDRAW (trackbar)
NM_RELEASEDCAPTURE (trackbar)


Tree-View Control Reference

This section contains information about the following new or updated API elements used with tree-view controls.

Tree-View Control Window Styles

Tree-View Control Item States

Messages
TVM_CREATEDRAGIMAGE
TVM_DELETEITEM
TVM_EDITLABEL
TVM_ENDEDITLABELNOW
TVM_ENSUREVISIBLE
TVM_EXPAND
TVM_GETBKCOLOR
TVM_GETCOUNT
TVM_GETEDITCONTROL
TVM_GETIMAGELIST
TVM_GETINDENT
TVM_GETINSERTMARKCOLOR
TVM_GETISEARCHSTRING
TVM_GETITEM
TVM_GETITEMHEIGHT
TVM_GETITEMRECT
TVM_GETITEMSTATE
TVM_GETLINECOLOR
TVM_GETNEXTITEM
TVM_GETSCROLLTIME
TVM_GETTEXTCOLOR
TVM_GETTOOLTIPS
TVM_GETUNICODEFORMAT
TVM_GETVISIBLECOUNT
TVM_HITTEST
TVM_INSERTITEM
TVM_SELECTITEM
TVM_SETBKCOLOR
TVM_SETIMAGELIST
TVM_SETINDENT
TVM_SETINSERTMARK
TVM_SETINSERTMARKCOLOR
TVM_SETITEM
TVM_SETITEMHEIGHT
TVM_SETLINECOLOR
TVM_SETSCROLLTIME
TVM_SETTEXTCOLOR
TVM_SETTOOLTIPS
TVM_SETUNICODEFORMAT
TVM_SORTCHILDREN
TVM_SORTCHILDRENCB

Utility Macros
TreeView_CreateDragImage
TreeView_DeleteAllItems
TreeView_DeleteItem
TreeView_EditLabel
TreeView_EndEditLabelNow
TreeView_EnsureVisible
TreeView_Expand
TreeView_GetBkColor
TreeView_GetCheckState
TreeView_GetChild
TreeView_GetCount
TreeView_GetDropHilight
TreeView_GetEditControl
TreeView_GetFirstVisible
TreeView_GetImageList
TreeView_GetIndent
TreeView_GetInsertMarkColor
TreeView_GetISearchString
TreeView_GetItem
TreeView_GetItemHeight
TreeView_GetItemRect
TreeView_GetItemState
TreeView_GetLastVisible
TreeView_GetNextItem
TreeView_GetNextSibling
TreeView_GetNextVisible
TreeView_GetParent
TreeView_GetPrevSibling
TreeView_GetPrevVisible
TreeView_GetRoot
TreeView_GetScrollTime
TreeView_GetSelection
TreeView_GetTextColor
TreeView_GetToolTips
TreeView_GetUnicodeFormat
TreeView_GetVisibleCount
TreeView_HitTest
TreeView_InsertItem
TreeView_Select
TreeView_SelectDropTarget
TreeView_SelectItem
TreeView_SelectSetFirstVisible
TreeView_SetBkColor
TreeView_SetCheckState
TreeView_SetImageList
TreeView_SetIndent
TreeView_SetInsertMark
TreeView_SetInsertMarkColor
TreeView_SetItem
TreeView_SetItemHeight
TreeView_SetItemState
TreeView_SetScrollTime
TreeView_SetTextColor
TreeView_SetToolTips
TreeView_SetUnicodeFormat
TreeView_SortChildren
TreeView_SortChildrenCB

Notifications
NM_CLICK (tree view)
NM_CUSTOMDRAW (tree view)
NM_DBLCLK (tree view)
NM_KILLFOCUS (tree view)
NM_RCLICK (tree view)
NM_RETURN (tree view)
NM_SETCURSOR (tree view)
NM_SETFOCUS (tree view)
TVN_BEGINDRAG
TVN_BEGINLABELEDIT
TVN_BEGINRDRAG
TVN_DELETEITEM
TVN_ENDLABELEDIT
TVN_GETDISPINFO
TVN_GETINFOTIP
TVN_ITEMEXPANDED
TVN_ITEMEXPANDING
TVN_KEYDOWN
TVN_SELCHANGED
TVN_SELCHANGING
TVN_SETDISPINFO
TVN_SINGLEEXPAND

Structures
NMTREEVIEW
NMTVCUSTOMDRAW
NMTVDISPINFO
NMTVGETINFOTIP
NMTVKEYDOWN
TV_DISPINFO
TV_HITTESTINFO
TV_INSERTSTRUCT
TV_ITEM
TV_KEYDOWN
TV_SORTCB
TVHITTESTINFO
TVINSERTSTRUCT
TVITEM
TVITEMEX
TVSORTCB


Up-Down Control Reference

This section contains information about the following programming elements used with up-down controls.

Up-Down Control Styles

Functions
CreateUpDownControl

Messages
UDM_GETACCEL
UDM_GETBASE
UDM_GETBUDDY
UDM_GETPOS
UDM_GETPOS32
UDM_GETRANGE
UDM_GETRANGE32
UDM_GETUNICODEFORMAT
UDM_SETACCEL
UDM_SETBASE
UDM_SETBUDDY
UDM_SETPOS
UDM_SETPOS32
UDM_SETRANGE
UDM_SETRANGE32
UDM_SETUNICODEFORMAT

Notifications
NM_RELEASEDCAPTURE (up-down)
UDN_DELTAPOS

Structures
NM_UPDOWN
NMUPDOWN
UDACCEL


Format Values

This is preliminary documentation and is subject to change.

This section lists the values that are used with the dwTextFlags parameter of the DrawThemeText function. One or more of these values are used to specify how a text string should be formatted. The text string is drawn inside a display rectangle. The dimensions of the display rectangle are specified by the pRect parameter of the function.

Format Values

The following table lists the format values.

Value | Description
DT_BOTTOM | Renders the text string at the bottom of the display rectangle. This value is used only with the DT_SINGLELINE value.
DT_CALCRECT | Determines the width and height of the display rectangle.
DT_CENTER | Centers text horizontally in the display rectangle.
DT_EDITCONTROL | Duplicates the text-displaying characteristics of a multiline edit control. Specifically, the average character width is calculated in the same manner as for an edit control, and the function does not display a partially visible last line.
DT_END_ELLIPSIS | Truncates a text string that is wider than the display rectangle and adds an ellipsis to indicate the truncation. The string is not modified unless the DT_MODIFYSTRING flag is specified.
DT_EXPANDTABS | Expands tab characters. The default number of characters per tab is eight. The DT_WORD_ELLIPSIS, DT_PATH_ELLIPSIS, and DT_END_ELLIPSIS values cannot be used with the DT_EXPANDTABS value.
DT_EXTERNALLEADING | Includes the external leading of a font in the line height. Normally, external leading is not included in the height of a line of text.
DT_HIDEPREFIX | Ignores the prefix character & in the text. The letter that follows is not underlined, but other prefix characters are still processed. For example: input string: "A&bc&&d" normal: "Abc&d" DT_HIDEPREFIX: "Abc&d"
DT_LEFT | Aligns text to the left.
DT_MODIFYSTRING | Modifies a string to match the displayed text. This value has no effect unless DT_END_ELLIPSIS or DT_PATH_ELLIPSIS is specified.
DT_NOCLIP | Draws the text string without clipping the display rectangle.
DT_NOFULLWIDTHCHARBREAK | Prevents a line break at a double-byte character set (DBCS), so that the line-breaking rule is equivalent to single-byte character set (SBCS). This can be used, for example, to make icon labels written in Korean text more readable. This value has no effect unless DT_WORDBREAK is specified.
DT_NOPREFIX | Turns off processing of prefix characters. Normally, DrawThemeText interprets the prefix character & as a directive to underscore the character that follows, and the prefix characters && as a directive to print a single &. By specifying DT_NOPREFIX, this processing is turned off. For example: input string: "A&bc&&d" normal: "Abc&d" DT_NOPREFIX: "A&bc&&d"
DT_PATH_ELLIPSIS | Replaces characters in the middle of text with an ellipsis so that the result fits in the display rectangle. If the string contains backslash (\) characters, DT_PATH_ELLIPSIS preserves as much as possible of the text after the last backslash. The string is not modified unless the DT_MODIFYSTRING flag is specified.
DT_PREFIXONLY | Draws only an underline at the position of the character following the prefix character &. Normally DrawThemeText interprets the & as a directive to underline the character that follows and the prefix characters && as a directive to print a single &. By specifying DT_PREFIXONLY, no characters are drawn, only an underline. White spaces are placed in the positions where characters would normally appear. For example: input string: "A&bc&&d" normal: "Abc&d" DT_PREFIXONLY: " _ "
DT_RIGHT | Aligns text to the right.
DT_RTLREADING | Lays out text in right-to-left order for bidirectional text, for example, text in a Hebrew or Arabic font. The default direction for text is left-to-right.
DT_SINGLELINE | Displays text on a single line. Carriage returns and line feeds do not break the line.
DT_TABSTOP | Sets tab stops.
DT_TOP | Renders the text at the top of the display rectangle.
DT_VCENTER | Centers text vertically. This value is used only with the DT_SINGLELINE value.
DT_WORDBREAK | Breaks lines between words if a word would extend past the edge of the display rectangle. A carriage return/line feed (CR/LF) sequence also breaks the line.
DT_WORD_ELLIPSIS | Truncates any word that does not fit in the display rectangle and adds an ellipsis.


Hit Test Options

This is preliminary documentation and is subject to change.

This section lists the option values that are used with the dwOptions parameter of the HitTestThemeBackground function. For a list of the values returned when you specify one of these options, see Hit Test Return Values.

Option Values

The following table lists the hit test options.

Option | Value | Description
HTTB_BACKGROUNDSEG | 0x0000 | Theme background segment hit test option.
HTTB_FIXEDBORDER | 0x0002 | Fixed border hit test option.
HTTB_CAPTION | 0x0004 | Caption hit test option.
HTTB_RESIZINGBORDER | (HTTB_RESIZINGBORDER_LEFT | HTTB_RESIZINGBORDER_TOP | HTTB_RESIZINGBORDER_RIGHT | HTTB_RESIZINGBORDER_BOTTOM) | Resizing border hit test options.
HTTB_RESIZINGBORDER_LEFT | 0x0010 | Resizing left border hit test option.
HTTB_RESIZINGBORDER_TOP | 0x0020 | Resizing top border hit test option.
HTTB_RESIZINGBORDER_RIGHT | 0x0040 | Resizing right border hit test option.
HTTB_RESIZINGBORDER_BOTTOM | 0x0080 | Resizing bottom border hit test option.


Hit Test Return Values

This is preliminary documentation and is subject to change.

This section lists the hit test code values that are returned in the pwHitTestCode parameter of the HitTestThemeBackground function. The code values returned depend on the hit test options specified in the dwOptions parameter of the HitTestThemeBackground function. For a list of the options, see Hit Test Options.

Return Values

The following table lists the hit test options and the corresponding return codes.

Option | Return codes | Description
HTTB_BACKGROUNDSEG | HTBOTTOM | Hit test succeeded in the bottom border segment.
 | HTBOTTOMLEFT | Hit test succeeded in the bottom and left border intersection.
 | HTBOTTOMRIGHT | Hit test succeeded in the bottom and right border intersection.
 | HTCLIENT | Hit test succeeded in the middle background segment.
 | HTLEFT | Hit test succeeded in the left border segment.
 | HTNOWHERE | Hit test succeeded outside the control or on a transparent area.
 | HTRIGHT | Hit test succeeded in the right border segment.
 | HTTOP | Hit test succeeded in the top border segment.
 | HTTOPLEFT | Hit test succeeded in top and left border intersection.
 | HTTOPRIGHT | Hit test succeeded in the top and right border intersection.
HTTB_CAPTION | HTCAPTION | Hit test succeeded in the top, top left, or top right background segments.
 | HTNOWHERE | Hit test succeeded outside the control or on a transparent area.
HTTB_FIXEDBORDER | HTBORDER | Hit test succeeded in any background segment except the middle background segment.
 | HTCLIENT | Hit test succeeded in the middle background segment.
HTTB_RESIZINGBORDER | HTBORDER | Hit test failed in the middle background segment and resizing zones, but succeeded in a background border segment.
HTTB_RESIZINGBORDER_BOTTOM | HTBOTTOM | Hit test succeeded in the bottom border segment.
HTTB_RESIZINGBORDER_LEFT | HTLEFT | Hit test succeeded in the left border segment.
HTTB_RESIZINGBORDER_RIGHT | HTRIGHT | Hit test succeeded in the right border segment.
HTTB_RESIZINGBORDER_TOP | HTTOP | Hit test succeeded in the top border segment.


Shell and Common Controls Versions

This section describes how to determine which version of the Shell or common controls dynamic-link libraries (DLLs) your application is running on and how to target your application for a specific version.

  • DLL Version Numbers
  • Using DllGetVersion to Determine the Version Number
  • Project Versions
  • Downloading the Latest Version

DLL Version Numbers

All but a handful of the programming elements discussed in the Shell and common controls documentation are contained in three DLLs: Comctl32.dll, Shell32.dll, and Shlwapi.dll. Because of ongoing enhancements, different versions of these DLLs implement different features. Throughout this document, programming elements are marked with a version number. This version number indicates that the programming element was first implemented in that version and will also be found in all subsequent versions of the DLL. If no version number is specified, the programming element is implemented in all versions. The following table outlines the different DLL versions and how they were distributed.

Version | DLL | Distribution Platform
4.00 | All | Microsoft® Windows® 95/Windows NT® 4.0.
4.70 | All | Microsoft® Internet Explorer 3.x.
4.71 | All | Microsoft® Internet Explorer 4.0. See note 2.
4.72 | All | Microsoft® Internet Explorer 4.01 and Windows® 98. See note 2.
5.00 | Shlwapi.dll | Microsoft® Internet Explorer 5. See note 3.
5.00 | Shell32.dll | Microsoft® Windows® 2000 and Windows Me. See note 3.
5.80 | Comctl32.dll | Microsoft® Internet Explorer 5. See note 3.
5.81 | Comctl32.dll | Microsoft® Windows 2000 and Windows Me. See note 3.

Note 1: The 4.00 versions of Shell32.dll and Comctl32.dll are found on the original versions of Windows 95 and Windows NT 4. New versions of Commctl.dll were shipped with all Internet Explorer releases. Shlwapi.dll first shipped with Internet Explorer 4.0, so its first version number is 4.71. The Shell was not updated with the Internet Explorer 3.0 release, so Shell32.dll does not have a version 4.70. While Shell32.dll versions 4.71 and 4.72 were shipped with the corresponding Internet Explorer releases, they were not necessarily installed (see note 2). For subsequent releases, the version numbers for the three DLLs are not identical. In general, you should assume that all three DLLs may have different version numbers, and test each one separately.

Note 2: All systems with Internet Explorer 4.0 or 4.01 will have the associated version of Comctl32.dll and Shlwapi.dll (4.71 or 4.72, respectively). However, for systems prior to Windows 98, Internet Explorer 4.0 and 4.01 can be installed with or without the integrated Shell. If they are installed with the integrated Shell, the associated version of Shell32.dll will be installed. If they are installed without the integrated Shell, Shell32.dll is not updated. In other words, the presence of version 4.71 or 4.72 of Comctl32.dll or Shlwapi.dll on a system does not guarantee that Shell32.dll has the same version number. All Windows 98 systems have version 4.72 of Shell32.dll.

Note 3:Version 5.80 of Comctl32.dll and version 5.0 of Shlwapi.dll are distributed with Internet Explorer 5. They will be found on all systems on which Internet Explorer 5 is installed, except Windows 2000. Internet Explorer 5 does not update the Shell, so version 5.0 of Shell32.dll will not be found on Windows NT, Windows 95, or Windows 98 systems. Version 5.0 of Shell32.dll will be distributed with Windows 2000 and Windows Me, along with version 5.0 of Shlwapi.dll, and version 5.81 of Comctl32.dll.

Using DllGetVersion to Determine the Version Number

Starting with version 4.71, the Shell and common controls DLLs, among others, began exporting DllGetVersion. This function can be called by an application to determine which DLL version is present on the system. It returns a structure that contains version information.

Note: DLLs do not necessarily export DllGetVersion. Always test for it before attempting to use it.

For systems earlier than Windows 2000, DllGetVersion returns a DLLVERSIONINFO structure that contains the major and minor version numbers, the build number, and a platform identifier (ID). For Windows 2000 and later systems, DllGetVersion might instead return a DLLVERSIONINFO2 structure. This structure contains the QFE number that identifies the service pack and provides a more robust way to compare version numbers than DLLVERSIONINFO. Because the first member of DLLVERSIONINFO2 is a DLLVERSIONINFO structure, the new structure is backward-compatible.

Using DllGetVersion

The following sample function loads a specified DLL and attempts to call its DllGetVersion function. If successful, it uses a macro to pack the major and minor version numbers from the DLLVERSIONINFO structure into a DWORD that is returned to the calling application. If the DLL does not export DllGetVersion, the function returns zero. With Windows 2000 and later systems, you can modify the function to handle the possibility that DllGetVersion returns a DLLVERSIONINFO2 structure. If so, use the information in the ullVersion member to compare versions, build numbers, and service pack releases. The MAKEDLLVERULL macro simplifies the task of comparing these values to those in ullVersion.

#define PACKVERSION(major,minor) MAKELONG(minor,major)

DWORD GetDllVersion(LPCTSTR lpszDllName)
{

    HINSTANCE hinstDll;
    DWORD dwVersion = 0;

    hinstDll = LoadLibrary(lpszDllName);

    if(hinstDll)
    {
        DLLGETVERSIONPROC pDllGetVersion;

        pDllGetVersion = (DLLGETVERSIONPROC) GetProcAddress(hinstDll, "DllGetVersion");

/*Because some DLLs might not implement this function, you
  must test for it explicitly. Depending on the particular
  DLL, the lack of a DllGetVersion function can be a useful
  indicator of the version.
*/
        if(pDllGetVersion)
        {
            DLLVERSIONINFO dvi;
            HRESULT hr;

            ZeroMemory(&dvi, sizeof(dvi));
            dvi.cbSize = sizeof(dvi);

            hr = (*pDllGetVersion)(&dvi);

            if(SUCCEEDED(hr))
            {
                dwVersion = PACKVERSION(dvi.dwMajorVersion, dvi.dwMinorVersion);
            }
        }

        FreeLibrary(hinstDll);
    }
    return dwVersion;
}

The following code example illustrates how you can use GetDllVersion to test if Comctl32.dll is version 4.71 or later.

if(GetDllVersion(TEXT("comctl32.dll")) >= PACKVERSION(4,71))
{
    //Proceed.
}
else
{
    //Use an alternate approach for older DLL versions.
}

Project Versions

To ensure that your application is compatible with different targeted versions of Comctl32.dll and Shell32.dll, a version macro was added to the header files. This macro is used to define, exclude, or redefine certain definitions for different versions of the DLL. The macro name is _WIN32_IE, and you are responsible for defining the macro as a hexadecimal number. This version number defines the target version of the application that is using the DLL. The following table shows the available version numbers and the effect each has on your application.

Version | Description
0x0200 | The application is compatible with Comctl32.dll and Shell32.dll version 4.00 and later. The application cannot implement features that were added after version 4.00 of Comctl32.dll.
0x0300 | The application is compatible with Comctl32.dll and Shell32.dll version 4.70 and later. The application cannot implement features that were added after version 4.70 of Comctl32.dll.
0x0400 | The application is compatible with Comctl32.dll and Shell32.dll version 4.71 and later. The application cannot implement features that were added after version 4.71 of Comctl32.dll.
0x0401 | The application is compatible with Comctl32.dll and Shell32.dll version 4.72 and later. The application cannot implement features that were added after version 4.72 of Comctl32.dll.
0x0500 | The application is compatible with Comctl32.dll version 5.80 and later, and Shell32.dll and Shlwapi.dll version 5.0 and later. The application cannot implement features that were added after version 5.80 of Comctl32.dll, or version 5.0 of Shell32.dll and Shlwapi.dll.
0x0501 | The application is compatible with Comctl32.dll version 5.81 and later, and Shell32.dll and Shlwapi.dll version 5.0 and later. The application cannot implement features that were added after version 5.81 of Comctl32.dll, or version 5.0 of Shell32.dll and Shlwapi.dll.

If you do not define this macro in your project, it is automatically be defined as 0x0500. To define a different value, you can add the following to the compiler directives in your make file; substitute the desired version number for 0x0400.

/D _WIN32_IE=0x0400

Another method is to add a line similar to the following in your source code before including the Shell and Common Control header files; substitute the desired version number for 0x0400.

#define _WIN32_IE 0x0400
#include <commctrl.h>

Downloading the Latest Version

To get the most recent version of the Shell and common controls DLLs, download and install Internet Explorer.


Active Desktop

Manages the Active Desktop. Has one interface, IActiveDesktop.


Flags

This section contains the flags used by the methods of the IActiveDesktop interface.

AD_APPLY_ALL
Aggregate of the AD_APPLY_SAVE, AD_APPLY_HTMLGEN, and AD_APPLY_REFRESH values.
Starts a timer and aggregates all the refresh requests made with this flag during that time interval into a single refresh. This interval is currently set at five seconds. At the end of the interval or if a refresh is requested during the interval without a AD_APPLY_BUFFERED_REFRESH flag, the refresh is made and the timer is stopped. This flag must be combined with the AD_APPLY_REFRESH flag.
AD_APPLY_DYNAMICREFRESH
Version 5.0. Use dynamic HTML to refresh only those items that have changed since the last refresh, not the entire desktop.
AD_APPLY_FORCE
Force an Active Desktop change.
AD_APPLY_HTMLGEN
Regenerate the desktop HTML file.
AD_APPLY_REFRESH
Refresh the desktop item.
AD_APPLY_SAVE
Save the desktop item.
COMP_ELEM_ALL
Aggregate of the COMP_ELEM_* values.
COMP_ELEM_CHECKED
The item has been checked.
COMP_ELEM_CURITEMSTATE
The current state of the desktop item.
COMP_ELEM_FRIENDLYNAME
The friendly name of the item.
COMP_ELEM_NOSCROLL
The item is not scrollable.
COMP_ELEM_ORIGINAL_CSI
The original desktop item state information.
COMP_ELEM_POS_LEFT
The horizontal position of the item.
COMP_ELEM_POS_TOP
The vertical position of the item.
COMP_ELEM_POS_ZINDEX
The z-index of the item.
COMP_ELEM_RESTORED_CSI
The restored desktop item state information.
COMP_ELEM_SIZE_HEIGHT
The height of the item.
COMP_ELEM_SIZE_WIDTH
The width of the item.
COMP_ELEM_SOURCE
The original source of the item.
COMP_ELEM_TYPE
The item type.
COMP_TYPE_CFHTML
Compressed format HTML.
COMP_TYPE_CONTROL
The item is a control.
COMP_TYPE_HTMLDOC
The item is an HTML document. This flag should only be used when absolutely necessary. It causes an HTML document to be inserted verbatim into the desktop.htt file used to control layout of the desktop. For most cases, you should use the COMP_TYPE_WEBSITE flag to add items to the desktop.
COMP_TYPE_MAX
The maximum value of a COMP_TYPE_* flag.
COMP_TYPE_PICTURE
The item is a picture.
COMP_TYPE_WEBSITE
The item is a Web site.
COMPONENT_TOP
A z-order value meaning the item is at the top.
WPSTYLE_CENTER
The wallpaper is centered.
WPSTYLE_MAX
The maximum value of a WPSTYLE_* flag.
WPSTYLE_STRETCH
The wallpaper is stretched to fit the entire screen.
WPSTYLE_TILE
The wallpaper is tiled.


IShellFolder2::MapNameToSCID

Converts a column name to the appropriate property set ID (FMTID) and property ID (PID).

HRESULT MapNameToSCID(
    LPCWSTR pwszName,
    SHCOLUMNID *pscid
);

Parameters

pwszName
[in] Pointer to a NULL-terminated Unicode string with the column's language-independent canonical name.
pscid
[out] Pointer to an SHCOLUMNID structure containing the FMTID and PID.

Return Values

Returns NOERROR if successful, or a COM error value otherwise.

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: Declared in Shlobj.h.


CImageDataFactory Object

This is preliminary documentation and is subject to change.

Provides methods for loading, saving, translating, and transforming images from both files and streams.

Remarks

The IShellImageDataFactory::CreateIShellImageData, IShellImageDataFactory::CreateImageFromFile and IShellImageDataFactory::CreateImageFromStream methods all return a reference to an object which implements the IShellImageData interface.

This element is not rendered.

This element requires a closing tag.

Creation/Access Functions

CoCreateInstance Call CoCreateInstance setting the CLSID parameter to CLSID_CImageData.

Interfaces Implemented

IShellImageDataFactory interface

Object Information

Stock Implementation | None
Custom Implementation | No
CLSID | CLSID_CImageData
Minimum operating systems | Whistler


Shell Objects for scripting and Visual Basic

The following objects are implemented by the Shell for use in scripting and Visual Basic®.
DIDiskQuotaUser
DiskQuotaControl
Folder
Folder2
FolderItem
FolderItems
FolderItems2
FolderItemVerb
FolderItemVerbs
IShellDispatch2
IShellLinkDual2
Shell
ShellFolderItem
ShellFolderView
ShellFolderViewOC
ShellLinkObject
ShellUIHelper
ShellWindows
WebViewFolderContents


UserNotification Object

This is preliminary documentation and is subject to change.

Provides methods to supply information to users.

Creation/Access Functions

CoCreateInstance Call CoCreateInstance setting the CLSID parameter to CLSID_UserNotification.

Interfaces Implemented

IUserNotification interface

Object Information

Stock Implementation | None
Custom Implementation | No
Header and IDL files | shobjidl.h, shobjidl.idl
CLSID | CLSID_UserNotification
Minimum operating systems


DiskQuotaControl.TranslateLogonNameToSID

TranslateLogonNameToSID Method

Translates a logon name to the corresponding user security ID in string format.

sidstring = object.TranslateLogonNameToSID(logonname)

Parameters

logonname Required. String value that specifies the user's logon name.

Return Values

Returns the user security ID (SID) in string format corresponding to the provided logon name. The returned string includes the standard enclosing braces. For example:

"{S-1-5-21-2127521184-1604012920-1887927527-19009}"

Remarks

The returned SID string can be passed to the FindUser method in place of a logon name.

When a call to the FindUser(logonname) method fails, it could be due to a mismatch between the form (Security Account Manager [SAM] compatible vs. User Principal Name [UPN]) of the logon name provided and the form stored in the SID-name cache. In such cases, the logon name can be converted to a SID and the call to FindUser repeated. FindUser recognizes a SID string and will bypass the SID-name cache lookup. The following Microsoft® Visual Basic® for Scripting (VBScript) code illustrates this technique.

Function Find(dqc, name)
    On Error Resume Next
    SET Find = dqc.FindUser(name)
    If Err.Number <> 0 Then
        Err.Clear
        SET Find = dqc.FindUser(dqc.TranslateLogonNameToSID(name))
    End If
End Function

Name-to-SID translation can be a slow process when compared to lookups in the SID-name cache. Therefore, it is recommended that FindUser first be called with a logon name. The example above uses this technique.

See Also

DiskQuotaControl Object

Requirements

Version 5.00 and later of Shell32.dll

Windows NT/2000: Requires Windows 2000.
Windows 95/98/Me: Requires Windows Me.
Header: None.


 SOFTDISTINFO

Contains information about a software update.

typedef struct _TagSOFTDISTINFO{
    ULONG	cbSize;
    DWORD	dwFlags;
    DWORD	dwAdState;
    LPWSTR	lpszTitle;
    LPWSTR	lpszAbstract;
    LPWSTR	lpszHREF;
    DWORD	dwInstalledVersionMS;
    DWORD	dwInstalledVersionLS;
    DWORD	dwUpdateVersionMS;
    DWORD	dwUpdateVersionLS;
    DWORD	dwAdvertisedVersionMS;
    DWORD	dwAdvertisedVersionLS;
    DWORD	dwReserved
} SOFTDISTINFO, *LPSOFTDISTINFO;

Members

cbSize
Contains the size of the structure, in bytes.
dwFlags
This parameter can take one of the following values:
  • SOFTDIST_FLAG_USAGE_EMAIL
  • SOFTDIST_FLAG_USAGE_PRECACHE
  • SOFTDIST_FLAG_USAGE_AUTOINSTALL
  • SOFTDIST_FLAG_DELETE_SUBSCRIPTION
dwAdState
The advertised state. It can take one of the following values:
  • 0: Update-available dialog box has not been presented to the user.
  • 1: Files-downloaded dialog box has not been presented to the user.
  • 2: Program-installed dialog box has not been presented to the user.
lpszTitle
String containing the contents of the TITLE flag from the associated CDF file.
lpszAbstract
String containing the contents of the ABSTRACT flag from the associated CDF file.
lpszHREF
String containing the URL of the Web page to advertise or install the update.
dwInstalledVersionMS
Contains the most-significant unsigned long integer value of the installed version number.
dwInstalledVersionLS
Contains the least-significant unsigned long integer value of the installed version number.
dwUpdateVersionMS
Contains the most-significant unsigned long integer value of the update version number.
dwUpdateVersionLS
Contains the Least-significant unsigned long integer value of the update version number.
dwAdvertisedVersionMS
Contains the most-significant unsigned long integer value of the advertised version number.
dwAdvertisedVersionLS
Contains the least-significant unsigned long integer value of the advertised version number.
cbReserved
Reserved. Must be set to zero.

The most-significant unsigned long integer of a version number contains the major and minor version numbers. The least-significant unsigned long integer of the version number contains the custom version and build numbers.

Requirements

Version 4.71 and later of Shell32.dll

Windows NT: Requires version 5.0 or later (or version 4.0 with Internet Explorer 4.0 or later).
Windows: Requires Windows 98 (or Windows 95 with Internet Explorer 4.0 or later).
Header: Declared in Shlobj.h.