Tech Note 16: Win32 API Control

January 06, 2009

© NSB Corporation. All rights reserved.

  1. Overview
  2. Timer Object
  3. Tray Object
  4. Registry Object
  5. Remote Access Connection Object (RAS)
    RAS Entry Object
    RAS Connection State Object
  6. API Object
    Point and Rectangle Object

1. Overview

NSBasic Win32 components provide access to various useful OS features for the NSBasic applications. Currently (version 2.0.1) the following objects are included in this library:

Timer object

ProgID: NSBasic.win32.Timer
ClassID: {ACE050A1-EEF9-435B-8D29-0D676727188B}
Create example: AddObject "NSBasic.win32.Timer", MyTimer

Tray object

ProgID: NSBasic.win32.Tray
ClassID: {5334D155-E526-4A1D-B03F-86B112DC8D3A}
Create example: AddObject "
NSBasic.win32.Tray", MyTray

Registry object

ProgID: NSBasic.win32.Registry
ClassID: {602E25DA-DBE7-4358-A542-1DFEC6793443}
Create example: AddObject "NSBasic.win32.Registry", MyRegistry

RAS Object

ProgID: NSBasic.win32.RAS
ClassID: {38CE02DD-7A75-4077-A1A8-DEC520CD618A}
Create example: AddObject "NSBasic.win32.RAS", MyRas

See also: RASEntry object and RASConState object which are non-creatable. They are obtained from the RAS object (See Entry, Connections, Entries) and RASEntry.Status respectively

API object

ProgID: NSBasic.win32.api
ClassID: {9217A3CE-4560-45D0-853C-F4CBCAD694C4}
Create example: AddObject "NSBasic.win32.api", MyApi

See also: PtOrRect object which is used by some routines that return/accept point or rectangle. 

Creation notes

To use a particular object you need to add it to your application. For example:
AddObject "NSBasic.win32.RAS", "ras"
later in the code you use it like this, for example:
Set connections = ras.Connections

In other words you use the ProgID of the object to create it and you specify a name of your choice for the created object.

For the most objects the best place to use the AddObject statement is the FormX_Load. However, objects like the Registry for instance are often used only in some specific parts of the application which are not always executed. In such case you can add the object in the routine that begins the task that needs the object and thus save some memory when the object is not needed.

The Tray and the Timer object have important events without which their usage is almost meaningless. This makes FormX_Load the best place for their creation.  

Supported platforms

The library is available as single DLL named: NSBWin32.dll

Builds are available for: Windows NT4/2000/XP/2003/Vista and later, Palm-sized PC, Handheld PC (all versions), Pocket PC, Pocket PC 2002, 2003/SE, 2005 (WM5) and later, MS Smartphone 2003/WM5 and later, custom CE.NET 4.0 or later based devices.

Compatibility with the old version - MGCEWin32 library.

This library is a reincarnation of the Mark Gamber's MGCEWin32 library, written anew from scratch only following the interface layout of the MGCEWin32 library as far as possible. All the creatable objects have a property named Version which return the class version as Major * 100 + Minor. For example 201 is returned for version 2.01. The legacy MGCEWin32 library classes have this property as well and it returns 10X. If you are porting code that uses MGCEWin32 library you can use this property to resolve compatibility issues. Alternatively you can change the code to use the new version and re-pack the application with the new DLL.

NSBasicWin32 is almost fully compatible with the older MGCEWin32 on usage syntax level, but there are some differences and additions. Some of the changes were needed in order to correct some problems in the old version, others were made in order to improve the usage and implement new features. Still, about 90% of the methods and properties are the same or defined with optional arguments in such manner that will permit old code to run without changes. Major differences can be found only in the RAS object which in contrast to the old version is now a root object of a hierarchy of objects that allow more convenient work with RAS phonebook entries.

 

 

 

2. Timer Object

The Timer object allows you execute events on the interval specified. In most cases, it will be easier to use the Timer property of an intrinsic object instead of this control.

The Interval and OnTimer events are equivalent to each other. Use the one you like most.

Members reference

