Tech Note 04: Common Dialog Control

January 3, 2007

Documented version: 1.0.1

© NSB Corporation. All rights reserved.

Overview
Special Note on Pocket PC Devices
Common Dialog Reference
Common Dialog Flags
Help Files and PegHelp Usage Example
Version History

1. Overview

NSBasic Common Dialogs ActiveX (ComDlg) control provides access to some of the system defined common dialog boxes. These are file open/save dialog, color choosing dialog, and font choosing dialog.

The NSBComDlg ActiveX control is implemented in manner similar to the Microsoft's common dialog ActiveX control. It is almost fully compatible with existing code that uses that control. NSBasic's ComDlg control provides a number of features that allow the developer to write better readable code, easily access additional features and avoid mistakes.

Creation

The object can be created explicitly using this code:

ComDlg

ProgID: NSBasic.ComDlg
ClassID: {9DF344D4-66FB-4660-A569-AC8586CFE9FF}
Create example: AddObject "NSBasic.ComDlg", "MyComDlg"

See also: ComDlgFlags objectwhich is non-creatable. It is returned by the ComDlg.Flags property and provides both low-level and high-level flags access.

Alternatively you can add its DLL to the NSBasic toolbox and place a ComDlg control on a form. We recommend the second way, because it gives the object access to the form object, thus allowing it to create modal dialog boxes.

How to add the control to the toolbox manually: Make sure that the Windows desktop version of control's DLL (NSBComDlg.dll) is installed/registered on your machine. Open the ActiveX Control manager dialog box from the tool menu, browse for the DLL and add it. Note that for the both NSBasic development environments (Desktop and CE) the desktop version of the DLL is used. The specific version for the device is needed only when the application is deployed. This is so, because the IDE uses only the registration information for the DLL.

Architecture

The same ComDlg object controls/shows all the supported system common dialogs. This means that you can show any of these dialogs using the same object. The settings specific to a certain common dialog affect only its appearance, thus the application does not usually need separate instance for each dialog type it shows. Still, it is up to you to determine what is best in your particular case - sometimes it may be easier to create one ComDlg object for showing file open dialogs, one for font selection and so on. In other cases it is more convenient to use a single instance of the object to show all the needed dialogs.

The ComDlg object provides the Reset method which provides a simple way to initialize and configure the object with the most common settings for a certain common dialog type.

See more details on the ComDlg's page.

Typical usage

The typical usage of the ComDlg object follows a simple pattern for all the dialog types it supports. The example lines below are for file open dialog, but the sequence of actions is the same for all the dialog types.

Usually the first step is to reset the object for a the dialog you are about to show:
NSComDlg1.Reset "File"

Then some flags are set to configure the dialog appearance and features:
NSComDlg1.Flags.MultiSelect = True ' We will accept multiple files
NSComDlg1.Flags.NoChangeDir = True
... some other flags ...

Show the dialog
If Not NSComDlg1.ShowOpen Then
    ' Action is cancelled - usually this means skip the operation
Else
    ' Obtain and use the user selection
    For Each sqlFile In NSComDlg1.FileNames
        ' Do something with each file, for the sake of the example let show them in message boxes
        MsgBox NSComDlg1.InitDir & "\" & sqlFile
    Next
End If

In the reality you may want to show the dialog multiple times with the last settings. In such case you would want to call Reset, set the desired flags only once and then show the dialog when needed. This can be done by putting the one-time code in the Form.Load for example and the rest in the methods in which the dialog must be shown. The initial values of the object properties are different case - you may want or not want to set them every time you show the dialog. It is also possible that you would want to keep most of them constant and change only some. In the above example you may want to have the dialog title set to the same text always and different directory for each dialog invocation. Separate the initialization code as appropriate considering the flow of the code execution in your application.

Supported platforms and compatibility

The library is available as single DLL named: NSBComDlg.dll.

The ActiveX looks for the application the same way on each platform, but the actual functionality depends on the system. This is because it shows system defined standard dialogs. On some platforms some of them may not be available. In such case the corresponding method that show the dialog would return False or raise error depending on the value of the CancelError property. Thus on platforms where certain dialog is not provided by the system the object will behave as if the user always cancels the dialog.

Aside of the system common dialogs existence the implementation of the common dialogs differs on each platform. This is caused mostly because of platform specifics. Therefore some flags may have no effect on certain platform - see the ComDlgFlags object for details.

