Tech Note 07: DialogX 1.0

A control that lets you build powerful dialog boxes.

September 11, 2003

© NSB Corporation. All rights reserved.

NS Basic is (c) NS Basic Corporation
Windows CE is (c) Microsoft Corporation

DialogX is an ActiveX control designed to allow NS Basic/CE users to create and use custom dialog boxes.

DialogX creates dialogs that are modal and passive. The dialogs are modal because program execution halts, and waits for the user to close the dialog. The dialogs are passive because the program is halted while the dialog is open, and the dialog cannot be changed by the program until it is closed.

DialogX syntax is very similar to NSBasic/CE. Objects are added by calling the AddObject method. The list of usable objects is similar to list of intrinsic objects in NSBasic/CE:

with additions:

Many familiar object properties can be set by DialogX methods with equivalent names. DialogX also supports some new properties. These objects can be used to create powerful, flexible dialog content that will greatly improve your program's user interface. Using DialogX is a five step process:

  1. Creation
  2. Add and configure objects
  3. Set default values (if necessary)
  4. Open the dialog with DoModal
  5. Retrieve values (if necessary)

NOTE: There is also an InputBox method of DialogX that simulates the INPUTBOX Function of NSBasic/CE. The dialog that is opened fits properly on a Palm-Size PC screen!!

All dimensions and coordinates are in Dialog Template Units (DTUs). DTUs are relative to the DialogX's selected font. A smaller font size will create a smaller DialogX with the same values of Width and Height.

Dialog Base Units (DBUs) are the average width and height, in pixels, of the characters in the dialog's font. Each horizontal DBU is equal to 4 horizontal DTUs and each vertical DBU is equal to 8 vertical DTUs.


Connect your Windows CE device to your desktop using ActiveSync. On the desktop, run the program DialogX.exe. Follow the instructions on the screen to complete the installation.

If you have NS Basic/CE 3.01 or later, DialogX is installed along with NS Basic/CE itself. You may need to register the control if your programs cannot find it. Use this NS Basic/CE statement:
shellexecute "open","regsvrce.exe","dialogx.ocx"

Object Creation

AddObject "NSBasic.DialogX.1", "Name"

Starting with Rev 3.01, you can simply do
AddObject "DialogX", "Name"