Name Syntax Description
Interval object.Interval = value
variable = object.Interval
Specifies the timer's interval in milliseconds. Does not affect the timer if it is already running. You need to Stop and Start it again in order this value to take effect.
Tag object.Tag = value
variable = object.Tag
Sets an application specified tag - can be anything. You can use it if you have more than one timers and you have code that is called to handle similar operations. This will help you distinguish the timer that have invoked the operation.
Version variable = object.Version Returns the object version.
Start object.Start([Interval]) Starts the timer. If you pass an Interval argument it has the same effect as setting the Interval property before calling Start.
Stop object.Stop() Stops the timer.
Interval Sub object_Interval() Fired each time the interval expires.
OnTimer Sub object_OnTimer(sender) Fired each time the interval expires. The parameter is the Timer object itself. Prefer this event if you want to use one code to handle different timers which still need to be distinguished at some point.

 

 

 

3. Tray Object

This object allows you put and control icons in the shell/system notification area (often called System Tray).

The usage cycle of the object most often follows this pattern:
1. One or more bitmaps are added to the object (see AddImage)
2. At certain point the application puts an icon from the loaded bitmaps into the tray (See Image property).
3. The application handles user actions over the icon in the tray (see the events).
4. The application removes the image from the tray (object.Image = 0).

Do not forget to remove the image from the tray before the application exits or earlier if appropriate. Otherwise the image will remain there until the user passes with the mouse over it or until the shell is restarted (on some CE devices).

If you need more than one tray icons you need the same number of Tray objects in your application - each controlling one of the tray icons.

Hint. By using bitmaps containing many icons you can implement animation or dynamic state indication in the tray. Changing the Image property at run time will immediately change the icon the user sees. 

Note that on devices/systems with touch screens only Click and DblClick events can actually occur. Although some of these systems may support hold action internally translated to right mouse click this is not common for the system tray support and you cannot count on it when you write code that must run on different touch screen based systems.

Members reference

Name Syntax Description
Image object.Image = value
variable = object.Image
Type: Numeric
Specifies an index of an image/icon in the bitmap (See AddImage). When set it puts the specified image index into the system tray or returns the index of the currently shown image.
If an image is already shown in the system tray putting new index will change it giving you the opportunity to implement animations or application state indication in the system tray. 
Tag object.Tag = value
variable = object.Tag
An application specified value for its custom usage.
Version variable = object.Version Returns the object version.
AddImage image_index = object.AddImage(bitmapfile_path) Loads a set of icons/images to the object. The images are in a bitmap. Most often 16x16 images are used. If you want to have 4 different images you put 4 such images in a single bitmap with size 64x16 from left to right. Then the first image has index 1 and so forth.
RemoveImage object.RemoveImage(image_index) Removes an image previously loaded with AddImage. Use the returned image_index from it to address it.
Tip object.Tip = tool_tip_text
variable = object.Tip
Specifies the tool tip for the tray icon
Click Sub object_Click(sender) The user has clicked the tray icon with the left mouse button or has pressed space key over it.
RClick Sub object_RClick(sender) The user has clicked the tray icon with the right mouse button
DblClick Sub object_DblClick(sender) The user has double clicked the tray icon with the left mouse button or has pressed the Enter key over it.
RDblClick Sub object_RDblClick(sender) The user has double clicked the tray icon with the right mouse button.
KeyDown Sub object_KeyDown(sender) reserved for future use.

 

 

 

4. Registry Object

Provides access to the system registry. The object is designed to represent a "current key". I.e. you can think of the Registry object as attached to the registry key specified by the Key and Path properties. When you work with values the Name property "attaches" the object to the desired value.

The object allows enumeration of registry keys, but this features are is not implemented as collections that can be enumerated with For Each statements. The reasons are two - compatibility with the previous version of this object and the fact that the sub-keys enumerated can be too many. Depending on the usage this may lead to allocation of huge amount of system resources for a simple operation. See GetPathName and GetValueName for more information on how to enumerate keys and values.

Here are short samples for NS Basic/CE and NS Basic/Desktop:

'Sample for NS Basic/CE
ShowOKButton true
AddObject "NSBasic.win32.Registry","reg"

reg.key=&H1 'HKEY_CURRENT_USER
reg.path="Software\NSBasic\NSBasic\Recent File List"
reg.name="File1"
MsgBox reg.value



'Sample for NS Basic/Desktop
AddObject "NSBasic.win32.Registry","reg"

reg.key=&H1 'HKEY_CURRENT_USER
reg.path="Software\NSBasic\Desktop"
reg.name="SerialNumber"
MsgBox reg.value

Members reference

Name Syntax Description
Key object.Key = value
variable = object.Key
Sets the registry branch. Common constants:
Const HKEY_CLASSES_ROOT = &H0
Const HKEY_CURRENT_USER = &H1
Const HKEY_LOCAL_MACHINE = &H2
Const HKEY_USERS = &H3
Const HKEY_PERFORMANCE_DATA = &H4
Const HKEY_CURRENT_CONFIG = &H5
Const HKEY_DYN_DATA = &H6
Path object.Path = value
variable = object.Path
Sets/gets the key path name
Value object.Value = value
variable = object.Value
Sets/gets the value for the value with the specified Name (see Name).
Default property.
Name object.Name = value
variable = object.Name
Specifies the name of the current value in the current key.
Version variable = object.Version Returns the object version
ValueType object.ValueType = value
variable = object.ValueType
Specifies the type of the registry value type. When a value is assigned to the Value property it is converted internally to this type. Common constants:
Const REG_SZ = 1
Const REG_EXPAND_SZ = 2
Const REG_BINARY = 3
Const REG_DWORD = 4
Const REG_DWORD_LITTLE_ENDIAN = 4
Const REG_DWORD_BIG_ENDIAN = 5
Const REG_LINK = 6
Const REG_MULTI_SZ = 7
GetPathName enum_path = object.GetPathName(nKey) Call with nKey = 0 and then increment nKey to enumerate the sub-keys in the current key. When there are no more keys an error will occur. If you do not want On Error statements an empty key name will be returned if you set the ReturnEmptyForEnumEnd to true.
GetValueName enum_val = object.GetPathName(nVal) Call with nVal = 0 and then increment nVal to enumerate the values in the current key. When there are no more values an error will occur. If you do not want On Error statements an empty key name will be returned if you set the ReturnEmptyForEnumEnd to true.
CreatePath object..CreatePath() Creates a registry key specified by the Path property with the in the registry branch specified by the Key property.
DeletePath object.DeletePath Deletes the registry key specified by the Path property with the in the registry branch specified by the Key property.
DeleteValue object.DeleteValue Deletes the value specified by the Name property from the current key (the key is determined by the Key and the Path properties).
Advanced features
UseRawBinary object.UseRawBinary = bool_val
variable = object.UseRawBinary 
Default is false.
If set to true the Value property will return binary data instead of hex decimal textual representation of binary data for binary (REG_BINARY) values. Useful when you want to pass the data to a database or another object that requires binary data (VT_ARRAY | VT_UI1).
HexWithSpaces object.HexWithSpaces = bool_val
variable = object.HexWithSpaces 
Default is false.
When the Value property returns the value of a binary value (REG_BINARY), by default it returns is as hex-decimal string. Id this property is set to true spaces between the bytes will be inserted.
ReturnEmptyForEnumEnd object.ReturnEmptyForEnumEnd = bool_val
variable = object.ReturnEmptyForEnumEnd 
Default is false.
GetPathName and GetValueName by default generate an error which can be intercepted with OnError statement when there are no more keys/values to enumerate. Setting this property to true changes this behavior and they return empty strings instead of generating an error.

 

 

 

5. Remote Access Connection Object (RAS)

This object is the root of a foundation of objects that allow the NSBasic application to obtain information and control the Remote Access Connections (RAS) of the system/device. You need to create only this object (NSBasic.win32.RAS), the other objects from the RAS foundation are obtained/created by the its members.