Here is the list of the currently supported platforms with some notes about the system common dialogs availability. If you want to use the same code for all the platforms it is highly recommended to review the list and determine the effect of the platform differences over the application.

Platform(s)	Notes
Windows desktop/tablet/laptop	All the dialogs are available to the full extent of their features.
Palm-sized PC	The Font selection dialog (ShowFont) may not be available. The file open/save dialog provides access only to certain directories. Color dialog does not support extended panel*.
Handheld PC (Pro and 2000)	All the dialogs are available. Some minor features may not be available for some dialogs.
Pocket PC (incl. 2002, 2003 and later)	On Pocket PC 2000 (the oldest one - very rare today) the Font dialog may not be available**. The Color dialog (Choose color) does not support the extended panel. The file open/save dialogs allow access only to certain directories.
Windows CE.NET version 4 and later based devices (tablets, media devices etc.)	The functionality is virtually equivalent to the Windows desktop except for some layout differences.

* - The practice came from the world of the Palm devices. In order to ensure that inexperienced users wont get lost on the device the open/save dialogs and even alternative implementations (from MFC for instance) allow on these devices the user to open save files only in the "My Documents" directory, its first level subdirectories and the root and the first level sub-directories of the memory cards. This usually good enough because the files the application saves/loads are usually wanted in these locations. An alternative implementation may be provided in future versions of the control - your feedback is welcome. See Pocket PC notes for detailed explanation of the Pocket PC behavior specifics.

** - The color selection dialog on Pocket PC based devices is more simplistic than on the desktops and CE devices with bigger screens. For instance it has no free-color selection panel.

*** - Font dialog is not listed in the Pocket PC SDK's header files. In the reality it is available on virtually all of the existing Pocket PC and later device. The control will show it if it is implemented. You may expect problems only on the first Pocket PC devices (2000 edition) which are mostly extinct and rarely considered as targets by the projects today. The Font dialog on Pocket PC is rather simplistic - it has no font preview, looks a little bare-boned, but it works fine.

Troubleshooting

File open/save dialog.

The dialog does not show. Make sure you set the FileName property to an empty string or valid file name (not necessarily existing - just syntactically correct). Check the flags you use and clear those that are not needed and any flags that may conflict with each other.

No files are shown in the file list (especially on Pocket PC). Make sure you have a non-empty filter. See Filter property for more details.

Font dialog

The dialog does not show on a certain device. The device may have an OS version that does not implement the dialog. If this happens only on a device with Pocket PC 2000 or earlier OS version you can be certain that this is the case.

No fonts or not all fonts are listed. See if you have at least one of the ScreenFonts, PrinterFonts flags set to True. See also the other flags that concern the font types enabled for selection.

2. Special Note on Pocket PC Devices

In PocketPC (all versions) and the Pocket PC ancestor (Palm-Sized PC) the standard file open/save dialogs are designed in a way inspired by the Palm OS. Perhaps some people in Microsoft already regret this, but it is a fact and we need to cope with it.

FILE OPEN DIALOG

So, the file open dialog (unlike in the desktop and full CE version) is more like a filtered search and not a single directory view. Thus you have a directory filter, and file type filter (in open file) and a list of files.

The file list contains all the files with the selected file extension in a 1-level directory on all the storage devices. Note that for the internal storage the dialog uses "My Documents" as a root directory and not the device root directory. Thus from the FILE OPEN dialog perspective you have these storage devices:

\My Documents
\Memory Card1
\Memory Card2
... etc ...

Of course the names of the memory cards varies from device to device.

The dialog can show files only in these locations and in 1-st level subdirectories in them. As the directory combo box (by itself) specifies a filter and not a complete location it may contain only a name and not a full path. Thus

NSBComDlg1.InitDir = "\Some card\somedir"
is invalid and will be ignored or may cause strange results on some versions of the OS, but
NSBComDlg1.InitDir = "somedir"
is valid and will initialize the directory filter with "somedir" and the files in

\My Documents\somedir
\Memory card1\somedir
... etc ..

will be listed. Of course that directory should exist in one or more of these locations.

FILE SAVE DIALOG

In this dialog there are 3 filters:

1. Folder (directory)
2 .File type
3. Location (meaning in fact storage card/device)

InitDir is of no use here, it is even treated a bit incorrectly by the system. Thus you should use FileName property to initialize the dialog:

