Common dialogs overview

Conceptually ComDlg ActiveX is implemented in manner very close to the Microsoft's common dialog ActiveX you may already know. The resemblance makes it almost fully compatible with existing code that uses that control, but still, the similarities are only superficial. NSBasic ComDlg control provides a number of features that allow the developer to write better readable code, easily access certain 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 object which 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 ...

Set the initial values - initialize the dialog.
NSComDlg1.InitDir = "C:\mydir"
NSComDlg1.DialogTitle = "Select SQL queries"
NSComDlg1.Filter = "SQL files|*.sql|Text files|*.txt|All files|*.*"
... more settings - as needed ...

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.

* - 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.