While internally the RAS object and the RASEntry objects are able to query the state of the entry (connected or not for instance), be sure to pay attention to the RASEntry members reference in order to ensure that you know when and how the state of the represented RAS entry is current. For example if you obtain a RASEntry object it represents the entry state at the moment in which you have obtained the object. If you keep the object for some time the state of the corresponding RAS entry may change because another application uses it. Use RASEntry.ResetState whenever you need to be absolutely sure that the RASEntry object "knows" what is currently happening with the RAS entry it represents. If you omit this step you may for example attempt to dial already connected entry.

Notes 

Currently the RAS objects foundation represents the most common RAS phone book features in all the Windows versions. In future the foundation may be extended to support additional features - such as specifying the RAS device settings and so on. The objects are written with this in mind and compatibility of any NSBasic code that uses them with future versions is guaranteed.

Members reference

Name Syntax Description
PhoneBook object.PhoneBook = value
variable = object.PhoneBook
By default it is empty which means "the default phone book". Some OS versions support different phonebooks and you can specify the file name of a non-default phonebook in this property. Before using it consult the OS version/variant documentation to see if this it supports custom phonebooks. 
If you do not have special reason to deal with custom phonebooks leave the property empty - i.e. do not change it.
Version variable = object.Version Returns the object version
Entry objEntry = object.Entry(EntryName) Returns RASEntry object representing the RAS entry specified by the EntryName from the current phonebook (see PhoneBook).
Entries object = object.Entries
For Each Entry In object.Entries
Returns a collection of RASEntry objects with all the entries in the current phonebook (see PhoneBook).
Connections object = object.Connections
For Each Entry In object.Connections
Returns a collection of RASEntry objects currently active connections (connected or in connecting but in intermediate or erroneous state). You can think of it as of a collection of the connected RAS phonebook entries.

 

 

 

5.1 RAS Entry Object

Applies to: RAS object

Members reference

Name Syntax Description
Name object.Name = value
variable = object.Name
Specifies the RAS phonebook entry's Name
CallbackNumber object.CallbackNumber = value
variable = object.CallbackNumber
Specifies the callback phone number (or IP/DNS name for VPN connections) for the entry as string.
UserName object.UserName = value
variable = object.UserName
Specifies the user name for the RAS entry
Domain object.Domain = value
variable = object.Domain
Specifies the domain name for the RAS entry. Most often it is empty to indicate the default domain of the RAS server to which the entry connects.
Password object.Domain = value Sets the password for the entry. You should call Update if you want to save it within the phonebook. Be aware that different OS versions may have different default policies about this - save the password for the current user, for all users, do not permit saving etc.
PhoneNumber object.PhoneNumber = value
variable = object.PhoneNumber
Override phone number (or IP/DNS name for VPN connections) for the entry. The entries most often have one or more phone numbers saved in the RAS phonebook. This property allows you to override the number(s) from it with a specific phone number before dialing up. Otherwise this property has no persistent effect over the entries (i.e. it is not saved)
Connect object.Connect() Attempts to dial up and connect the entry.
Disconnect object.Disconnect() Attempts to hang up. Note that you must have a connected RASEntry object in order this to succeed. For example such object can be obtained from the RAS.Connections collection. Otherwise you should have called Connect over the same entry before. See also ResetState.
Load object.Load() Reloads the entry from the RAS phonebook.
Update object.Update() Updates the entry data in the RAS phonebook.
Delete object.Delete() Deletes the entry from the RAS phonebook.
HasPassword object.HasPassword = value
variable = object.HasPassword 
Boolean indicating if the entry has saved password. If you set it to false the saved password will be deleted when you call Update.
IsActive variable = object.IsActive  Indicates if the entry is in active - connected or connecting state. Note that this is not completely reliable for long periods of time because it indicates the last known state. If you want to make sure you are dealing with the current state of the entry call ResetState or query the entry state through the Status property. 
Status o = object.Status Returns RASConState object which enables you to query details about the entry's current state. The RASConState object and the entry object are updated with the current state (i.e. the object automatically attempts to determine what is happening with this entry when you read this property - is it connected or not, what is the status of the connection etc.).  
ResetState object.ResetState() Attempts to determine the current state of the entry - updates the connected/connecting state etc. After calling this method IsActive is ensured to indicate the current state of the entry.

 

 

 