NSComDlg1.FileName = "\Storage device\Directory\filename.ext"
or
NSComDlg1.FileName = "\My Documents\\filename.ext"
or
NSComDlg1.FileName = "\Storage device\filename.ext"

I.e. you must specify a full path name. The file name at the end may be whatever you want - treat it as a proposed file name for example.

You cannot omit any of the path parts without risking strange behavior on some Pocket PC OS versions. Furthermore on some occasions the system gets confused if the proposed file name is only one character long - so propose a descriptive file name to the user when OpenSave is invoked and no prior save operation has been performed (from which you may keep the last name under which the file has been saved).

The IsPocketPC property.

The NSComDlg object provides a property named IsPocketPC which returns True if the platform on which the application runs is a Pocket PC. Using it you can implement different behavior for Pocket PC and other platforms thus making the code reusable regardless of the platform. The only other way is to use only the FileName property for initialization and specify full path name in it. In this case only the Open file dialog on Pocket PC will not initialize with any specific directory which seems to be the acceptable sacrifice if the aim is single code to serve all the platforms.

CONCLUSION

The NSBASIC Common Dialogs control makes use of the system provided standard dialog boxes and does not implement them. Therefore it reflects the system behavior and all the mentioned specifics are the same no matter how you use the corresponding dialogs - from NSBasic or from C for example. Unfortunately the limitations of the File open/save dialogs on Pocket PC make it nearly impossible to use the same code as on a desktop or on a full scale Windows CE device (such as HPC or a tablet). An implementation of own file dialogs has been considered, but there are two reasons to provide this control in this form:

1. The Pocket PC users are already familiar with this behavior which is also exerted by some alternative dialog implementations from Microsoft (for instance applications built using MFC use file view with similar limitations - see pocket word and excel for example). Therefore, no matter how you feel about these dialogs they are already a standard and the applications designed for regular users should use them to keep the user within the realm he/she already knows.

2. The control provides almost the same methods and properties as the former Microsoft Common Dialogs control thus making applications porting easier.

Any other implementation we may provide in future will be alternative choice, but not a replacement for this control (because of the above reasons).

3. Common Dialog Reference

Through the NSBComDlg object you can show certain system defined common dialog boxes, such as open/save file, color selection and font selection. The same instance of the object can be used to show each of these dialogs at one time or another - it is not necessary to create separate instances for each dialog type. Of course if the developer prefers separate object instance for each dialog he/she can create separate objects and use them as necessary.

Because the same object shows all the dialog boxes its properties have effect on certain dialog boxes only. For example the FileName does not affect the color and font selection dialog boxes, on the other hand the Color property has effect on both color and font selection dialog boxes because they both enable the user to specify a color. Thus, the fact that you use single object for all the dialogs does not mean that their settings will mix up. On the contrary it is even possible to share a few common settings and help the user a bit.

When created the object is passive. A dialog is shown only when you call one of the ShowXXXX methods:
ShowOpen - to show the file open dialog
ShowSave - to show the file save dialog
ShowColor - to show the color selection dialog
ShowFont - to show the font selection dialog.

When called the methods does not return until the dialog box is closed by the user either by clicking the OK/Open/Save or the Cancel button.

Members reference

