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