5.2 RAS Connection State Object

Applies to: RASEntry
Obtained from RASEntry.Status property. When queried from the property the RASEntry object synchronizes the state information for the RAS entry it represents and the returned RASConState object is guaranteed to reflect the current state of the entry. This means it is best to obtain fresh RASConState object from the RASEntry.Status property each time you want to query its state. Using the Refresh method will refresh the state information but only until the current connection is active (if the entry is connected). If the entry has been disconnected and reconnected again the Refresh method will no longer do any useful work - you will need to obtain new RASConState object from the RASEntry of interest. Thus the Refresh method is an useful  helper only for phases in which you need to follow a dialing process you have just invoked.

You can use the DeviceType/DeviceName as alternative (to RASEntry.IsActive) indicators that a connection is actually in progress. They have non-empty values only if the entry is connected/connecting.

Members reference

Name Syntax Description
State variable = object.State Returns the state of the connection (if connected). Common constants returned:
RASCS_OpenPort = 0
RASCS_PortOpened = 1
RASCS_ConnectDevice = 2
RASCS_DeviceConnected = 3
RASCS_AllDevicesConnected = 4
RASCS_Authenticate = 5
RASCS_AuthNotify = 6
RASCS_AuthRetry = 7
RASCS_AuthCallback = 8
RASCS_AuthChangePassword = 9
RASCS_AuthProject = 10
RASCS_AuthLinkSpeed = 11
RASCS_AuthAck = 12
RASCS_ReAuthenticate = 13
RASCS_Authenticated = 14
RASCS_PrepareForCallback =15
RASCS_WaitForModemReset = 16
RASCS_WaitForCallback = 17
RASCS_Projected = 18
Note that some OS versions support more values. Consult MSDN for extended information about the possible values for the OS version you work with.
ErrorNumber variable = object.ErrorNumber Returns the error number > 0 (if error has occurred). If you are interested in displaying particular error messages you can obtain the RAS error list from raserror.h file from MS Visual C include directory. There are over 150 different error messages listed in it.
DeviceType variable = object.DeviceType Returns a string representing the device type used for the connection (if connected/connecting - empty otherwise).
DeviceName variable = object.DeviceName Returns a string representing the device name used for the connection (if connected/connecting - empty otherwise).
Refresh object.Refresh() Refreshes the status information (see the notes above).

 

 

 

6. API Object

Overview

The API object provides easy-to-use access to certain Win32 API functions which may be needed by applications that need to perform some advanced tasks. While useful in scenarios where the standard NSBasic features are not enough the API object requires careful usage and some basic level of understanding of the Win32 API. Wrong usage will not harm the system, but may cause some inconveniences to the interactive user or unexpected behavior of the application or the affected windows of other applications. It is recommended to consult MSDN for details about the particular methods and properties. To make this easier the most of the API object's members are named after the closest Win32 API function.

Names and abbreviations

In the members reference below:
wnd - is a long integer value which represents a handle of a window. Once obtained from a property or method it can be used as parameter to another member which takes as an argument window handle. Generally wnd = 0 is an invalid window handle value (no window found for instance).
object - is a previously created API object.

Members reference

