MGCEWin32 - Windows CE Custom Control Objects
Written by Mark Gamber, September 1999

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

====================================================================================

MGCEWin32 provides five separate controls for Windows CE applications capable of
making use of COM oriented controls such as NS Basic. Included in this package are:

Tray Image control
Registry control
Win32 API control
Timer control
Remote Access (RAS) Control

Because the number of functions available from this module is relatively large, the
documentation has been broken into two parts. This file deals with the Tray Image
control, Registry control and Timer control documentation.

====================================================================================

RAS (Remote Access) Control

The RAS Control provides access to the remote access API, allowing programs capable
of using the object to dial a remote network, hang up a connection, set logon
parameters and maintain connections. The RAS control supports the following
properties, methods and events:


Object Creation:
	AddObject "MGCEWin32.RAS", "name"



Properties:

*** AllConnections
	Retrieves an array of open connections. If there are no open connections,
an empty array is returned. Each item in the array is a 32 bit number which
identifies a connection.

	a = RAS.AllConnections


*** AllEntries
	Retrieves an array of remote access connection names. If there are no
names available, an empty array is returned. Each array entry is a string which
identifies a connection.

	aNames = RAS.AllEntries


*** ConnectionStatus
	Retrieve the current state of a connection as a bit field. THe connection
is identified by a 32 bit value passed to the property. Possible status bits include:


	status = RAS.ConnectionStatus( connID )


*** Domain
	Set and retrieve a domain name to apply to a remote connection.

	sDomain = RAS.Domain
	RAS.Domain = "DEVGROUP"


*** EntryName
	Set and retrieve the name of a connection to dial.

	RAS.EntryName = "WrkServer"
	sName = RAS.EntryName


*** Password
	Set and retrieve a password used to log into a connection.

	RAS.Password = "tritium"
	sPwd = RAS.Password


*** PhoneNumber
	Set and retrieve a phone number to dial in order to establish a connection.
If this property is used, the EntryName property must be cleared ("") and vice
versa.

	RAS.PhoneNumber = "555-1212"
	sNum = RAS.PhoneNumber


*** UserName
	Set and retrieve a user name used to log into a connection.

	RAS.UserName = "howard"
	sName = RAS.UserName


*** Validate
	Determine if a connection name is valid. An error occurs is an invalid or
existing entry name is passed to this property.

	iValid = RAS.Validate( "New Entry" )


*** Version
	Retrieve the version of the RAS object.

	v = RAS.Version



Methods:

*** Clear
	Removes all data from the Domain, EntryName, Password, PhoneNumber, UserName
and Password properties.

	RAS.Clear


*** Connect
	This method attempts to connect to a server with data applied using the
Domain, EntryName, Password, PhoneNumber, UserName and Password properties. If a
valid connection is established, a 32 bit connection identifier is returned by the
method. This value may be later used to disconnect.

	iConnID = RAS.Connect


*** DeleteEntry
	Remove an entry from the device phone book. The entry is identified by
name.

	RAS.DeleteEntry "New Entry"


*** Disconnect
	Hang up a current connection, the connection identified by a 32 bit value
assigned by the Connect method or the AllConnections property.

	RAS.Disconnect iConnID


*** GetDialParams
	The properties associated with a remote access entry may be obtained by
specifying the name using the EntryName property and calling the GetDialParams
method. The Domain, Password, PhoneNumber and UserName properties are updated
with the entry data.

	RAS.EntryName = "Work Server"
	RAS.GetDialParams


*** RenameEntry
	Rename a remote access entry name.

	RAS.RenameEntry "OldName", "New Name"


*** SetDialParams
	After setting the EntryName, Domain, Password, PhoneNumber and UserName
properties, call SetDialParams to save those properties.

	RAS.SetDialParams



Events:
	The RAS object does not support events.

====================================================================================

Tray Image Control

The Tray Image control provides access to the system tray from Basic and allows you
to add images to, removes images from and modify existing images on the system tray.
The Tray Image control supports the following properties, methods and events:


Object Creation:
	AddObject "MGCEWin32.Tray", "Name", 0, 0, 0, 0



Properties:

*** Tag
	Set and retrieve a variant value which may be obtained at any point.

	Tray.Tag = "Num1"


*** Value
	The Value property is what actually adds, removes and modifies tray images.
The image to display is identified by it's position in the control's image list. To
remove an image from the tray, use zero. To add or modify an image, specify an image
number. If an image is not displayed in the tray, one is added.

	Tray.Value = 1
	iCurImage = Tray.Value



Methods:

*** AddImage
	The Tray object maintains a list of images, each image identified by the
order in which it was added. The first image added using the AddImage method is
image one and so on. Only valid Windows bitmaps are accepted by the tray object
and 16 color images are recommended.

	Tray.AddImage "\smimg1.bmp"


*** RemoveImage
	You may remove images from the image list at any time by specifying the
