From 3291e2e0d532bc3ad2e4cdd1b0da33b0c74a16c3 Mon Sep 17 00:00:00 2001 From: David Hall Date: Mon, 29 Jan 2018 16:22:49 -0700 Subject: [PATCH] Added IFileDialog2, IFileDialogControlEvents, and IFileDialogCustomize. --- PInvoke/Shell32/ShObjIdl.IFileDialog.cs | 319 +++++++++++++++++++++++++++++++- 1 file changed, 310 insertions(+), 9 deletions(-) diff --git a/PInvoke/Shell32/ShObjIdl.IFileDialog.cs b/PInvoke/Shell32/ShObjIdl.IFileDialog.cs index b9e2b87c..cfa1fd56 100644 --- a/PInvoke/Shell32/ShObjIdl.IFileDialog.cs +++ b/PInvoke/Shell32/ShObjIdl.IFileDialog.cs @@ -15,6 +15,20 @@ namespace Vanara.PInvoke { public static partial class Shell32 { + /// Specifies the values that indicate whether a control is visible and enabled. Used by members of the IFileDialogCustomize interface. + [Flags] + public enum CDCONTROLSTATEF : uint + { + /// The control is inactive and cannot be accessed by the user. + CDCS_INACTIVE = 0x00000000, + /// The control is active. + CDCS_ENABLED = 0x00000001, + /// The control is visible. The absence of this value indicates that the control is hidden. + CDCS_VISIBLE = 0x00000002, + /// Windows 7 and later. The control is visible and enabled. + CDCS_ENABLEDVISIBLE = 0x00000003 + } + /// Specifies list placement. [PInvokeData("Shobjidl.h", MSDNShortId = "bb762502")] public enum FDAP : uint @@ -201,7 +215,7 @@ namespace Vanara.PInvoke /// The number of elements in the array specified by rgFilterSpec. /// A pointer to an array of COMDLG_FILTERSPEC structures, each representing a file type. void SetFileTypes(uint cFileTypes, - [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); + [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); /// Sets the file type that appears as selected in the dialog. /// @@ -303,7 +317,7 @@ namespace Vanara.PInvoke /// Enables a calling application to associate a GUID with a dialog's persisted state. /// The GUID to associate with this dialog state. - void SetClientGuid([In, MarshalAs(UnmanagedType.LPStruct)] Guid guid); + void SetClientGuid([MarshalAs(UnmanagedType.LPStruct)] Guid guid); /// Instructs the dialog to clear all persisted state information. void ClearClientData(); @@ -313,6 +327,293 @@ namespace Vanara.PInvoke void SetFilter([MarshalAs(UnmanagedType.Interface)] object pFilter); } + /// + /// Extends the IFileDialog interface by providing methods that allow the caller to name a specific, restricted location that can be browsed in the + /// common file dialog as well as to specify alternate text to display as a label on the Cancel button. + /// + /// + [SuppressUnmanagedCodeSecurity] + [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("61744fc7-85b5-4791-a9b0-272276309b13")] + [PInvokeData("Shobjidl.h", MinClient = PInvokeClient.Windows7)] + public interface IFileDialog2 : IFileDialog + { + /// Launches the modal window. + /// The handle of the owner window. This value can be NULL. + /// + /// If the method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code, including the following: + /// HRESULT_FROM_WIN32(ERROR_CANCELLED) = The user closed the window by canceling the operation. + /// + [PreserveSig] + new HRESULT Show(IntPtr parent); + + /// Sets the file types that the dialog can open or save. + /// The number of elements in the array specified by rgFilterSpec. + /// A pointer to an array of COMDLG_FILTERSPEC structures, each representing a file type. + new void SetFileTypes(uint cFileTypes, + [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); + + /// Sets the file type that appears as selected in the dialog. + /// + /// The index of the file type in the file type array passed to IFileDialog::SetFileTypes in its cFileTypes parameter. Note that this is a one-based + /// index, not zero-based. + /// + new void SetFileTypeIndex(uint iFileType); + + /// Gets the currently selected file type. + /// + /// A UINT value that receives the index of the selected file type in the file type array passed to IFileDialog::SetFileTypes in its cFileTypes parameter. + /// + new uint GetFileTypeIndex(); + + /// Assigns an event handler that listens for events coming from the dialog. + /// A pointer to an IFileDialogEvents implementation that will receive events from the dialog. + /// + /// A DWORD value identifying this event handler. When the client is finished with the dialog, that client must call the IFileDialog::Unadvise method + /// with this value. + /// + new uint Advise(IFileDialogEvents pfde); + + /// Removes an event handler that was attached through the IFileDialog::Advise method. + /// + /// The DWORD value that represents the event handler. This value is obtained through the pdwCookie parameter of the IFileDialog::Advise method. + /// + new void Unadvise(uint dwCookie); + + /// Sets flags to control the behavior of the dialog. + /// One or more of the FILEOPENDIALOGOPTIONS values. + new void SetOptions(FILEOPENDIALOGOPTIONS fos); + + /// Gets the current flags that are set to control dialog behavior. + /// When this method returns successfully, points to a value made up of one or more of the FILEOPENDIALOGOPTIONS values. + new FILEOPENDIALOGOPTIONS GetOptions(); + + /// Sets the folder used as a default if there is not a recently used folder value available. + /// A pointer to the interface that represents the folder. + new void SetDefaultFolder(IShellItem psi); + + /// Sets a folder that is always selected when the dialog is opened, regardless of previous user action. + /// A pointer to the interface that represents the folder. + new void SetFolder(IShellItem psi); + + /// + /// Gets either the folder currently selected in the dialog, or, if the dialog is not currently displayed, the folder that is to be selected when the + /// dialog is opened. + /// + /// The address of a pointer to the interface that represents the folder. + new IShellItem GetFolder(); + + /// Gets the user's current selection in the dialog. + /// + /// The address of a pointer to the interface that represents the item currently selected in the dialog. This item can be a file or folder selected + /// in the view window, or something that the user has entered into the dialog's edit box. The latter case may require a parsing operation + /// (cancelable by the user) that blocks the current thread. + /// + new IShellItem GetCurrentSelection(); + + /// Sets the file name that appears in the File name edit box when that dialog box is opened. + /// A pointer to the name of the file. + new void SetFileName([MarshalAs(UnmanagedType.LPWStr)] string pszName); + + /// Retrieves the text currently entered in the dialog's File name edit box. + /// The address of a pointer to a buffer that, when this method returns successfully, receives the text. + new SafeCoTaskMemString GetFileName(); + + /// Sets the title of the dialog. + /// A pointer to a buffer that contains the title text. + new void SetTitle([MarshalAs(UnmanagedType.LPWStr)] string pszTitle); + + /// Sets the text of the Open or Save button. + /// A pointer to a buffer that contains the button text. + new void SetOkButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszText); + + /// Sets the text of the label next to the file name edit box. + /// A pointer to a buffer that contains the label text. + new void SetFileNameLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + + /// Gets the choice that the user made in the dialog. + /// The address of a pointer to an IShellItem that represents the user's choice. + new IShellItem GetResult(); + + /// Adds a folder to the list of places available for the user to open or save items. + /// A pointer to an IShellItem that represents the folder to be made available to the user. This can only be a folder. + /// Specifies where the folder is placed within the list. + new void AddPlace(IShellItem psi, FDAP fdap); + + /// Sets the default extension to be added to file names. + /// + /// A pointer to a buffer that contains the extension text. This string should not include a leading period. For example, "jpg" is correct, while + /// ".jpg" is not. + /// + new void SetDefaultExtension([MarshalAs(UnmanagedType.LPWStr)] string pszDefaultExtension); + + /// Closes the dialog. + /// The code that will be returned by Show to indicate that the dialog was closed before a selection was made. + new void Close([MarshalAs(UnmanagedType.Error)] HRESULT hr); + + /// Enables a calling application to associate a GUID with a dialog's persisted state. + /// The GUID to associate with this dialog state. + new void SetClientGuid([MarshalAs(UnmanagedType.LPStruct)] Guid guid); + + /// Instructs the dialog to clear all persisted state information. + new void ClearClientData(); + + /// Sets the filter. Deprecated. SetFilter is no longer available for use as of Windows 7. + /// A pointer to the IShellItemFilter that is to be set. + new void SetFilter([MarshalAs(UnmanagedType.Interface)] object pFilter); + + /// Replaces the default text "Cancel" on the common file dialog's Cancel button. + /// Pointer to a string that contains the new text to display on the button. + void SetCancelButtonLabel([MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + + /// Specifies a top-level location from which to begin browsing a namespace, for instance in the Save dialog's Browse folder option. Users cannot navigate above this location. + /// Pointer to an IShellItem object that represents the navigation root. + void SetNavigationRoot([MarshalAs(UnmanagedType.Interface)] IShellItem psi); + } + + /// + /// Exposes methods that allow an application to be notified of events that are related to controls that the application has added to a common file dialog. + /// + [SuppressUnmanagedCodeSecurity] + [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("36116642-D713-4b97-9B83-7484A9D00433")] + [PInvokeData("Shobjidl.h")] + public interface IFileDialogControlEvents + { + /// Called when [item selected]. + /// The PFDC. + /// The dw identifier control. + /// The dw identifier item. + /// + [PreserveSig] + HRESULT OnItemSelected(IFileDialogCustomize pfdc, uint dwIDCtl, uint dwIDItem); + /// Called when [button clicked]. + /// The PFDC. + /// The dw identifier control. + /// + [PreserveSig] + HRESULT OnButtonClicked(IFileDialogCustomize pfdc, uint dwIDCtl); + /// Called when [check button toggled]. + /// The PFDC. + /// The dw identifier control. + /// if set to true [b checked]. + /// + [PreserveSig] + HRESULT OnCheckButtonToggled(IFileDialogCustomize pfdc, uint dwIDCtl, [MarshalAs(UnmanagedType.Bool)] bool bChecked); + /// Called when [control activating]. + /// The PFDC. + /// The dw identifier control. + /// + [PreserveSig] + HRESULT OnControlActivating(IFileDialogCustomize pfdc, uint dwIDCtl); + } + + /// Exposes methods that allow an application to add controls to a common file dialog. + [SuppressUnmanagedCodeSecurity] + [ComImport, Guid("e6fdd21a-163f-4975-9c8c-a69f1ba37034"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)] + public interface IFileDialogCustomize + { + /// Enables a drop-down list on the Open or Save button in the dialog. + /// The ID of the drop-down list. + void EnableOpenDropDown(uint dwIDCtl); + /// Adds a menu to the dialog. + /// The ID of the menu to add. + /// A pointer to a buffer that contains the menu name as a null-terminated Unicode string. + void AddMenu(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + /// Adds a button to the dialog. + /// The ID of the button to add. + /// A pointer to a buffer that contains the button text as a null-terminated Unicode string. + void AddPushButton(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + /// Adds a combo box to the dialog. + /// The ID of the combo box to add. + void AddComboBox(uint dwIDCtl); + /// Adds an option button (also known as radio button) group to the dialog. + /// The ID of the option button group to add. + void AddRadioButtonList(uint dwIDCtl); + /// Adds a check button (check box) to the dialog. + /// The ID of the check button to add. + /// A pointer to a buffer that contains the button text as a null-terminated Unicode string. + /// A BOOL indicating the current state of the check button. TRUE if checked; FALSE otherwise. + void AddCheckButton(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszLabel, [MarshalAs(UnmanagedType.Bool)] bool bChecked); + /// Adds an edit box control to the dialog. + /// The ID of the edit box to add. + /// A pointer to a null-terminated Unicode string that provides the default text displayed in the edit box. + void AddEditBox(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszText); + /// Adds a separator to the dialog, allowing a visual separation of controls. + /// The control ID of the separator. + void AddSeparator(uint dwIDCtl); + /// Adds text content to the dialog. + /// The ID of the text to add. + /// A pointer to a buffer that contains the text as a null-terminated Unicode string. + void AddText(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszText); + /// Sets the text associated with a control, such as button text or an edit box label. + /// The ID of the control whose text is to be changed. + /// A pointer to a buffer that contains the text as a null-terminated Unicode string. + void SetControlLabel(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + /// Gets the current visibility and enabled states of a given control. + /// The ID of the control in question. + /// A variable that receives one or more values from the CDCONTROLSTATE enumeration that indicate the current state of the control. + CDCONTROLSTATEF GetControlState(uint dwIDCtl); + /// Sets the current visibility and enabled states of a given control. + /// The ID of the control in question. + /// One or more values from the CDCONTROLSTATE enumeration that indicate the current state of the control. + void SetControlState(uint dwIDCtl, CDCONTROLSTATEF dwState); + /// Gets the current text in an edit box control. + /// The ID of the edit box. + /// The address of a pointer to a buffer that receives the text as a null-terminated Unicode string. + void GetEditBoxText(uint dwIDCtl, out SafeCoTaskMemString ppszText); + /// Sets the text in an edit box control found in the dialog. + /// The ID of the edit box. + /// A pointer to a buffer that contains the text as a null-terminated Unicode string. + void SetEditBoxText(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszText); + /// Gets the current state of a check button (check box) in the dialog. + /// The ID of the check box. + /// A BOOL value that indicates whether the box is checked. TRUE means checked; FALSE, unchecked. + [return: MarshalAs(UnmanagedType.Bool)] + bool GetCheckButtonState(uint dwIDCtl); + /// Sets the state of a check button (check box) in the dialog. + /// The ID of the check box. + /// A BOOL value that indicates whether the box is checked. TRUE means checked; FALSE, unchecked. + void SetCheckButtonState(uint dwIDCtl, [MarshalAs(UnmanagedType.Bool)] bool bChecked); + /// Adds an item to a container control in the dialog. + /// The ID of the container control to which the item is to be added. + /// The ID of the item. + /// A pointer to a buffer that contains the item's text, which can be either a label or, in the case of a drop-down list, the item itself. This text is a null-terminated Unicode string. + void AddControlItem(uint dwIDCtl, int dwIDItem, [MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + /// Removes an item from a container control in the dialog. + /// The ID of the container control from which the item is to be removed. + /// The ID of the item. + void RemoveControlItem(uint dwIDCtl, int dwIDItem); + /// Not implemented. + /// + void RemoveAllControlItems(uint dwIDCtl); + /// Gets the current state of an item in a container control found in the dialog. + /// The ID of the container control. + /// The ID of the item. + /// A pointer to a variable that receives one of more values from the CDCONTROLSTATE enumeration that indicate the current state of the control. + CDCONTROLSTATEF GetControlItemState(uint dwIDCtl, int dwIDItem); + /// Sets the current state of an item in a container control found in the dialog. + /// The ID of the container control. + /// The ID of the item. + /// One or more values from the CDCONTROLSTATE enumeration that indicate the new state of the control. + void SetControlItemState(uint dwIDCtl, int dwIDItem, CDCONTROLSTATEF dwState); + /// Gets a particular item from specified container controls in the dialog. + /// The ID of the container control. + /// The ID of the item that the user selected in the control. + uint GetSelectedControlItem(uint dwIDCtl); + /// Sets the selected state of a particular item in an option button group or a combo box found in the dialog. + /// The ID of the container control. + /// The ID of the item to display as selected in the control. + void SetSelectedControlItem(uint dwIDCtl, int dwIDItem); + /// Declares a visual group in the dialog. Subsequent calls to any "add" method add those elements to this group. + /// The ID of the visual group. + /// A pointer to a buffer that contains text, as a null-terminated Unicode string, that appears next to the visual group. + void StartVisualGroup(uint dwIDCtl, [MarshalAs(UnmanagedType.LPWStr)] string pszLabel); + /// Stops the addition of elements to a visual group in the dialog. + void EndVisualGroup(); + /// Places a control in the dialog so that it stands out compared to other added controls. + /// The ID of the control. + void MakeProminent(uint dwIDCtl); + } + /// Exposes methods that allow notification of events within a common file dialog. [SuppressUnmanagedCodeSecurity] [ComImport, InterfaceType(ComInterfaceType.InterfaceIsIUnknown), Guid("973510DB-7D7F-452B-8975-74A85828D354")] @@ -424,7 +725,7 @@ namespace Vanara.PInvoke /// The number of elements in the array specified by rgFilterSpec. /// A pointer to an array of COMDLG_FILTERSPEC structures, each representing a file type. new void SetFileTypes(uint cFileTypes, - [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); + [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); /// Sets the file type that appears as selected in the dialog. /// @@ -526,7 +827,7 @@ namespace Vanara.PInvoke /// Enables a calling application to associate a GUID with a dialog's persisted state. /// The GUID to associate with this dialog state. - new void SetClientGuid([In, MarshalAs(UnmanagedType.LPStruct)] Guid guid); + new void SetClientGuid([MarshalAs(UnmanagedType.LPStruct)] Guid guid); /// Instructs the dialog to clear all persisted state information. new void ClearClientData(); @@ -686,7 +987,7 @@ namespace Vanara.PInvoke /// The number of elements in the array specified by rgFilterSpec. /// A pointer to an array of COMDLG_FILTERSPEC structures, each representing a file type. new void SetFileTypes(uint cFileTypes, - [In, MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); + [MarshalAs(UnmanagedType.LPArray, SizeParamIndex = 0)] COMDLG_FILTERSPEC[] rgFilterSpec); /// Sets the file type that appears as selected in the dialog. /// @@ -788,7 +1089,7 @@ namespace Vanara.PInvoke /// Enables a calling application to associate a GUID with a dialog's persisted state. /// The GUID to associate with this dialog state. - new void SetClientGuid([In, MarshalAs(UnmanagedType.LPStruct)] Guid guid); + new void SetClientGuid([MarshalAs(UnmanagedType.LPStruct)] Guid guid); /// Instructs the dialog to clear all persisted state information. new void ClearClientData(); @@ -803,7 +1104,7 @@ namespace Vanara.PInvoke /// Provides a property store that defines the default values to be used for the item being saved. /// Pointer to the interface that represents the property store that contains the associated metadata. - void SetProperties([In] PropSys.IPropertyStore pStore); + void SetProperties(PropSys.IPropertyStore pStore); /// Specifies which properties will be collected in the save dialog. /// Pointer to the interface that represents the list of properties to collect. This parameter can be NULL. @@ -811,7 +1112,7 @@ namespace Vanara.PInvoke /// TRUE to show default properties for the currently selected filetype in addition to the properties specified by pList. FALSE to show only /// properties specified by pList. /// - void SetCollectedProperties(PropSys.IPropertyDescriptionList pList, [In, MarshalAs(UnmanagedType.Bool)] bool fAppendDefault); + void SetCollectedProperties(PropSys.IPropertyDescriptionList pList, [MarshalAs(UnmanagedType.Bool)] bool fAppendDefault); /// Retrieves the set of property values for a saved item or an item in the process of being saved. /// Address of a pointer to an IPropertyStore that receives the property values. @@ -827,7 +1128,7 @@ namespace Vanara.PInvoke /// Pointer to an optional IFileOperationProgressSink that the calling application can use if they want to be notified of the progress of the /// property stamping. This value may be NULL. /// - void ApplyProperties(IShellItem psi, PropSys.IPropertyStore pStore, [In] IntPtr hwnd, IFileOperationProgressSink pSink); + void ApplyProperties(IShellItem psi, PropSys.IPropertyStore pStore, IntPtr hwnd, IFileOperationProgressSink pSink); } /// Exposes a method that represents a modal window. This interface is used in the Windows XP Passport Wizard.