_SHGDNF enumeration (shobjidl_core.h)

Article
01/31/2022

Defines the values used with the IShellFolder::GetDisplayNameOf and IShellFolder::SetNameOf methods to specify the type of file or folder names used by those methods.

Note Prior to Windows 7, these values were packaged as the SHGNO enumeration.

Syntax

typedef enum _SHGDNF {
  SHGDN_NORMAL = 0,
  SHGDN_INFOLDER = 0x1,
  SHGDN_FOREDITING = 0x1000,
  SHGDN_FORADDRESSBAR = 0x4000,
  SHGDN_FORPARSING = 0x8000
} ;

Constants


`SHGDN_NORMAL` Value: 0 When not combined with another flag, return the parent-relative name that identifies the item, suitable for displaying to the user. This name often does not include extra information such as the file name extension and does not need to be unique. This name might include information that identifies the folder that contains the item. For instance, this flag could cause IShellFolder::GetDisplayNameOf to return the string "username (on Machine)" for a particular user's folder.
`SHGDN_INFOLDER` Value: 0x1 The name is relative to the folder from which the request was made. This is the name display to the user when used in the context of the folder. For example, it is used in the view and in the address bar path segment for the folder. This name should not include disambiguation information—for instance "username" instead of "username (on Machine)" for a particular user's folder. Use this flag in combinations with SHGDN_FORPARSING and SHGDN_FOREDITING.
`SHGDN_FOREDITING` Value: 0x1000 The name is used for in-place editing when the user renames the item.
`SHGDN_FORADDRESSBAR` Value: 0x4000 The name is displayed in an address bar combo box.
`SHGDN_FORPARSING` Value: 0x8000 The name is used for parsing. That is, it can be passed to IShellFolder::ParseDisplayName to recover the object's PIDL. The form this name takes depends on the particular object. When SHGDN_FORPARSING is used alone, the name is relative to the desktop. When combined with SHGDN_INFOLDER, the name is relative to the folder from which the request was made.

Remarks

The SHGDNF type is defined in Shobjidl.h as shown here.

typedef DWORD SHGDNF;

This enumeration consists of two groups of values. The first group—SHGDN_NORMAL and SHGDN_INFOLDER—specifies the name's type. The second group—SHGDN_FOREDITING, SHGDN_FORADDRESSBAR, and SHGDN_FORPARSING—consists of modifiers to the first group that specify name retrieval options.

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	SHGDN_FORPARSING	Returns the fully qualified parsing name.
2	SHGDN_INFOLDER \| SHGDN_FORPARSING	Returns the parsing name relative to the parent folder.
3	SHGDN_INFOLDER \| SHGDN_FOREDITING	Returns the editing name relative to the parent folder.
4	SHGDN_INFOLDER	Returns the display name relative to the parent folder.
5	SHGDN_NORMAL	Returns the display name relative to the desktop and not to a specific folder.

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

Requirement	Value
Minimum supported client	Windows XP, Windows 7 [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	shobjidl_core.h (include Shobjidl.h)