number of the image to remove, starting with one for the first image added to the
object.

	Tray.RemoveImage 1



Events:

*** Click
	When a tray image created by the object is tapped, the Click event is
fired, passing along the number of the image currently displayed. A basic event
handler can catch and make use of this event.

	sub Tray_Click( image )
		MsgBox "You tapped image #" & CStr( image )
	end sub

====================================================================================

Registry Control

The Registry control provides a very flexible way to access the Windows CE registry
from Basic. The registry control DOES NOT attempt to protect the registry from errant
programming, however, so exercise caution when modifying the registry. The Registry
Control supports the following properties, methods and events:


Object Creation:
	AddObject "MGCEWin32.Registry", "Name", 0, 0, 0, 0



Properties:

*** Key
	The Key property sets and retrieves the "base key" from which path operations
take place. There are four valid key values:
	CLASSES_ROOT:	0
	CURRENT_USER:	1
	LOCAL_MACHINE:	2
	USERS:		3

	Registry.Key = 1
	iCurKey = Registry.Key


*** Path
	Use the Path property to set and retrieve the current path into the registry.
This value is combined with the Key property to make a full path into a specified
section of the registry.

	Registry.Path = "Software\MyApp"
	sPath = Registry.Path


*** Name
	The Name property identifies a value name in the registry. If the value does
not exist when reading from the registry, an error occurs and may be trapped by using
the "on error resume next" line to prevent the error from stopping the program and
using the "Err.Number" variable to determine if an error occurred. When writing to
the registry and the value doesn't exist, it is created as a type specified by the
ValueType property.

	Registry.Name = "MyData"
	sName = Registry.Name


*** ValueType
	Set and retrieve the type of value currently being read or written from or
to the registry. Four types are supported by the registry object including:
	REG_SZ (1): Text string
	REG_BINARY (3): Binary data
	REG_DWORD (4): 32 bit numeric value
	REG_MULTI_SZ (7): An array of text strings
Various brands of Basic may or may not support single byte binary data
manipulation. To ensure that the data may be used from within Basic, Binary data
is written and read as a string of hexidecimal data. When the Key, Path and Name
properties combine to point to an existing value, that value's data type may be
obtained by reading this property.

	Registry.ValueType = 4
	ValType = Registry.ValueType


*** Value
	Set and retrieve data to and from the registry using the Value property.
You must set the Key, Path and Name properties before reading or writing from or
to the registry usng this property. Because registry data comes in many forms
(text, numeric, array and binary formats), the Value property does automatic
conversion when possible. It cannot convert any type to Binary or Array values,
not can it convert Binary or Array values to any type.

	Registry.ValueType = REG_DWORD
	Registry.Value = "32"      ' This will convert to the number 32

	Registry.ValueType = REG_SZ
	Registry.Value = 150       ' This will convert to the string "150"

	Registry.ValueType = REG_BINARY
	Registry.Value = "FFFF00FF0A0B0C0D"  ' Add a binary value

	Registry.ValueType = REG_MULTI_SZ  ' Add a string array
	a = Array( 2, 3, "Four", 5 )       ' Numbers will convert to strings
	Registry.Value = a

	a = Registry.Value		   ' When reading an array, you can
	if Registry.ValueType = REG_MULTI_SZ then ' determine the number of
		iItem = UBound( a )        ' items read by using UBound()
	end if				   '  on the array



Methods:

*** CreatePath
	The current Key and Path properties are combined to form a path into
the registry. Set these two properties and call CreatePath to create a new path.
If the path already exists, it is not modified by this method.

	Registry.Key = CURRENT_USER
	Registry.Path = "Software\Test"
	Registry.CreatePath


*** DeletePath
	Set the current Key and Path properties, then call the DeletePath
method to remove a path from the registry.

	Registry.Key = CURRENT_USER
	Registry.Path = "Software\Test"
	Registry.DeletePath


*** DeleteValue
	You may set the Key, Path and Name properties and then call the
DeleteValue method to remove a value from the registry.

	Registry.Key = CURRENT_USER
	Registry.Path = "Software\Test"
	Registry.Name = "TestVal"
	Registry.DeleteValue


*** GetPathName
	This method is used to find paths connected to a path specified by the
Key and Path properties. For example, if the "CURRENT_USER\Software\Test" path
has three paths within it, the may be found by calling this method and starting
with one, adding one to the value passed to the method each time it is called
until an error occurs.

	on error resume next
	Registry.Key = CURRENT_USER
	Registry.Path = "Software\Test"
	iNum = 1
	while Err.Number = 0
		MsgBox Registry.GetPathName( iNum )
		iNum = iNum + 1
	wend


*** GetValueName
	Similar to the GetPathName method except this method hunts for and returns
