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

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

API Control

There are hundreds of available functions in the Win32 API as implemented on
Windows CE devices. Unfortunately, none of them are directly available from Basic.
Visual Basic can access the functions using the "declare" statement, but it's not
terribly intuitive and other brands of Basic may not be able to access the API at
all. While it is impractical to provide access to every API function available, it
is practical to provide access to the most commonly used and useful functions in
the Win32 API which is what this object does. In addition, Windows CE sends messages
to applications when certain system-wide changes or events take place. The API
control catches these messages and turns them into events your application can
handle if it so chooses. Note that the object does not attempt to protect the
system from errant programming, so be careful when using this control!

The number of possible flags, options and messages available to even the limited
subset of functions this object supports is large enough that this document does
not list them, nor does it provide a tutorial of the Win32 API and it's use. If
you are not familiar with the Win32 API, it is strongly suggested that you do NOT
use this object until you have become familiar with the API and it's calls supported
by this object. While it's extremely unlikely that physical damage could occur to
your device by using the API, it can't be ruled out and it is entirely possible to
lock up a device, requiring a cold reset, using the API. You have been warned and
have already agreed, by installing the object, that you accept full responsibility
for the use of this object and may not hold the object's author or any distributor
of the object liable for any loss or damage brought about by the use of the object.


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



Properties:

*** Capture
	Set and retrieve the window handle that has captured input focus. See the
ReleaseCapture method to release input capture once it has been set.

	API.Capture = lWnd
	lWnd = API.Capture


*** ClassName
	Read only. ClassName retrieves the text name of a specified window's class.

	MsgBox API.ClassName( lWnd )


*** ClipText
	Set and retrieve plain text to and from the system clipboard.

	API.ClipText = "Add something to the clipboard"
	sText = API.ClipText


*** CursorPos
	Retrieve the X,Y coordinates of the cursor when the cursor was last used.
This property returns an array of two values, the first being the horizontal position
and the second being the vertical position.

	aPos = API.CursorPos
	x = aPos( 1 )
	y = aPos( 2 )


*** EnableKeyboard
	TRUE enables the device keyboard, FALSE disables the device keyboard.

	API.EnableKeyboard = FALSE
	iKeyStatus = API.EnableKeyboard


*** Focus
	Set and retrieve the window handle with input focus.

	API.Focus = lWnd
	lWnd = API.Focus


*** ForegroundWindow
	Set and retrieve the current foreground window.

	API.ForegroundWindow = lWnd
	lWnd = API.ForegroundWindow


*** GetShortcutTarget
	Read only. You may retrieve the file a shortcut points to using this property.

	s = API.GetShortcutTarget "My Link.lnk"


*** GetWindow
	Read only. This property retrieves the handle of a window based on a window
specified and a relationship flag. These flags are:
	WNDFIRST (0): Retrieve the first peer window of the window specified.
	WNDLAST (1): Retrieve the last peer window of the window specified.
	WNDNEXT (2): Retrieve the next peer window of the window specified.
	WNDPREV (3): Retrieve the previous peer window of the window specified.
	WNDOWNER (4): Retrieve the owner (parent) of the specified window.
	WNDCHILD (5): Retrieve the first child window of the window specified.

	lChild = API.GetWindow( lWnd, WNDCHILD )


*** LocalTime
	Set and retrieve the current time and date according to the locale
specified by the Windows CE device.

	d = API.LocalTime
	API.LocalTime = Now


*** SystemColor
	Set and retrieve RGB color values for system components. Note: Changes
made using this property are temporary and are not maintained when a device is
restarted. SystemColor flags are:

	colorScrollBar: 0
	colorBackground: 1
	colorActiveCaption: 2
	colorInactiveCaption: 3
	colorMenu: 4
	colorWindow: 5
	colorWindowFrame: 6
	colorMenuText: 7
	colorWindowText: 8
	colorCaptionText: 9
	colorActiveBorder: 10
	colorInactiveBorder: 11
	colorAppWorkspace: 12
	colorHighlight: 13
	colorHighlightText: 14
	colorBtnFace: 15
	colorBtnShadow: 16
	colorGrayText: 17
	colorBtnText: 18
	colorInactiveCaptionText: 19
	colorBtnHighlight: 20
	color3DDKShadow: 21
	color3DLight: 22
	colorInfoText: 23
	colorInfoBK: 24

	clr = API.SystemColor( colorWindow )
	API.SystemColor( colorBackground ) = (128 * 65536 )


