An important feature of almost any software application is the ability to persist and remember settings between different instances of the application. Putting user interface customization aside, remembering commonly or previously accessed files and providing the ability to reopen those files with a shortcut can be quite a useful feature. Having recent document shortcuts without the need to navigate through the traditional file system dialog can save a significant amount of time, increasing productivity in the end.
The Documents folder (My Recent Documents folder on Windows XP and 2003) on the Start menu contains a listing of recently accessed files and documents. One of the most important design considerations for software is the concept of interface transparency. An application should behave the same as other applications on the operating system. This is so the user can easily navigate the application by using knowledge learned from other applications. Users have come to expect that recently opened or saved files from your application appear in the recent documents list, so this topic will show how to programmatically interact with this feature of Windows.
The code to implement this feature is very simple. The solution involves a few PInvoke calls, so the first logical step is to include the appropriate namespace.
using System.Runtime.InteropServices;
The API signatures we will invoke are described in the following code. The first signature is sent the pointer type, along with a pointer to the actual data. The second signature is nearly identical to the first, except a string is passed into it instead of a pointer.
[DllImport("shell32.dll")]
internal static extern void SHAddToRecentDocs(UInt32 pointerType, IntPtr pointer);
[DllImport("shell32.dll")]
internal static extern void SHAddToRecentDocs(UInt32 pointerType,
[MarshalAs(UnmanagedType.LPWStr)] string pointer);There are three flavors of the SHAddToRecentDocs method that can be used, specified by the PointerType enumeration. These pointer types are defined in the following code, and are described in Table 33.1.
Table 33.1. SHAddToRecentDocs Pointer Types
Pointer Type | Description |
|---|---|
| Pointer to a |
| Pointer to a null terminated string with the path and filename of the object |
| Pointer to a null terminated string with the path and filename of the object; Unicode formatting |
internal enum PointerType
{
SHARD_PIDL = 0x00000001,
SHARD_PATHA = 0x00000002,
SHARD_PATHW = 0x00000003,
}Using the method is very easy. You can either pass in the PIDL of the file if you have it, or simply specify the system path to the file as a string. Doing so will create a shortcut to the file and place it in the Recent Documents folder. The following code shows how to do this.
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PATHW),
path);Clearing the Recent Documents folder is even easier! Passing a null PIDL pointer into the method will clear all the entries. The following code shows how to do this.
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PIDL)
IntPtr.Zero);Using the code is extremely straightforward. The following example clears all current entries in the Recent Documents menu, and then adds four new entries to it.
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PIDL),
IntPtr.Zero);
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PATHW),
@"C:MyFolderFile1.txt");
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PATHW),
@"C:MyOtherFolderFile2.doc");
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PATHW),
@"C:ImagesFile3.gif");
SHAddToRecentDocs(Convert.ToUInt32(PointerType.SHARD_PATHW),
@"C:MyFolderFile4.zip");Managing items in the recent documents folder is extremely trivial, but do not underestimate the significance of implementing features like this. Users expect all applications to function the same way; if they don’t, you end up breaking interface transparency, and users will hate your program because of it.