Name	Syntax	Description
FileName	object.FileName = value variable = object.FileName	String. Specifies the file name for the file open/save dialog boxes. For single selection (default) file open and save dialogs it contains the full path name of the file after the dialog is closed. Before calling the ShowOpen/ShowSave you can set this property thus initializing the dialog with a selection that the user can simply confirm. The path of the file name also specifies the initial directory in which the dialog will open. When the user makes a selection and closes the dialog the property contains the user selection Alternatively you can use the InitDir property to specify an initial directory in which the open/save dialog will open - you are free to use any of the both techniques. For multi-selection file open dialog boxes (see also Flags.MultiSelect) you can set the property the same way as in the previous case before calling ShowOpen, but after the user selects one or more files and the method returns the property will contain the list of the selected files separated with the \| character. The first entry will be the path of the directory in which the files are and each of the next entries specifies a file name without a path. For example you may have this value: C:\mypath\|file1.txt\|file2.txt In case of multi-select file open you can use instead the more convenient FileNames collection to read the user selection. See also Pocket PC notes
DialogTitle	object.DialogTitle = value variable = object.DialogTitle	String. Puts/Gets the string displayed in the dialog title of the file open/save dialog boxes. Has no effect over the other dialogs. When empty the system default title is displayed (usually Open file/Save file).
Filter	object.Filter = value variable = object.Filter	String. Puts/Gets the list of the file filters. The value must be formed as pairs name\|filter. For example you can set this filter: Text files\|.txt;.text\|HTML files\|.htm;html\|All files\|. which provides 3 different filters which will be displayed in the open/save file dialog box. The default value is "All Files\|.". Note that on Pocket PC devices you must have a valid filter in order the dialog to do any useful work. Without a filter on Pocket PC the dialog will stay empty enabling the user only to click cancel. This is because of the specific behavior of the Pocket PC implementation which searches a number of directories some of which may be on slow flash memory cards. The default filter (.) guarantees that the dialog will work fine with the default settings, but it is recommended to set more specific filters in order to speed up the search that is performed each time an open/save dialog is displayed on a Pocket PC device. See also the FilterIndex property.
DefaultExt	object.DefaultExt = value variable = object.DefaultExt	String. Puts/Gets the default extension that is assigned to the file name entered by the user if he/she fails to specify an extension explicitly. Usually the more complex applications determine one of many possible file extensions over the file type/format. For example the Filter and the FilterIndex properties can be used to enable the user to select a file format for a picture. Depending on the user selection the application can decide what kind of file to save and no single file extension would be of any use for the application. However, most applications do not need/support multiple file formats and a default extension can save a few lines of code that would be needed otherwise to ensure that the file has a correct name.
InitDir	object.InitDir = value variable = object.InitDir	String. Enables you to specify the initial directory in which file open/save dialog will open. Usually this property is not used. The full path and a file name you can set in the FileName property will give the dialog enough information to determine the initial directory with the additional benefit that you can both specify a default (or for example previous) file name and the directory in a single string which is also used in the file open/save operations in your application. Still sometimes it may be convenient to specify the initial directory separately - in such case you can use this property. See also Pocket PC notes
Color	object.Color = value variable = object.Color	RGB color value as long integer. Puts/Gets the initial color or the selected color. Affects the color selection dialog (ShowColor) and the font selection dialog box (ShowFont). Color dialog - if you set it before calling ShowColor it will set the initial color in the color selection dialog if the Flags.RGBInit is set to true. After the user selects a color it contains the selected color. Font dialog - The dialog enables color selection id the Flags.Effects is set to true. Otherwise the property has no effect. On return the user selection is contained. Before ShowFont you can specify initial color.
Flags	Set of = object.Flags object.Flags.Value = some_flags object.Flags = some_flags object.Flags.<flag_property> = True \| False variable = object.Flags.<flag_property>	Object. Enables you to specify or query certain features of the dialog boxes. All the features are flags that enable/disable something or reflect some details about the user selection. The object has a set of Boolean properties that allow you to set/get each flag. See the Flags object's reference. This object has also a default property (named Value) that allows advanced users to put/get flags by combining them with bit-wise OR. Thus you can refer to the Flags in a way similar to a long integer property if you prefer to specify the features this way. Furthermore this allows you to set/get flags not explicitly supported by the object as separate properties. This may come handy in newer OS versions where you can access new OS features with a version of the object compiled for an older OS version. We strongly recommend you to use the Boolean properties exposed by the object instead - they hide the potentially problematic features. Consult MSDN for more information.
FontName		String. Puts/gets the font face name. Affects the Font dialog only (ShowFont). By setting this property before calling ShowFont you define the initial face name displayed by the dialog. After the user makes a selection and the ShowFont returns it contains the font face name selected by the user.
FontBold		Boolean. Specifies if the font is Bold. Affects font dialog only (ShowFont). Before calling ShowFont it specifies the initial value, after the user makes a selection it contains the user selection.
FontItalic		Boolean. Specifies if the font is Italic. Affects font dialog only (ShowFont). Before calling ShowFont it specifies the initial value, after the user makes a selection it contains the user selection.
FontStrikeThru		Boolean. Specifies if the font is striked out. Affects font dialog only (ShowFont). Before calling ShowFont it specifies the initial value, after the user makes a selection it contains the user selection.
FontUnderLine		Boolean. Specifies if the font is underlined. Affects font dialog only (ShowFont). Before calling ShowFont it specifies the initial value, after the user makes a selection it contains the user selection.
Min	object.Min = value variable = object.Min	Long integer. Specify the minimal and the maximal font point size the font dialog will enable the user to select. Has effect only if Flags.LimitSize is true. By default the dialog restricts the font size from 8 to 72 points. You can change this limit using these properties and the Flags.LimitSize.
Max	object.Min = value variable = object.Min
CancelError	object.CancelError = value variable = object.CancelError	Boolean. Default is false. If set to true the ShowXXXX methods will cause "Action cancelled" error if the user cancels the dialog. Otherwise they return false. If you prefer On Error Resume Next techniques instead of If.. Then checks set it to True.
FilterIndex	object.FilterIndex = value variable = object.FilterIndex	Long integer. Works together with the Filter property. Before calling ShowOpen or ShowSave it enables you to specify the initial filter index shown in the dialog. After the user makes a selection it reflects the filter selected by the user. This is most often used to allow the user select one from many file formats/types. Checking the index provides a very simple and convenient way to determine the user selected file type/format and the file location in a single step. The index is 1-based.
FontSize	object.FontSize = value variable = object.FontSize	Double. Puts/Gets the fonts size. Affects the Font dialog only. On init it specifies the initial font size, after ShowFont it specifies the user selection.
FileTitle	object.FileTitle = value variable = object.FileTitle	String. Specifies the file name only. Currently (in version 1.0) this depends on the system implementation of the file open/save dialog. Most platforms fill this field only when ShowOpen returns. The field contains the file name only without the full path. The applications should not count on any other usage of this property no matter if a test shows that it is filled under other circumstances - this may be specific to the OS version you use.
Charset	object.Charset = value variable = object.Charset	Long integer. Specifies the charset for the font. Applies to the font dialog only (ShowFont). Before calling ShowFont specifies the initial charset, after ShowFont contains the user selection. Here are the well-known charset constants: ANSI_CHARSET = 0 DEFAULT_CHARSET = 1 ' Matches the system settings SYMBOL_CHARSET = 2 ' for symbol fonts only SHIFTJIS_CHARSET = 128 HANGEUL_CHARSET = 129 HANGUL_CHARSET = 129 GB2312_CHARSET = 134 CHINESEBIG5_CHARSET = 136 OEM_CHARSET = 255 JOHAB_CHARSET = 130 HEBREW_CHARSET = 177 ARABIC_CHARSET = 178 GREEK_CHARSET = 161 TURKISH_CHARSET = 162 VIETNAMESE_CHARSET = 163 THAI_CHARSET = 222 EASTEUROPE_CHARSET = 238 RUSSIAN_CHARSET = 204 MAC_CHARSET =77 BALTIC_CHARSET = 186
Action	object.Action = value variable = object.Action	String/Number. The values are the same as the dialog type in the Reset method. Setting the property does not reset the object, instead it only declares that the application is going to use it for the specified dialog type. This has the following effect: When you set the dialog flags as value (See Flags) only the flags for the specified dialog type are affected. Thus for instance: object.Flags.Value = OFN_ALLOWMULTISELECT Or _ OFN_HIDEREADONLY will apply only to the file dialog flags, if you invoke another dialog it will show with whatever flags has been set for it before you have changed the Action property. This does not affect the Boolean flag properties of the Flags object - they are all dialog specific and the dialog type for which they apply is known implicitly. The Action property is actually useful only when you want to both reuse the object for different dialogs and set flags directly - as a long integer value composed with Or operators and not using the Flags object's Boolean properties.
CustomColors	object.CustomColors(I) = value variable = object.CustomColors(I)	Indexed property, color values. The index must be between 0 and 15. This property allows you put/get the 16 custom colors the Color dialog (ShowColor) presents to the user. On Pocket PC the user is not allowed to change/set them, on most of the other platforms the user can save his/her selections there. If you want to preserve the custom colors you should save all the 16 values.
FileNames	variable = object.FileNames(I) For Each I In object.FileNames namesCount = object.FileNames.Count	Collection. Can be used only with file open dialog (ShowOpen) when the dialog is configured to allow the user to select multiple files. In this case it is easier to use this collection instead of splitting the value of the FileName property in order to get the file names. The collection contains the file names only (without path). The path you can obtain from the InitDir property. See also Flags.MultiSelect. On Pocket PC multiselect is not supported.
HelpCommand	object.HelpCommand = cmd cmd = object.HelpCommand	Long Integer. Specifies the help command to be executed when ShowHelp is invoked. The supported commands are: &H01 - Context help. Shows help for the specified context. On Windows CE the topic specified by the *HelpContext* property is shown. On desktop (see &H08) displays the topic specified by the HelpContext property (for help files created with Help Workshop prior to 4.0). &H08 - Context popup. Shows help for the specified context in the HelpContext property in a pop-up window. (desktop only). &H03 - Help index/contents. Shows the main page of the help file. &H09 - Force file. Forces the help file specified by the *HelpFile* property to be shown. (desktop only) &H04 - Help on help. Displays the help about the Windows help system. (desktop only). &H101 - Keyword. Displays help for the keyword specified by the *HelpKey* property. (desktop only). &H105 - Partial keyword. Displays help topic by partially specified keyword in the *HelpKey* property. (desktop only). &H02 - Quit. Closes the help. (desktop only)
HelpKey	object.HelpKey = s s = object.HelpKey	String. Has no effect on Windows CE. Specifies the help keyword (pr partial keyword) for HelpCommand &H101 and &H105.
HelpContext	object.HelpContext = ctx ctx = object.HelpContext	On desktop integer (the ID of the topic) should be specified, on Windows CE a string (the name of the topic) must be specified. See HelpCommand &H01 and &H08
HelpFile	object.HelpFile = f f = object.HelpFile	String. The path to the help file to be displayed. Note that the safest way is to specify the full path to the file.
ShowOpen	object.ShowOpen	Shows the file open dialog. The method does not return until the user makes a selection or presses cancel. When cancelled the method returns False, otherwise it returns True. If the CancelError property is set to True instead of returning False the method generates an error. See also Pocket PC notes.
ShowSave	object.ShowSave	Shows the file save dialog. The method does not return until the user makes a selection or presses cancel. When cancelled the method returns False, otherwise it returns True. If the CancelError property is set to True instead of returning False the method generates an error. See also Pocket PC notes.
ShowColor	object.ShowColor	Shows the color selection dialog. The method does not return until the user makes a selection or presses cancel. When cancelled the method returns False, otherwise it returns True. If the CancelError property is set to True instead of returning False the method generates an error.
ShowFont	object.ShowFont	Shows the font selection dialog. The method does not return until the user makes a selection or presses cancel. When cancelled the method returns False, otherwise it returns True. If the CancelError property is set to True instead of returning False the method generates an error.
ShowHelp	object.ShowHelp	Invokes the help system (WinHelp on desktop, PegHelp on Windows CE). The actual operation that will be performed depends on the current values of the *HelpFile, HelpCommand, HelpContext* and *HelpKey* properties. See their descriptions for details. Note that the help systems on the desktop and Windows CE devices are very different. Even if you use the very basic help features there will be differences in the desktop and the Windows CE versions of your application.
Reset	object.Reset dlgType	Resets/Initializes the object to the best suitable state for the dialog type specified. dlgType can be integer or a string containing a keyword recognized by the object - use whatever you prefer. The values are: 1 or "File" - File open/save dialog 2 or "Color" - Choose color dialog 3 or "Font" - Font selection dialog. The method does not change any of the properties and flags that are not used by the specified dialog type. However, any call to this method resets the CancelError to its default value - False. The method also sets the value of the Action property to the dlgType specified (see Action for more details). If unsure about the state of the object you can always call this method before starting to fill the properties of the object and showing a dialog box. This may be especially useful when you are using the same object to show the same dialog type for different purposes. A good example is using open file for import and typical file open operation. A property value set for one of the operations may cause the dialog to look or behave strangely when you show it for the other operation if you forget to change it. Resetting the object will help you identify such omissions earlier. Note that on Pocket PC the default initialization for file save dialog is inappropriate - see Pocket PC notes for more details.
IsPocketPC	variable = object.IsPocketPC	Boolean. Returns True if the device is a Pocket PC (any version). See Pocket PC notes