*** SystemParameters
	This property sets and retrieves various system-wide values which may or
may not be supported by a given version of Windows CE. Values supported by the
control are:

	spWorkArea: 0
	spWakupIdleTimeout: 1
	spExternalIdleTimeout: 2
	spBatteryIdleTimeout: 3
	spPlatformType: 4
	spOEMInfo: 5

The first four values are numeric, the last two are strings and read only.

	iTurnOffTime = API.SystemParameters( spBatteryIdleTimeout )
	API.SystemParameters( spBatteryIdleTimeout ) = 180  ' 3 minutes


*** SystemTime
	Set and retrieve the system time and date. Note that the time is
specified in Universal Coordinated Time (UTC).

	d = API.SystemTime
	API.SystemTime = Now


*** SystemVersion
	Retrieves the version of Windows CE. The upper 2 bytes of the returned
value is the major version number and the lower 2 bytes of the value is the
minor version number.

	version = API.SystemVersion


*** Ticks
	Retrives the number of milliseconds that have elapsed since Windows CE
was started.

	i = API.Ticks


*** TopMost
	The TopMost property sets and retrieves a window handle with topmost or
"Stay On Top" status. TRUE sets a window to topmost status, FALSE sets the window
to normal (not topmost) status.

	API.TopMost( lWnd ) = TRUE
	iStatus = API.TopMost( lWnd )


*** WindowLong
	Set and retrieve long values applied to windows. This may be used to
examine and alter window styles and custom data.

	i = API.WindowLong( lWnd, -16 )  ' Get window style
	API.WindowLong( lWnd, -16 ) = WS_CAPTION  ' Apply caption to style


*** WindowParent
	Set and retrieve the parent of a specified window.

	API.WindowParent( lChild ) = lNewParent
	lParent = API.WindowParent( lWnd )


*** WindowText
	Set and retrive the text displayed by a window caption. For most windows,
this is the text that appears in a caption bar. For other windows, such as edit
controls, this is the text that appears within the window itself.

	API.WindowText( lWnd ) = "Main Window"
	sCaption = API.WindowText( lWnd )



Methods:

*** AddToRecent
	This method creates a link to a specified file in the "Recently used"
folder. On most devices, this is the "My Documents" folder.

	API.AddToRecent "\somefile.txt"


*** ChildWindowFromPoint
	Given the handle of a window and screen coordinate, in pixels, this method
will return the handle (if any) of a window at that coordinate which is a child of
the specified window.

	lChild = API.ChildWindowFromPoint lWnd, xPos, yPos


*** CreateShortcut
	Create a shortcut to a specified file on the device.

	API.CreateShortcut sShortcutFilename, "\windows"  ' Shortcut to Windows dir


*** FindWindow
	Returns the handle of a window identified by it's caption text. This will
not find child windows, only top level windows.

	lWnd = API.FindWindow "apitest.nsb"


*** FindWindowByClass
	Returns the handle of a window identified by it's class name. This will not
find child windows, only top level windows.

	lWnd = API.FindWindowByClass "MyWndClass"


*** GetAsyncKeyState
	Retrieve the state of a keyboard key since the last time this method was
called.

	iKeyState = API.GetAsyncKeyState( 32 )   ' Check on spacebar


*** GetMemoryStatus
	Use this method to retrieve one of several available memory status values.
Method options are:

	memTotalPhysical: 0
	memAvailPhysical: 1
	memTotalPagefile: 2
	memAvailPagefile: 3
	memTotalVirtual: 4
	memAvailVirtual: 5
	memLoadPercent: 6

	iMemLoad = API.GetMemoryStatus( memLoadPercent )


*** GetPowerStatus
	This method retrieves one of several power (AC, Battery, etc) status values
which may or may not be supported on a given Windows CE device. Flags include:

	AC Status: 0
	Battery Flag: 1
	Battery Percent: 2
	Battery Life: 3
	Battery Full Life: 4
	Backup Flag: 5
	Backup Percent: 6
	Backup Life: 7
	Backup Full Life: 8

AC Status return values:
	ACOffline: 0
	ACOnline: 1
	ACUnknown: 255

