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
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
ComDlg control provides a number of features that allow the
developer to write better readable code, easily access additional
features and avoid mistakes.
The object can be created explicitly using this code:
Create example: AddObject "NSBasic.ComDlg",
See also: ComDlgFlags
objectwhich is non-creatable. It is returned by the
ComDlg.Flags property and provides both low-level and high-level
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.
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
See more details on the ComDlg's page.
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:
Then some flags are set to configure the dialog appearance and
NSComDlg1.Flags.MultiSelect = True ' We will accept
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
... more settings - as needed ...
Show the dialog
If Not NSComDlg1.ShowOpen Then
' Action is cancelled - usually this means
skip the operation
' 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
NSComDlg1.InitDir & "\" & sqlFile
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.
||All the dialogs are available
to the full extent of their features.
||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
|Pocket PC (incl. 2002, 2003
||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
* - 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
** - 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.
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.
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.