These samples are installed with the rest of the NS Basic samples.
CaptionCloseTRUE|FALSEAdds close box "X" to DialogX.
CaptionOKTRUE|FALSEAdds OK button "OK" to DialogX.
FontNameText (Default: System Font)Sets font name for font used in DialogX items.
FontSizeNumber (Default: 9)Sets font size for font used in DialogX items.
HeightNumber (Default: 100)Sets DialogX height (in DTU's).
HelpFileFileName (Text) Displays DialogX with "?" in frame, which opens Help with the given file
If a fully qualified paths is not used, the file will be opened from \Windows.
SystemSoundNumber Play one of the standard system sounds when the DialogX is opened:
TagExpression This property is not used by DialogX. Any valid expression can be used to set this property.
TitleTextSets the title displayed in DialogX.
VersionMajorRead-OnlyReturns a numeric value.
VersionMinorRead-OnlyReturns a numeric value.
WidthNumber (Default: 160)Sets DialogX width (in DTU's).
NameParametersDescription/Return Value(s)
AddItemObjectName (Text), Item (Text) Adds list items to ListBox and ComboBox objects.
AddObjectObjectType (Text), ObjectName (Text), Left, Top, Width, Height Adds an object to the DialogX. Dimensions are in DBU's. Valid types:
CommandButton, TextBox, Label, ListBox, ComboBox, OptionButton, CheckBox, GroupBox, Bitmap, SpinCtrl, Slider
Note: A SpinCtrl must be added directly after the TextBox it will control.
ClearListObjectName (Text) Removes all text items from ListBox and ComboBox objects.
DoModal  Displays the DialogX. Returns Number 0 = Cancel, 1 = OK, 2... = User Defined
*** Note "Get" methods only return values after the DialogX has been opened and a button with a return value not equal to 0 has been pressed
GetCaptionObjectName (Text) Returns the text from a DialogX item.
GetIndexObjectName (Text)Returns the selected index for ListBox and ComboBox. Returns a Number
GetValueObjectName (Text) Returns the selected index for ListBox and ComboBox, the check state from OptionButton and CheckBox, or the position from SpinCtrl and Slider. When working with OptionButton objects, use GetValue only on the first button in a group, after the SetGroup method has been called.
InputBoxPrompt (Text), Title (Text), Default (Text) Similar to the default INPUTBOX from NSBasic, this creates a dialog that will fit the screen of most Palm-Size PCs. The string from the text box is returned if the user taps "OK" or presses the enter key, otherwise an empty string ("") is returned. All 3 arguments are required.
Reset Removes all objects and reinitializes DialogX.
SetAlignmentObjectName (Text), 0|1|2 Sets text alignment in TextBox and Label, sets button arrangement in OptionButton and CheckBox, sets alignment of SpinCtrl.
"Center" Not used in OptionButton, CheckBox, or SpinCtrl
SetAutoTicksObjectName (Text), TRUE|FALSE Automatically draws interval ticks on Slider objects.
See also, SetTickFrequency.
SetBitmapObjectName (Text), Filename (*.bmp) Loads a bitmap from a fully qualified pathname to a Bitmap file.
SetCaptionObjectName (Text), Caption (Text) Sets the text of a DialogX item.
SetCaseObjectName (Text), 0|1|2 Sets TextBox objects to automatically convert case.
0Mixed case
SetDirectionObjectName (Text), 0|1|2 Sets the direction the thumb control points in a Slider object.
SetEnabledObjectName (Text), TRUE|FALSE Enables or disables (grays out) an object.
SetGroupObjectName (Text), TRUE|FALSE Use this property to begin a group of mutually exclusive OptionButtons. Use SetGroup on the first OptionButton of group only! Once this is set, the value of the group can be set or read from the first OptionButton with the SetValue() and GetValue() methods.
SetHBitmapObjectName (Text), HBITMAP A Handle to a BITMAP that is valid when the DialogX is opened and is displayed in Bitmap objects.
SetIndexObjectName (Text), Number Sets the originally selected item in a ListBox or ComboBox. The list is 0-based, with 0 being the first item, and -1 indicating no selection.
SetIntegralHeightObjectName (Text), TRUE|FALSE Use to modify ListBox or ComboBox objects to hide or show partial items.
SetMax/SetMinObjectName (Text), Number Sets the range for SpinCtrl and Slider objects. Default 0-100.
SetMaxLengthObjectName (Text), Number Sets the total number of characters that can be entered in a TextBox or editable ComboBox.
SetMultilineObjectName (Text), TRUE|FALSE Set the multiline property to TRUE, to allow TextBox objects to accept carriage returns and multiple lines of text.
SetNumbersOnlyObjectName (Text), TRUE|FALSE Sets TextBox objects to filter non-numeric input.
SetPasswordObjectName (Text), TRUE|FALSE Modifies TextBox items to display password character (*).
SetReturnValueObjectName (Text), Number This sets the value DoModal returns when an object is Clicked/Double Clicked/Selected.
0 = Cancel, 1 = OK, 2... = User Defined.
Set Return Value to -1 to restore default behavior.
SetScrollbarsObjectName (Text), 0|1|2|3 This will add or remove scrollbars from TextBox or ListBox objects.
3Horizontal & Vertical
SetShowTicksObjectName (Text), TRUE|FALSE Set to show the limit ticks for Slider objects.
SetSortedObjectName (Text), TRUE|FALSE Use to automatically sort ListBox and ComboBox list items alphabetically.
SetStyleObjectName (Text), 0|2 Use to set ComboBox read-only.
0Allow Input
SetTabStopObjectName (Text), TRUE|FALSE This adds or removes an object from the chain of tabable items.
SetTickFrequencyObjectName (Text), Number Set the frequency for interval ticks on Slider objects. Default 1.
SetValueObjectName (Text), TRUE|FALSE|Number Sets the check state of OptionButton and CheckBox, sets the position of SpinCtrl and Slider. When working with OptionButton objects, use SetValue only on the first button in a group, after the SetGroup method has been called.
SetVerticalObjectName (Text), TRUE|FALSE Sets the orientation for SpinCtrl and Slider objects.
SpinCtrl default TRUE.
Slider default determined by slider object shape.
SetVisibleObjectName (Text), TRUE|FALSE Shows or hides a DialogX item.
Version Returns a text value.

Change Log

10/12/99: SetScrollbars corrected. 02/13/00: Additional changes to Scrollbar logic