value names. The first value is found by specifying one and following values are
found by increasing the number passed to the method with each call until an error
occurs.

	on error resume next
	Registry.Key = CURRENT_USER
	Registry.Path = "Software\Test"
	iNum = 1
	while Err.Number = 0
		MsgBox Registry.GetValueName( iNum )
		iNum = iNum + 1
	wend



*** Events:
	The registry object does not support any events.



====================================================================================

Timer Control

	The Timer control is a very simple object you may use to send events to an
application on regular intervals. The Timer Control supports the following
properties, methods and events:


Object Creation:
	AddObject "MGCEWin32.Timer", "Name", 0, 0, 0, 0



Properties:

*** Interval
	The number of milliseconds to wait between events. Interval ranges from one
to 2147483647.

	Timer.Interval = 1000
	i = Timer.Interval


*** Tag
	Set and retrieve a variant value which may be obtained at any point.

	Timer.Tag = "Test"
	s = Timer.Tag



Methods:

*** Start
	Call the Start method to start the timer. If the Interval property was set
properly, the application will begin to receive events. Note that starting the timer
itself is not an event. The first event occurs after the first specified interval.

	Timer.Start


*** Stop
	The Stop method stops a running timer. If there is no running timer when
Stop is called, nothing happens.

	Timer.Stop


Events:

*** Interval
	The Interval event is triggered when the number of milliseconds specified by
the Interval property has passed. The application will receive this event until the
timer is stopped or the application is closed.

	sub Timer_Interval
		Listbox.AddItem "Interval fired"
	end sub


====================================================================================

' Demonstration of the registry functions in MGCEWin32
' Written by Mark Gamber using NS Basic

' Registry root keys. Everything else is based on these
CLASSES_ROOT = 0
CURRENT_USER = 1
LOCAL_MACHINE =2
USERS = 3

'Registry types supported by this object
REG_SZ = 1
REG_BINARY = 3
REG_DWORD = 4
REG_MULTI_SZ = 7

' ******** Create the registry object
addobject "MGCEWin32.Registry", "Registry", 0, 0, 0, 0

' ******** Create HKEY_CURRENT_USER\Software\Test path
Registry.Key = CURRENT_USER
Registry.Path = "Software\Test"
Registry.CreatePath

' ******** First, add a REG_MULTI_SZ type using an array

Registry.Name = "TestValue"      ' Use a value called TestValue
Registry.ValueType = REG_MULTI_SZ    ' Setting a multi-string
v = Array( 1, 2, "Three", 4 )               ' Set up an array of values
Registry.Value = v                            ' Add array to the registry


' ******** Now read back the array we just added
s = Registry.Value
MsgBox CStr( UBound( s ) ) & " items in array", vbOKOnly, "Array Size"
for i = 1 to UBound( s )                       ' Display each array item
   MsgBox s( i ), vbOKOnly, "Array Value " & CStr( i )
next

Registry.ValueType = REG_DWORD
Registry.Value = "10"
MsgBox Registry.Value, vbOKOnly, "DWORD Value"

' ******** New let's play around with a binary value

Registry.ValueType = REG_BINARY           '  Specify registry type as BINARY
Registry.Name = "BinValue"
Registry.Value = "FFFEFDFC00010203"      ' Give value a Hex string

s = Registry.Value                                     ' Read back binary value we just set
MsgBox s, vbOKOnly, "Binary Value"          ' Display the hex string

i = 0
on error resume next
while Err.number = 0
   MsgBox Registry.GetValueName( i ), vbOKOnly, "Created Key"
   i = i + 1
wend

Registry.DeleteValue                                  ' Delete the binary value
Registry.Name = "TestValue"                      ' Delete the original array value
Registry.DeleteValue

Registry.DeletePath                                    ' Delete the Software\Test path we added

Registry.Path = ""
i = 0
on error resume next
while Err.Number = 0
   MsgBox Registry.GetPathName( i ), vbOKOnly, "Paths in CURRENT_USER"
   i = i + 1
wend

bye

====================================================================================

' Demonstration of the tray image functions in MGCEWin32
' Written by Mark Gamber using NS Basic
' NOTE: This assumes you have two 16x16 images in the root
' directory of your device. If you don't make some, then try it!

addobject "MGCEWin32.Tray", "Tray", 0, 0, 0, 0
addobject "CommandButton", "Img1", 10, 10, 70, 20
addobject "CommandButton", "Img2", 80, 10, 70, 20
addobject "CommandButton", "NoImg", 10, 30, 140, 20

Img1.Caption = "Image 1"
Img2.Caption = "Image 2"
NoImg.Caption = "Remove Tray Image"

Tray.AddImage "\smimg1.bmp"
Tray.AddImage "\smimg2.bmp"

sub Img1_Click
   Tray.Image = 1
end sub

sub Img2_Click
   Tray.Image = 2
end sub

sub NoImg_Click
   Tray.Image = 0
end sub

sub Tray_Click( image )
   MsgBox "Image #" & CStr( image ) & " was clicked"
end sub

====================================================================================