4. Common Dialog Flags

This object is accessible through the NSComDlg.Flags property. Typically you should use it for example like this:

comdlg_object.Flags.MultiSelect = True
' Which configures the file dialog to allow multi-selection.

The object provides a set of Boolean properties each controlling a single flag (option) for a certain dialog type. By using them you do not need to combine flag values or import/define constants for these flags (like the MS Common Dialogs control).

Boolean Properties reference

Each of the properties listed below is Boolean and read/write. Each of them corresponds to a single flag (option) for a given dialog type. The properties are listed by the dialog type they affect. Note that most flags specify options about the dialog boxes, but there are a few that indicate specifics of the user selection after the dialog closes (marked in Blue) .

Name	Description
Open/Save file dialog
MultiSelect	Default: False If set to True the open file dialog allows multiple selection and returns the list of the selected files - see ComDlg.FileName and ComDlg.FileNames. Not supported on Pocket PC and most Windows CE devices.
CreatePrompt	For file save dialog displays a prompt if the user enters a non-existent file name.
FileMustExist	Allows the user to select only existing files.
HelpButton	Displays the help button on the dialog. No effect on Pocket PC.
HideReadOnly	Hides the Read Only check box. No effect on Pocket PC.
NoChangeDir	Restores the current directory to its original value if the user changed the directory while searching for files. Not supported on Windows CE/Pocket PC.
NoDereferenceLinks	Allow selection of the shortcut files themselves instead of the files to which they point to.
NoReadOnlyReturn	After ShowOpen indicates that Read only checkbox has not been checked by the user. Not supported on Windows CE/Pocket PC.
NoValidate	Perform no validation of the entered file name. If set to True you should use only the FileName property after the ShowOpen/ShowSave returns. The returned file name may contain invalid characters, for this flag allows this. No effect on Windows CE (the names are always checked)
OverwritePrompt	ShowSave will show message box asking the user if he/she really wants to overwrite the selected file if the user chooses/enters a name of an existing file.
PathMustExist	If the user types path and a file name in the dialog and the path does not exist a warning message is shown.
ShareAware	Ignore sharing violation. If this flag is not set the user is not allowed to select a file which is locked. Not supported on Windows CE/Pocket PC.
ReadOnly	Controls the Read only check box. After return indicates the stat in which it has been left by the user. Not supported on Windows CE/Pocket PC.
ExtensionDifferent	If the DefaultExt is not empty this flag indicates after ShowSave that the user has typed file extension different from the extension specified by that property.
Color dialog
FullOpen	Causes the dialog to open with the advanced options shown (free color selection). Does not have effect on Pocket PC 2003 and earlier.
PreventFullOpen	Disables the button that opens the advanced options. No effect on Pocket PC 2003 and earlier.
RGBInit	Use the Color property to initialize the dialog. If the flag is not set the dialog is not initialized from the current value of the Color property.
Font dialog
ANSIOnly	Show ANSI fonts only (obsolete - included for backward compatibility).
Effects	Show the controls for effects selection (strike thru, color etc.)
FixedPitchOnly	Show fixed pitch fonts only.
ForceFontExist	The font must exist. The user is not allowed to type a face name of non-existent font. If not set the closest substitution is selected by the system.
LimitSize	If set to True the dialog will show only the font sizes between the values of the Min and Max properties.
NoFaceSel	No initial face selection is shown in the dialog (the FontName can still be valid and non-empty, but it is not initially selected when the dialog opens).
NoSimulations	Forbids font simulations to be made by the GDI.
NoSizeSel	Hide the size selection controls on the dialog.
NoStyleSel	Hide the style selection controls on the dialog.
NoVectorFonts	Show no vector fonts in the list.
ScalableOnly	List only fonts that are scalable.
ScreenFonts	List screen fonts.
TTOnly	List true type fonts only.
WYSIWYG	List only WYSIWYG fonts (these are in first place fonts available for the both screen and the printer).
PrinterFonts	List printer fonts.