Battery Flag / Backup Flag return values:
	BatteryHigh: 1
	BatteryLow: 2
	BatteryCritical: 4
	BatteryCharging: 8
	NoBattery: 128
	BatteryUnknown: 255

	iBatteryStatus = API.GetPowerStatus( 0 )


*** GetSpecialFolder
	This method retrieves the path of a "special folder", such as Favorites,
Desktop and Controls. Most devices support most of the possible flags, most they
are not all supported on all devices and will return an empty string (""). Flags
include:

	sfDesktop: 0
	sfPrograms: 2
	sfControls: 3
	sfPrinters: 4
	sfPersonal: 5
	sfFavorites: 6
	sfStartup: 7
	sfRecent: 8
	sfSendTo: 9
	sfRecycler: 10
	sfStartMenu: 11
	sfDesktopDir: 16
	sfDrives: 17
	sfNetwork: 18
	sfNetHood: 19
	sfFonts: 20
	sfTemplates: 21

	sPath = API.GetSpecialFolder( sfDesktop )


*** GetStorageStatus
	Retrieve the memory status of program storage. Flags include:

	Storage Total Size: 0
	Storage Free Size: 1

	iBytesFree = API.GetStorageStatus( 1 )


*** PostMessage
	This method posts a message to a window.

	iReturnVal = API.PostMessage( lWnd, msg, wParam, lParam )


*** ReleaseCapture
	Release input capture. If input capture was not set, nothing happens.

	API.ReleaseCapture


*** SendKeys
	Send keystrokes to whatever window has input focus at the time this
method is called. Shift, Control and Alt keystrokes causes the control to toggle
an internal flag. When any of these three keys are sent, the flag is set and
all keystrokes following are sent as though the Shift, Control or Alt key is
being pressed at the same time. When sent again, the flag is reset and following
keystrokes are sent as though the Shift, Control or Alt key is NOT pressed at the
same time. This continues through the string of keys passed to this method. A
second parameter determines if "key clicks" are used and should be set to TRUE for
silent operation or FALSE for key clicks.

	API.SendKeys Chr(16) & "T" & Chr(16) & "est", FALSE


*** SendMessage
	Sends a message to a window. Since SendMessage can pass numeric values
or strings, this method is used to send a numeric (32 bit) value with the message.

	iReturnVal = API.SendMessage( lWnd, msg, wParam, lParam )


*** SendMessageText
	This method also sends a message to a window. Unlike SendMessage, the
last parameter of this method is a string which is sent with the message.

	iRetVal = API.SendMessageText( lWnd, msg, wParam, "Item text" )


*** showWindow
	A window may be hidden, displayed, minimized and otherwise using this
method. Note the lowercase "s" in showWindow is not a typo! Flags include:

	swHide: 0
	swShowNormal: 1
	swShowNoActivate:4
	swShow: 5
	swMinimize: 6
	swShowMaximized: 11
	swMaximize: 12
	swRestore: 13

	API.showWindow lWnd, swHide


*** WindowFromPoint
	This method will find a top level window at a specified screen coordinate
and return it's handle, if any.

	lWnd = API.WindowFromPoint( xPos, yPos )



Events:

*** ColorChange
	This event is triggered when an application changes a system wide color.

	sub API_ColorChange
		MsgBox "Something changed a system color"
	end sub


*** FontChange
	This event is triggered when an application adds or removes a font resource.

	sub API_FontChange
		MsgBox "A font has been added or removed"
	end sub	


*** Hibernate
	When the device begins to run low on resources, a hibernate message is sent
to all running applications. It is the job of the applications to lower their memory
usage by freeing unneeded resources or, if possible, closing.

	sub API_Hibernate
		MsgBox "Uh oh...something bad is about to happen"
	end sub


*** PaletteChange
	When an applicate changes the system color palette, this event is
fired, allowing a program alter it's own color palette if it needs to do so.

	sub API_PaletteChange
		MsgBox "The system color palette has been changed"
	end sub


*** SettingsChange
	SystemParameters can get and retrieve various system settings and this
event notifies a program when one of those settings has been changed. The value
passed to this event is a flag which may be used with SystemParameters in order
to retrieve the new value of the setting that was changed.

	sub API_SettingsChange( flag )
		val = API.SystemParameters( flag )
	end sub

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


