TApOpenDialog and TApSaveDialog components

Inherited from : TOpenDialog and TSaveDialog

unit: ApOpenDlg, ApSaveDlg

Custom versions: TApCustomOpenDialog and TApCustomSaveDialog.

Much more powerful replacement for TOpen/SaveDialog components shipped with Delphi/C++Builder.

Types

Properties

Methods

Events



TApOpenDlgControls and TApOpenDlgControl

TApOpenDlgControl = ( dcFolderCombo,
dcFolderLabel,
dcSelectionCtrl,
dcOkBtn,
dcCancelBtn,
dcFileName,
dcFileNameLabel,
dcFileType,
dcFileTypeLabel,
dcToolBar );

TApOpenDlgControls = set of TApOpenDlgControl;

These types are used in VisibleControls property to specify wich dialog controls are visible.



Properties


CustDlgParams : TApCustDlgParams; RW

Published; protected in custom version

This variable contains all information about side panels of the standard dialog. See TApCustDlgPatams type for details.

For Open/Save dialogs CustDlgParams.CustomForm points to form wich is the replacement for standard selection shell list view when SelectionType property value is stCustom.


SelectionType : TApDlgSelectionType; RW

Published; protected in custom version

Can be one of the following values : stStandard or stCustom. stStandard value points that standard shell selection control is visible and active. stCustom value specifies that any other Delphi form specified in CustDlgParams.CustomForm property is used as selection control. You can use this property even when your dialog is already visible and active.


SelectionStyle : TViewStyle; R; use when dialog is visible

Published; protected in custom version;

Returns list view style of selection shell list view. There is no at this moment support for Millennium's Trumbhails style (vsIcon in this case is returned).


EditHandle : HWND; use when dialog is visible.

Protected

The EditHandle property, which provides access to the dialog’s edit control handle after a call to Execute, can be used in "dialog-time" event handlers. EditHandle is reset to 0 after the dialog is closed.


VisibleControls : TApOpenDlgControls; RW

Published; protected in custom version

Determines the visibility of the file-selection dialog controls.


DlgHandle : HWND; R; use when dialog is visible.

Public

The handle of the dialog box. Keep in mind that its not the same as TOpenDialog.Handle protected property. DlgHandle property is reset to 0 after the dialog is closed.


SelectedFolder : string; R; use when dialog is visible.

Public; protected in custom version

Access this Read-only property to get currently selected folder path in the dialog box.


SelectedFiles : string; RW; use when dialog is visible.

Public; protected in custom version

Read this property to get currently selected files in the dialog box. The result is in the folowing form:

"file1.txt" "file2.txt" "file3.txt" "file4" ...

Write to this property to set file names you want to be displayed in the filename edit box.


SelectedFilesList : TStrings; RW; use when dialog is visible.

Public; Protected in custom version

Read this property to get currently selected files as TStrings collection. The result has the following form:

file1.txt
file2.txt
file3.txt
...

Write to this property to set file names you want to be displayed in the filename edit box.


DlgItemsCaptions : TApOpenDlgCaptions

Published; protected in custom version

You can set items in this property to replace labels for standard controls inside dialog. For example you can replace OK button caption using DlgItemsCaptions.OK property and so on. If there is no value in any subitem then original text is displayed.


ListViewStyles : TApListViewStyles

Published; protected in custom version

TApListViewStyles = class(TPersistent)    // declared in ApDlgParams module
published
  property lvHotTrack : boolean;     
  property lvHotTrackStyles : TListHotTrackStyles;  
<< not available in Delphi/C++Builder Version 3
  property lvGridLines : boolean;
  property lvRowSelect : boolean;
  property lvEnableEdit : boolean;
  property lvEnableDelete : boolean;
  property lvFlatScrollBars : boolean;
end;

Set sub-properties values of ListViewStyles property to provide your shell list view with some additional styles wich can not be specified using standard properties TOpen/SaveDialog components and Windows Common Dialogs API. For example set lvRowSelect property value to true to allow user to select the whole list item (with subitems) if ListView style is Report(Details). Most of these properties have corresponding property in VCL TListView component (for example there is RowSelect property in TListView) and you can read VCL Reference for details about these properties. The only note:

Setting lvEnableDelete or lvEnableEdit properties values to false lead to disabling the appropriate shell vist view's context menu items. You also can not delete any file or folder using Del key in this case.



Methods


no new items.



Events


All the new event handlers are "dialog-time".

All event handlers are published; They are protected in custom versions of these components


OnCanClose : TCloseQueryEvent

Occurs when you try to close dialog box by pressing OK button. See VCL Reference for help. TCloseQueryEvent  - VCL class (Forms unit).


OnFolderCreating : TApCtrlQueryEvent

Occurs if user presses "Create Folder" tool button. Note that this event does not occur if you create folder using shell list view's context menu.


OnDesktopNavigating : TApCtrlQueryEvent

Occurs if user presses "Show Desktop" tool button DesktopBtn.gif (1027 bytes) on the toolbar. Note that this event does not occur if you open desktop contents using LookIn combo box. Remember that there is no such button under Millennium. You can set AllowProceed variable to false to prevent desktop displaying.


OnDesktopNavigate : TNotifyEvent

This event occurs if you have pressed "Show Desktop" button and if AllowProceed variable in OnDesktopNavigating handler was not set to false.


OnUpLevelNavigating : TApCtrlQueryEvent

This event occurs if user presses "Up Level" tool button UpLevelBtn.gif (967 bytes). You can set AllowProceed variable to false to prevent this action.


OnUpLevelNavigate : TNotifyEvent

This event occurs if you have pressed "Up Level" button and if AllowProceed variable in OnUpLevelNavigating handler was not set to false. You can evaluate SelectedFolder property to determine currently selected folder in this event handler.


OnFilenameChange : TNotifyEvent

Occurs when user changes text in the filename edit box.


OnLastFolderNavigating : TApCtrlQueryEvent     Windows 5.0 only

Occurs if user tries to go back to last visited folder by pressing "Last Folder Visited" tool button wpe2.jpg (707 bytes) . Works under Windows Millennium only (there is no appropriate button in Win95/98/NT4).


OnLastFolderNavigate : TNotifyEvent

Occurs when you have pressed "List Folder Visited" tool button under Millennium.


OnSelectionStyleChanging : TApViewStyleQueryEvent

type TApViewStyleQueryEvent = procedure (Sender: TObject; AStyle : TViewStyle; var AllowChange : boolean) of object;

Occurs when you try to change shell list view style (for example by pressing List or Details button on the toolbar). Set AllowChange to false to prevent listview style changing.


OnSelectionStyleChange : TApViewStyleEvent

type TApViewStyleEvent = procedure ((Sender: TObject; AStyle : TViewStyle) of object;

Occurs when shell list view style have changed. AStyle - listview's style wich now is selected.


OnShareViolation : TApShareViolationEvent         DID NOT TESTED YET!

TApShareViolationEvent = procedure (Sender : TObject; var DlgResult : LongInt; FileName : string) of object;

Occurs when The common dialog box encountered a sharing violation on the file about to be returned. This handler does not occur in this case if ofShareAware flag in Options property is set to True.


OnEventHook : TWndMethod

General hook procedure. You can hook any message you want directry in this handler. This handler occurs after dialog procedure has processed current message.


OnEventHooking : TApMsgQueryEvent

You can determine here whether dialog box procedure should process current message (m parameter).  Set AllowDispatch to false to prevent this message's processing by dialog box procedure. Note that some messages wich are specific to call-back procedure could not be dispatched in this handler. For example you can not process WM_NOTIFY message with CDN_FOLDERCHANGE notification code.