Advanced usage

If you prefer to use combined flag constants you can assign all the flags composed this way through the Value property of the object. The object has also two helper methods that can be used to bring it in well-known state. They are also intended for this kind of usage. If you want to use the Boolean properties there is no need to ever use the Value property or the Methods in the following table.

Name	Syntax	Description
Value	comdlg_object.Flags.Value = value comdlg_object.Flags = value variable = comdlg_object.Flags.Value	Long integer, default property. Thanks to the fact that this is default property flags combined in long integer value can be assigned syntactically just like with the Microsoft Common Dialogs ActiveX. The property puts/gets the flags for the dialog type specified by the NSComDlg.Action property. If you want to set the flags for all the dialogs at once (very unlikely) set the Action to 0. Note that due to the differences between the platforms and the fact that Microsoft no longer supports their common dialog ActiveX the flags that have worked on earlier OS versions may cause different behavior on new OS versions. To be on the safe side it is recommended to carefully check MSDN or use the properties listed above.
SetDefaults	comdlg_object.Flags.SetDefaults	Sets the flags for all the dialog types to their default values.
Clear	comdlg_object.Flags.Clear	Clears all the flags for all the dialog types. Use with caution! In many cases the common dialogs require at least one or two flags in order to do something useful - make sure you are setting new flags after calling the Clear method.