Name Syntax Description
FindWindow wnd = object.FindWindow(title) Finds a top level window with the specified title and returns its handle. If such window is not found 0 is returned. 
ReleaseCapture object.ReleaseCapture() Releases the mouse capture (See also Capture).
SendMessage r =object.SendMessage(wnd,msg,wParam,lParam) Sends message to a window and returns the result. This method cannot be used for windows of other applications.
WindowFromPoint wnd = object.WindowFromPoint(X,Y) Returns the handle of the window at point X,Y (in screen coordinates).
ChildWindowFromPoint wnd = object.ChildWindowFromPoint(wnd,X,Y) Returns the handle of the child window of wnd at point X,Y (in screen coordinates). Wnd is the parent window whose children are searched.
PostMessage r =object.PostMessage(wnd,msg,wParam,lParam) Posts message to the specified window. In contrast to SendMessage this method can be used over windows of other applications.
ForegroundWindow wnd = object.ForegroundWindow
object.ForegroundWindow = wnd
Gets/Sets the foreground window.
Focus object.Focus = wnd
wnd = object.Focus
Gets/Sets the window which owns the keyboard focus.
Capture object.Capture = wnd
wnd = object.Capture
Gets/Sets the window which has the mouse capture. To release capture call ReleaseCapture (see above).
EnableKeyboard object.EnableKeyboard = boolValue
var = object.EnableKeyboard
Gets/Sets the enabled state of the hardware keyboard. Works only on Windows CE based devices with hardware keyboard.
WindowText object.WindowText(wnd) = stringValue
var = object.WindowText(wnd)
Gets/Sets the text of the specified window. Usually the window text is displayed in its caption. Specific windows (such as edit boxes, labels and so on) display their window text otherwise - as content, as label and so on.
SystemColor object.SystemColor(lColor) = colorValue
var = object.SystemColor(lColor)
Gets/Sets a system wide color constant specified by lColor. Note that this changes the color for all the applications! The different OS versions support some common Windows color values and some specific to the particular OS. Lookup GetSysColor in MSDN for more information. Some of the most common color constants are:
COLOR_SCROLLBAR 0
COLOR_BACKGROUND 1
COLOR_ACTIVECAPTION 2
COLOR_INACTIVECAPTION 3
COLOR_MENU 4
COLOR_WINDOW 5
COLOR_WINDOWFRAME 6
COLOR_MENUTEXT 7
COLOR_WINDOWTEXT 8
COLOR_CAPTIONTEXT 9
COLOR_ACTIVEBORDER 10
COLOR_INACTIVEBORDER 11
COLOR_APPWORKSPACE 12
COLOR_HIGHLIGHT 13
COLOR_HIGHLIGHTTEXT 14
COLOR_BTNFACE 15
COLOR_BTNSHADOW 16
COLOR_GRAYTEXT 17
COLOR_BTNTEXT 18
COLOR_INACTIVECAPTIONTEXT 19
COLOR_BTNHIGHLIGHT 20 
The colorValue can be constructed this way:
B * &H10000 + G * &H100 + R
Where R, G and B are the Blue, Green and Red component (0-255).
TopMost object.TopMost = wnd Makes the specified window "top most".
GetWindow wnd = object.GetWindow(wnd,type) Retrieves a window that is in the specified relation (type) to the given window (wnd). type can be:
GW_HWNDFIRST 0
GW_HWNDLAST 1
GW_HWNDNEXT 2
GW_HWNDPREV 3
GW_OWNER 4
GW_CHILD 5
ClassName var = object.ClassName(wnd) Returns the Window class name of the specified window.
ShowWindow object.ShowWindow(wnd,cmd) Changes the window presence. For example hides or shows it. The cmd can be:
SW_HIDE 0
SW_SHOWNORMAL 1
SW_NORMAL 1
SW_SHOWMINIMIZED 2
SW_SHOWMAXIMIZED 3
SW_MAXIMIZE 3
SW_SHOWNOACTIVATE 4
SW_SHOW 5
SW_MINIMIZE 6
SW_SHOWMINNOACTIVE 7
SW_SHOWNA 8
SW_RESTORE 9
SW_SHOWDEFAULT 10
SW_FORCEMINIMIZE 11
GetAsyncKeyState state = object.GetAsyncKeyState(lKey) Retrieves the state of a keyboard key. lKey specifies the keyboard key to query. While the function can query wide variety of state information we list here only some of the features. For more information see GetAsyncKeyState in MSDN.
lKey codes for some keyboard keys:
VK_LSHIFT &HA0
VK_RSHIFT &HA1
VK_LCONTROL &HA2
VK_RCONTROL &HA3
VK_LMENU &HA4
VK_RMENU &HA5
VK_F1 &H70
continuous to
VK_F24 &H87
VK_SHIFT &H10 (shift any)
VK_CONTROL &H11 (control - any)
VK_MENU &H12 (alt - any)
VK_PAUSE &H13
VK_CAPITAL &H14 (caps lock)

The returned result can be used this way to determine if the key is down or up.
If state >= &H80000000 Then
  ' Key is down
Else
  ' Key is up
End If 

SendKeys object.SendKeys(strKeys [,boolSilent]) Sends a keyboard stroke to the window that has the focus. On Widnows CE If boolSilent is True no clicking sounds are made.
GetMemoryStatus var = object.GetMemoryStatus(type) Obtains information about the system/program memory.
type can be:
0 - Total physical memory
1 - Available physical memory
2 - Total page file
3 - Available page file
4 - Total virtual memory (for the process)
5 - Available virtual memory (for the process)
6 - System memory load in percents (0 - 100) 
In order to support both CE and desktop systems the function uses different numeric types for the returned value. On desktops it will most often return double precision floating point value because the long integer values are not enough for the modern machines. 
GetStorageStatus var = object.GetStorageStatus(info [, path]) Obtains storage information.
info can be:
0 - Total size of the storage in bytes
1 - Free bytes on the storage
2 - Free bytes on the storage available to the user.
If the path argument is omitted the function returns:
On desktop: information about the volume containing the current directory
On CE devices: Information about the internal object store.
If path is present it should be a string denoting a path on the storage device/volume for which you want to obtain information (it doesn't matter which directory is specified - it is enough to be sure that it is on the device/volume of interest).
Usually info = 2 will return the same information as 1, but on systems where that have disk quoting enabled it will indicate the space available to the current user.
GetPowerStatus var = object.GetPowerStatus(param) Obtains information about the system power status.
param can be: 
0 - Is on AC power (0 -no, 1 - yes, 255 - unknown)
1 - Battery (1 - high, 2 - low, 4 - critical, 8 - charging, 128 - no battery, 255 - unknown)
2 - Battery life (0 - 100% or 255 if unknown)
3 - Battery life time (in seconds or -1 meaning unknown)
4 - Battery full life time in seconds or -1 if unknown.
Windows CE only:
5 - Backup battery flag - like 1
6 - Backup Battery life (0 - 100% or 255 if unknown)
7 - Backup Battery life time (in seconds or -1 meaning unknown)
8 - Backup Battery full life time in seconds or -1 if unknown.
SystemParameters object.SystemParameters(which) = newVal
var = object.SystemParameters(which) 
Get set some system parameters.
which can be:
0 - Work area returns/sets a rectangle describing the work area
Windows CE only:
1 - Gets/Sets the idle timeout for which the device will stay on after it has been waked up. Returns the timeout for the current situation - no matter which is it.
2 - Gets/Sets the idle timeout for which the device will stay on after it has been waked up when on external power.
3 - Gets/Sets the idle timeout for which the device will stay on after it has been waked up when on battery power. 
4 - Gets (only) - platform type as string
5 - Gets (only) - OEM information as string
To set the work area you must first get it than change the returned object and assign it back. Example:
rect = api.SystemParameters(0)
rect.Left = rect.Left + 20
Set api.SystemParameters(0) = rect
This code shrinks the work area by 20 pixels on the left. The best way to describe the work area is to say that it is the screen area which is available to maximized windows. On the different OS versions and devices this may have also some additional effects.
CreateShortcut object.CreateShortcut(spath,tpath) Creates shortcut named spath pointing to the file/directory tpath. Note that you should name the shortcut with .LNK file extension to make sure it is correctly displayed and used by the shell. spath and tpath must be full path names.
AddToRecent object.AddToRecent(path) Adds the specified path/file to the recent files/documents.
GetSpecialFolder var = GetSpecialFolder(type) Obtains the full path to the specified special folder. Note that the different OS versions support quite a lot of specific special folders. The type values listed below are only for the most common ones. Check MSDN for the specific ones if you wish to use them. The function will work with future versions of the OS - by supplying the correct constant you will be able to obtain the folder of interest even if it does not existed at the time this library was built.
type can be:
0 - Desktop
2 - Programs (in the start menu)
5 - Personal/My Documents
6 - Favorites
7 - Startup
8 - Recent
9 - Send to
11 - Start menu
10 - desktop directory
14 - Fonts
15 - Templates
26 - Application data
Note that together with CreateShortcut you can find appropriate location and create shortcut there.
GetShortcutTarget var = object.GetShortcutTarget(spath) Obtains the target to which the specified shortcut points. spath is the full path name of the shortcut file. Note that the shell hides the shortcut's file extension which is .LNK
FindWindowByClass wnd = object.FindWindowByClass(strClass) Returns the first found top level window of the given Window class.
ClipText object.ClipText = value
var = object.ClipText 
Sets/Gets the text to/from the clipboard. When set the clipboard is cleared from any previous content and the assigned text is placed in it.
Version object.Version Returns the object version.
CursorPos Set obj = object.CursorPos Returns a point object holding the screen coordinates of the mouse cursor.
SystemVersion var = object.SystemVersion  Returns the OS version as long integer.
Major version is var / &H10000
Minor version is var And &HFFFF
WindowLong object.WindowLong(wnd,lLong) = value
var = object.WindowLong(wnd,lLong) 
Sets/Gets a value associated with the given window. The value is long integer (vbLong). Use with extreme care!!! Some of the values associated with the windows hold internal pointers to code that handles the window and changing them may crash the application to which the window belongs. Check carefully MSDN before using this method - see GetWindowLong/SetWindowLong and the related comments.
Ticks var = object.Ticks Returns the ticks count since the system start up. 1 - tick is 1 millisecond.
SystemTime object.SystemTime = value
var = object.SystemTime
Sets/Gets the system time
LocalTime object.LocalTime = value
var = object.LocalTime
Sets/Gets the local time
WindowParent object.WindowParent(wnd) = wndParent
wnd = object.WindowParent(wndToQuery)
Gets/Sets the parent window of an window. Use with extreme care !!! Changing the parent of an window may lead to unpredictable results including application crash. You should have good knowledge about the behavior of the affected windows.
OSType var = object.OSType Returns a string identifying the OS type:
9x - The OS is Windows 95/98/ME
NT - The OS is NT4/Win2k/XP or later
CE - The OS is Windows CE.
Can be used when you are creating code that must work on different platforms. Determining the OS Type your code will be able to avoid or use features specific to a particular platform. 
Hibernate Sub object_Hibernate() Fired when the system resources are running low and the application should attempt to free as much as possible. (Windows CE only)
ColorChange Sub object_ColorChange() Fired when one or more of the system colors are changed.
FontChange Sub object_FontChange() Fired when a new font has been added/changed/deleted from the system 
PaletteChange Sub object_PaletteChange() Fired only on systems using graphics mode with palettes. Fires when the system palette changes.
SettingsChange Sub object_SettingsChange(which) Fired when a system setting is changed. which contains the setting index.

 

 

 

6.1 Point and Rectangle Object

This object is returned or accepted by some methods/properties in this library. It represents a rectangle or a point and provides convenient programming interface to the data.

The object is non-creatable. If you need to set it to a property/pass as argument you need to obtain it first from the corresponding property or method which queries the information you want to change. 

Members reference

Name Syntax Description
Value object.Value(index) = value
object(index) = value
variable = object.Value(index)
variable = object(index)
Type: Numeric
Default property.
index can be 0 to 3. 
index 0 is equivalent to X and Left
index 1 is equivalent to Y and Top
index 2 is equivalent to Right
index 3 is equivalent to Bottom
X object.X = value
variable = object.X
Sets/Gets the X coordinate of the represented point.
Y object.Y = value
variable = object.Y
Sets/Gets the Y coordinate of the represented point.
Left object.Left = value
variable = object.Left
Sets/Gets the left side of the represented rectangle.
Right object.Right = value
variable = object.Right
Sets/Gets the right side of the represented rectangle.
Top object.Top = value
variable = object.Top
Sets/Gets the Top side of the represented rectangle.
Bottom object.Right = value
variable = object.Bottom
Sets/Gets the Bottom side of the represented rectangle.