General notes for developers who set flags directly (e.g. comdlg_object.Flags = &H<someflag> Or &H<someflag2> ...). Note that the Font and the Color dialogs do not initialize from the specified data unless a special flag is specified. To avoid confusion the control automatically adds this flag when flags are assigned directly, thus relieving you from the need to specify it explicitly.

5. Help Files and PegHelp Usage Example

This example shows both how to construct a help for your application and how to invoke it. The files are in \Program Files\NSBasic\CE\Samples\NSBComDlg.PegHelp.zip.

1. Creating the Help File

Help consists of one or more HTML files. The files are generally regular HTML 3.2 files, but there are some tags that add functionality and some specifics:

```
<META HTTP-EQUIV="Htm-Help" CONTENT="NSBHelpExample.htm#Main_Contents">
```
This tag defines an entry in the main system contents menu. The system is responsible for parsing the installed help files and check for this META tag. To make the sytem parse the file, see "Link creation" below.
```
<KEYWORD VALUE="nsbkeyword1;nsbkeyword2" TITLE="Topic 1" 
	HREF="NSBHelpExample.htm#topic1">
```
Put as many as you want such tags thus connecting keywords with specific topics in the same HTML file. This will enable the Search function in the CE Help to find them
```
<BR>
```
Put this tag after the heading (immediately after the BODY tag) and after each topic in your help files. This enables the PegHelp show separate topics from the file and enables you to put all or at least more topics in single file and then show them as if they are in spearate files. If you have any experience in WML (WAP) this is very similar to the deck in WML - i.e. the tag above separates "cards" in a "deck". So, Each topic in your help file is between  tags
```
<A NAME="Main_Contents"></A>
```
Assign this bookmark name to the topic that contains the general contents of all your help files.
```
<A NAME="topic1"></A>
```
Put a bookmark with the topic's bookmark name nearly the beginning of each topic
```
<A HREF="NSBHelpExample.htm#Main_Contents">Contents</A><BR>
```
When using links use the file name and the bookmark name of the topic to which the link leads.

2. Creating the Link

The link is actually a text file with a full path to your help file. The only special thing is that you must specify the number of the characters in the path specified immediately before it - like this:

27#\Windows\NSBHelpExample.htm

To make this link work copy it in \Windows\Help. The link file must have a .lnk extension. To avoid problems the file in the example is with .lnk.txt extension - remove the .txt part after copying to the device's \Windows\Help

3. Running the example

Copy the NSBHelpExample.htm in the \Windows directory
Copy the NSBasic PegHelp Usage Example.lnk.txt to \Windows\Help and remove the .txt extension fom it.
Compile and run (or make the exe and copy it whereever you want on the device) the example.

The 3 first buttons show topics following the Microsoft's guidelines The 4-th button "Open without a bookmark" demonstrates what would happen if you use link without a bookmark - everything is shown and this may not be what you actually want. Still in small help systems this may be useful - just do not forget to design the file(s) in a manner that will display nice in the both ways - single topic and everything at once.

4. Notes on invoking help

Notice the HelpCommand property. When it is set to 01 (Which is default) you need to specify a topic's bookmark name in the HelpContext property. Failing to do so will cause error (cannot find the help file) when you use the ShowHelp method.

If you want to go by without bookmarks you must set the HelpCommand to something else. It is recommended to use 0 in order to avoid any future problems if the future versions of Windows CE begin to support more different commands.

This behavior (defaulting to 01 - which requires a bookmark) have been choosen according to the guidelines in MSDN. It is intended to stimulate a kind of usage in which the information is displayed in relatively small topics and not as huge help files through which the user would need to scroll in order to find what he/she looks for.

6. Version History

Version 1.0.1

- Help support added (See ShowHelp)
- Fixed a problem with MultiSelect open file dialog box on Windows 2000. Symptoms: Windows 2000 gets confused if the buffer for the files list is too big and only one file is selected in a multi-select file open dialog box. Fix: The buffer size has been lowered.
Known problems:
On WM5 the font dialog may appear incorrectly in landscape mode. This is a problem in Windows Mobile OS - the system's template for the dialog seems to be from the handheld pc and does not fit the size of the screen of the Pocket PC devices.

Version 1.0 - the initial version