Contents:

    Introduction
    Function Index and Quick Reference
    Function Reference

Introduction:

The NSBSystemLib Shared Library contains functions that provide access to the PalmOS System. Some of these functions allow calls to PalmOS APIs that can not currently be called using NSBasic's SysTrap statements. Others, just provide a simplified interface to the PalmOS.

The functions in this library are divided into the following categories:

Alarms, Databases, Events, Field and Forms, HotSync Data, Localization, Preferences, Progress Manager, and System Time. With the version 2.0 release, additional categories for bitwise, encryption, decryption, and screen/color operations have been added.

This document, with its examples, should provide all the information necessary to use the functions in the NSBSystemLib. If more information about the underlying PalmOS functions is desired, please consult the PalmOS SDK Reference or the SDK C header files (*.h). The PalmOS SDK Reference can be downloaded from:

    http://www.palmos.com/dev/tech/docs/

    http://www.palmos.com/dev/tech/tools/

In order to use the NSBSystemLib Shared Library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the program's Startup code so that the functions will be available throughout the program. The LoadLibrary statement has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions. The examples in this document use "NSL" for this reference name. Example:

Program's Startup code:

	Sub main()
	    LoadLibrary "NSBSystemLib", "NSL"
	End Sub

Also, in order to use the NSBSystemLib Shared Library, the NSBSystemLib.INF file must be present in your "nsbasic\lib" directory and the NSBSystemLib.prc file must be downloaded to your device.

Except for the functions that return version numbers, all the parameter and return data types are either "Integer" or "String". Version numbers are returned as a "Double".

Function Index and Quick Reference:

NSBSystemLib Function Reference:

Version Information

Version

version = NSBSystemLib.Version()

Returns

version as Double

Example

Dim version as Double
version = NSL.Version()

CompileInfo

compileDateTime = NSBSystemLib.CompileInfo()

Returns

compileDateTime as String

Example

Dim compileDateTime as String
compileDateTime = NSL.CompileInfo()

SystemVersion

version = NSBSystemLib.SystemVersion()

Returns

version as Double

Example

Dim version as Double
version = NSL.SystemVersion()

Access To Shared Library Global Variables

GlobalVersionMajor

gblMajor = NSBSystemLib.GlobalVersionMajor()

Returns

gblMajor as Integer

Example

Dim gblMajor as Integer
gblMajor = NSL.GlobalVersionMajor()

GlobalVersionMinor

gblMinor = NSBSystemLib.GlobalVersionMinor()

Returns

gblMinor as Integer

Example

Dim gblMinor as Integer
gblMinor = NSL.GlobalVersionMinor()

GlobalX

x = NSBSystemLib.GlobalX()

Returns

x as Integer

Example

Dim x as Integer
x = NSL.GlobalX()

GlobalY

y = NSBSystemLib.GlobalY()

Returns

y as Integer

Example

Dim y as Integer
y = NSL.GlobalY()

GlobalStartX

startX = NSBSystemLib.GlobalStartX()

Returns

startX as Integer

Example

Dim startX as Integer
startX = NSL.GlobalStartX()

GlobalStartY

startY = NSBSystemLib.GlobalStartY()

Returns

startY as Integer

Example

Dim startY as Integer
startY = NSL.GlobalStartY()

GlobalEndX

endX = NSBSystemLib.GlobalEndX()

Returns

endX as Integer

Example

Dim endX as Integer
endX = NSL.GlobalEndX()

GlobalEndY

endY = NSBSystemLib.GlobalEndY()

Returns

endY as Integer

Example

Dim endY as Integer
endY = NSL.GlobalEndY()

GlobalStartPos

startPos = NSBSystemLib.GlobalStartPos()

Returns

startPos as Integer

Example

Dim startPos as Integer
startPos = NSL.GlobalStartPos()

GlobalEndPos

endPos = NSBSystemLib.GlobalEndPos()

Returns

endPos as Integer

Example

Dim endPos as Integer
endPos = NSL.GlobalEndPos()

GlobalWidth

width = NSBSystemLib.GlobalWidth()

Returns

width as Integer

Example

Dim width as Integer
width = NSL.GlobalWidth()

GlobalHeight

height = NSBSystemLib.GlobalHeight()

Returns

height as Integer

Example

Dim height as Integer
height = NSL.GlobalHeight()

GlobalHour

gblHour = NSBSystemLib.GlobalHour()

Returns

gblHour as Integer

Example

Dim gblHour as Integer
gblHour = NSL.GlobalHour()

GlobalMinute

gblMinute = NSBSystemLib.GlobalMinute()

Returns

gblMinute as Integer

Example

Dim gblMinute as Integer
gblMinute = NSL.GlobalMinute()

Alarm Functions

NSBAlarmProxy1, NSBAlarmProxy2, NSBAlarmProxy3, NSBAlarmProxy4, and NSBAlarmProxy5

SetAlarmReset

NSBSystemLib.SetAlarmReset resetTime, resetLimit

Parameters

resetTime as Integer
	Reset interval in seconds
	  0 = do not automatically reset alarm

resetLimit as Integer
	Limit to the number of automatic resets that can occur.
	 -1 = resets are not limited - CancelAlarm() must be
	      used to stop automatic resets.
	  0 = do not automatically reset alarm

Example

Dim resetTime as Integer
Dim resetLimit as Integer

resetTime = 10
resetLimit = -1
NSL.SetAlarmReset resetTime, resetLimit

SetAlarm

status = NSBSystemLib.SetAlarm(alarmPgm, alarmTime, alarmCmd, alarmMsg)

Parameters

alarmPgm as String
	Alarm program.
alarmTime as Integer
	Absolute alarm time in system time format or a time
	increment in seconds from the current time.  This time
	is considered as an absolute time if its value is greater
	or equal to the value of the current system time minus 5
	minutes.
alarmCmd as Integer
	Alarm Command explanations:
	  -32767 to -30001 = "Timer" commands
	     These commands have the least amount of overhead
	     associated with them.  They do not write to the
	     alarm log information.  In addition, they automat-
	     ically reset the alarm.  As such, they must be
	     specifically cancelled using the CancelAlarm()
	     function.
	
	     These commands queue an event which is the
	     absolute (positive) value of the command.
	
	     The reset interval (seconds) used is calculated as:
	          abs(cmd) - 30000
	          example:  -30005 has a reset interval of 5
	                           seconds and queues an event
	                           with an event type of 30005.
	  0 = enqueue a "nilEvent" - can be used to just simply
	      wake up or turn on a PalmOS device
	  1 = sound a system alarm sound only
	  2 = sound a system alarm sound and produce an Alert
	      with the message specified in the alarmMsg parameter.
	  3 = start the program with the name specified in the
	      alarmMsg parameter.  The alarmMsg parameter, in this
	      case, is a coded string with the following format:
	          <programName>[,<launcherWaitTime>][;<userInfo>]
	          examples:  "Address"
	                     "Address;started by MyProg"
	                     "Address,6;started by MyProg"
	          notes:  The launcherWaitTime is the time, in
	                  in seconds to wait for the current program
	                  to terminate - the default is 2 seconds.
	                  The userInfo, as well as the entire string,
	                  is written to the alarmLog.  It can be used
	                  for any purpose you like.
	   4 to 255 = enqueue a Key Event with a value equal to
	              the specified alarmCmd
	   24832 to 30000 = enqueue a generic event with an event
	                    type equal to the specified alarmCmd.
alarmMsg as String
	 A string of 80 characters or less that is used as the
	 message for alarmCmd 2 or the program code for alarmCmd 3.
	 It is also written to the alarm log to provide any info.
	 that may be useful.

Returns

status as Integer
	 0 = no error
	-1 = specified alarm program is not installed
	-2 = almErrorMemory - insufficient memory
	-3 = almErrorFull - alarm queue is full
	-4 = unexpected/unrecognized error

Example

Dim status as Integer
Dim alarmPgm as String
Dim alarmTime as Integer
Dim alarmCmd as Integer
Dim alarmMsg as String

alarmPgm = "NSBAlarmProxy1"
alarmTime = 3600    ' 1 hour from now
alarmCmd = 3
alarmMsg = "Hey Wake UP!"
status = NSL.SetAlarm(alarmPgm, alarmTime, alarmCmd, alarmMsg)

CancelAlarm

status = NSBSystemLib.CancelAlarm(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

status as Integer
	 0 = no error
	-1 = specified alarm program is not installed
	-2 = almErrorMemory - insufficient memory
	-3 = almErrorFull - alarm queue is full
	-4 = unexpected/unrecognized error

Example

Dim status as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
status = NSL.CancelAlarm(alarmPgm)

GetAlarm

alarmTime = NSBSystemLib.GetAlarm(alarmPgm, alarmCmd, alarmMsg)

Parameters

alarmPgm as String
	Alarm program.
alarmCmd as String
	AlarmCmd as a string.  This value is returned and
	must be initialized to a maximum length before calling
	the function.  This value should never be more than
	6 characters in length.
alarmMsg as String
	Alarm message as a string.  This value is returned and
	must be initialized to a maximum length before calling
	the function.  This value should never be more than
	80 characters in length.

Returns

alarmTime as Integer
	Alarm time in system time format.  This value is expressed
	as the number of seconds since January 1st, 1904.

Example

Dim alarmTime as Integer
Dim alarmPgm as String
Dim alarmCmd as String
Dim alarmMsg as String

alarmPgm = "NSBAlarmProxy1"
alarmCmd = "123456"
alarmMsg = "1234567890123456789012345678901234567890" _
         + "1234567890123456789012345678901234567890"
alarmTime = NSL.GetAlarm(alarmPgm, alarmCmd, alarmMsg)

GetAlarmTime

alarmTime = NSBSystemLib.GetAlarmTime(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

alarmTime as Integer
	Alarm time in system time format.  This value is expressed
	as the number of seconds since January 1st, 1904.

Example

Dim alarmTime as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmTime = NSL.GetAlarmTime(alarmPgm)

GetAlarmResetTime

resetTime = NSBSystemLib.GetAlarmResetTime(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

resetTime as Integer
	Alarm reset time in seconds.

Example

Dim resetTime as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
resetTime = NSL.GetAlarmResetTime(alarmPgm)

GetAlarmResetLimit

resetLimit = NSBSystemLib.GetAlarmResetLimit(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

resetLimit as Integer
	Alarm reset limit.

Example

Dim resetLimit as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
resetLimit = NSL.GetAlarmResetLimit(alarmPgm)

GetAlarmCommand

alarmCmd = NSBSystemLib.GetAlarmCommand(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

alarmCmd as Integer
	Alarm command.

Example

Dim alarmCmd as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmCmd = NSL.GetAlarmCommand(alarmPgm)

GetAlarmMessage

alarmMsg = NSBSystemLib.GetAlarmMessage(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

alarmMsg as String
	Alarm message.

Example

Dim alarmMsg as String
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmMsg = NSL.GetAlarmMessage(alarmPgm)

AlarmLog

alarmTime = NSBSystemLib.AlarmLog(alarmPgm, alarmCmd, alarmMsg)

Parameters

alarmPgm as String
	Alarm program.
alarmCmd as String
	AlarmCmd as a string.  This value is returned and
	must be initialized to a maximum length before calling
	the function.  This value should never be more than
	6 characters in length.
alarmMsg as String
	Alarm message as a string.  This value is returned and
	must be initialized to a maximum length before calling
	the function.  This value should never be more than
	80 characters in length.

Returns

alarmTime as Integer
	Alarm time in system time format.  This value is expressed
	as the number of seconds since January 1st, 1904.

Example

Dim alarmTime as Integer
Dim alarmPgm as String
Dim alarmCmd as String
Dim alarmMsg as String

alarmPgm = "NSBAlarmProxy1"
alarmCmd = "123456"
alarmMsg = "1234567890123456789012345678901234567890" _
         + "1234567890123456789012345678901234567890"
alarmTime = NSL.AlarmLog(alarmPgm, alarmCmd, alarmMsg)

AlarmLogAlarmTime

alarmTime = NSBSystemLib.AlarmLogAlarmTime(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

alarmTime as Integer
	Alarm time in system time format.  This value is expressed
	as the number of seconds since January 1st, 1904.

Example

Dim alarmTime as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmTime = NSL.AlarmLogAlarmTime(alarmPgm)

AlarmLogResetTime

resetTime = NSBSystemLib.AlarmLogResetTime(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

resetTime as Integer
	Alarm time reset time in seconds.

Example

Dim resetTime as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
resetTime = NSL.AlarmLogResetTime(alarmPgm)

AlarmLogResetLimit

resetLimit = NSBSystemLib.AlarmLogResetLimit(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

resetLimit as Integer
	Alarm time reset limit.

Example

Dim resetLimit as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
resetLimit = NSL.AlarmLogResetLimit(alarmPgm)

AlarmLogResetCount

resetCount = NSBSystemLib.AlarmLogResetCount(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

resetCount as Integer
	The number of times the alarm as been automatically reset.

Example

Dim resetCount as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
resetCount = NSL.AlarmLogResetCount(alarmPgm)

AlarmLogCommand

alarmCmd = NSBSystemLib.AlarmLogCommand(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

alarmCmd as Integer
	Alarm command.

Example

Dim alarmCmd as Integer
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmCmd = NSL.AlarmLogCommand(alarmPgm)

AlarmLogMessage

alarmMsg = NSBSystemLib.AlarmLogMessage(alarmPgm)

Parameter

alarmPgm as String
	Alarm program.

Returns

alarmMsg as String
	Alarm message.

Example

Dim alarmMsg as String
Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmMsg = NSL.AlarmLogMessage(alarmPgm)

ClearAlarmLog

alarmPgm = NSBSystemLib.ClearAlarmLog()

Returns

alarmPgm as String

Example

Dim alarmPgm as String

alarmPgm = "NSBAlarmProxy1"
alarmPgm = NSL.ClearAlarmLog()

Database Functions

FindDatabase

dbID = NSBSystemLib.FindDatabase(cardNo, dbName)

Parameters

cardNo as Integer
	This value will most likely be 0.
dbName as String
	Database name.

Returns

dbID as Integer
	dbID if the named database is found.
	0 if the named database is not found.

Example

Dim dbID as Integer
Dim cardNo as Integer
Dim dbName as String

cardNo = 0
dbName = "NSBRuntime"
dbID = NSL.FindDatabase(cardNo, dbName)

DatabaseInfo

dbName = NSBSystemLib.DatabaseInfo(cardNo, dbID)

Parameters

cardNo as Integer
dbID as Integer

Returns

dbName as String

Example

Dim cardNo as Integer
Dim dbID as Integer
Dim dbName as String
Dim dbVersion as Integer
Dim dbCreationDate as Integer
Dim dbModificationDate as Integer
Dim dbBackupDate as Integer
Dim dbModificationNumber as Integer
Dim dbAppInfoID as Integer
Dim dbSortInfoID as Integer
Dim dbType as Integer
Dim dbCreatorID as Integer

cardNo = 0
dbName = "NSBRuntime"
dbID = NSBNSL.FindDatabase(cardNo, dbName)
If dbID <> 0 Then
    dbName = NSL.DatabaseInfo(cardNo, dbID)
    If dbName <> "" Then
        dbVersion = NSL.DatabaseVersion()
        dbCreationDate = NSL.DatabaseCreationDate()
        dbModificationDate = NSL.DatabaseModificationDate()
        dbBackupDate = NSL.DatabaseBackupDate()
        dbModificationNumber = NSL.DatabaseModificationNumber()
        dbAppInfoID = NSL.DatabaseAppInfoID()
        dbSortInfoID = NSL.DatabaseSortInfoID()
        dbType = NSL.DatabaseType()
        dbCreatorID = NSL.DatabaseCreatorID()
    EndIf
EndIf

DatabaseName

dbName = NSBSystemLib.DatabaseName()

Returns

dbName as String

Example

See the example provided with the DatabaseInfo() function.

DatabaseAttributes

dbAttributes = NSBSystemLib.DatabaseAttributes()

Returns

dbAttributes as Integer
	The attributes value is a bitmapped value.  The following
	list contains the bit mask values available:
	    Bit  0  (0x0001) - dmHdrAttrResDB
	    Bit  1  (0x0002) - dmHdrAttrReadOnly
	    Bit  2  (0x0004) - dmHdrAttrAppInfoDirty
	    Bit  3  (0x0008) - dmHdrAttrBackup
	    Bit  4  (0x0010) - dmhdrAttrOKToInstallNewer
	    Bit  5  (0x0020) - dmHdrAttrResetAfterInstall
	    Bit  6  (0x0040) - dmHdrAttrCopyPrevention
	    Bit  7  (0x0080) - dmHdrAttrStream
	    Bit  8  (0x0100) - dmHdrAttrHidden
	    Bit  9  (0x0200) - hmHdrAttrLaunchableData
	    Bit 15  (0x8000) - dmHdrAttrOpen

Example

See the example provided with the DatabaseInfo() function.

DatabaseVersion

dbVersion = NSBSystemLib.DatabaseVersion()

Returns

dbVersion as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseCreationDate

dbCreationDate = NSBSystemLib.DatabaseCreationDate()

Returns

dbCreationDate as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseModificationDate

dbModificationDate = NSBSystemLib.DatabaseModificationDate()

Returns

dbModificationDate as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseBackupDate

dbBackupDate = NSBSystemLib.DatabaseBackupDate()

Returns

dbBackupDate as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseModificationNumber

dbModificationNumber = NSBSystemLib.DatabaseModificationNumber()

Returns

dbModificationNumber as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseAppInfoID

dbAppInfoID = NSBSystemLib.DatabaseAppInfoID()

Returns

dbAppInfoID as Integer
	0 if this optional block is not available.

Example

See the example provided with the DatabaseInfo() function.

DatabaseSortInfoID

dbSortInfoID = NSBSystemLib.DatabaseSortInfoID()

Returns

dbSortInfoID as Integer
	0 if this optional sort table is not available.

Example

See the example provided with the DatabaseInfo() function.

DatabaseType

dbType = NSBSystemLib.DatabaseType()

Returns

dbType as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseCreatorID

dbCreatorID = NSBSystemLib.DatabaseCreatorID()

Returns

dbCreatorID as Integer

Example

See the example provided with the DatabaseInfo() function.

DatabaseTotalSize

dbTotalSize = NSBSystemLib.DatabaseTotalSize(cardNo, dbID)

Parameters

cardNo as Integer
dbID as Integer

Returns

dbTotalSize as Integer

Example

Dim cardNo as Integer
Dim dbID as Integer
Dim dbTotalSize as Integer
Dim dbNumRecords as Integer
Dim dbDataSize as Integer

cardNo = 0
dbName = "NSBRuntime"
dbID = NSL.FindDatabase(cardNo, dbName)
If dbID <> 0 Then
    dbTotalSize = NSL.DatabaseSize(cardNo, dbID)
    dbNumRecords = NSL.DatabaseNumRecords()
    dbDataSize = NSL.DatabaseDataSize()
EndIf

DatabaseNumRecords

dbNumRecords = NSBSystemLib.DatabaseNumRecords()

Returns

dbNumRecords as Integer

Example

See the example provided with the DatabaseTotalSize() function.

DatabaseDataSize

dbDataSize = NSBSystemLib.DatabaseDataSize()

Returns

dbDataSize as Integer

Example

See the example provided with the DatabaseTotalSize() function.

DeleteDatabase

status = NSBSystemLib.DeleteDatabase(cardNo, dbID)

Parameters

cardNo as Integer
dbID as Integer

Returns

status as Integer
	0 = successful
	257 = memErrChunkLocked
	258 = memErrNotEnoughSpace
	259 = memErrInvalidParam
	517 = dmErrDatabaseOpen
	518 = dmErrCantOpen
	519 = dmErrCantFind
	526 = dmErrROMBased

Example

Dim cardNo as Integer
Dim dbID as Integer
Dim status as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
If dbID <> 0 Then
    status = NSL.DeleteDatabase(cardNo, dbID)
EndIf

GetNextDatabaseByTypeCreator

dbID = NSBSystemLib.GetNextDatabaseByTypeCreator(newSearch, dbType, dbCreatorID, onlyLatestVersion)

Parameters

newSearch as Integer
	0 = continue searching for databases
	1 = start a new search
dbType as Integer
	Integer database type.
	0 = wildcard search.
dbCreatorID as Integer
	Integer Creator ID.
	0 = wildcard search.
onlyLatestVersion as Integer
	0 = return all versions.
	1 = return only the latest database version for
	    supplied type and Creator ID.

Returns

dbID as Integer
	dbID (LocalID) of the database.

Example

Dim dbID as Integer
Dim newSearch as Integer
Dim dbType as Integer
Dim dbCreatorID as Integer
Dim onlyLatestVersion as Integer
Dim dbCardNo as Integer
Dim dbName as String

onlyLatestVersion = 0
dbType = NSL.String4ToInt("libr")
dbCreatorID = 0
newSearch = 1
dbID = 1
Do While dbID <> 0
    dbID = NSL.GetNextDatabaseByTypeCreator(newSearch, _
                dbType, dbCreatorID, onlyLatestVersion)
    If dbID <> 0 Then
        dbCardNo = NSL.DatabaseCardNo()
        dbName = NSL.DatabaseInfo(dbCardNo, dbID)
    End If
    newSearch = 0
Loop

DatabaseCardNo

dbCardNo = NSBSystemLib.DatabaseCardNo()

Returns

dbCardNo as Integer

Example

See the example provided with the
GetNextDatabaseByTypeCreator() function.

NumDatabases

nbr = NSBSystemLib.NumDatabases(cardNo)

Parameter

cardNo as Integer

Returns

nbr as Integer

Example

Dim nbr as Integer
Dim cardNo as Integer

cardNo = 0
nbr = NSL.NumDatabases(cardNo)

NumCards

nbr = NSBSystemLib.NumCards()

Returns

nbr as Integer

Example

Dim nbr as Integer
nbr = NSL.NumCards()

GetDatabase

dbID = NSBSystemLib.GetDatabase(cardNo, index)

Parameters

cardNo as Integer
index as Integer

Returns

dbID as Integer
	0 = Invalid index

Example

Dim nbr as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim index as Integer
Dim dbName as String

cardNo = 0
nbr = NSL.NumDatabases(cardNo)
index = 0
Do While index < nbr
    dbID = NSL.GetDatabase(cardNo, index)
    If dbID <> 0 Then
        dbName = NSL.DatabaseInfo(cardNo, dbID)
    End If
    index = index + 1
Loop

SetDatabaseName

status = NSBSystemLib.SetDatabaseName(cardNo, dbID, dbName)

Parameters

cardNo as Integer
dbID as Integer
dbName as String

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbName as String

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbName = "oldNSBAlarmProxy5"
status = NSL.SetDatabaseName(cardNo, dbID, dbName)

SetDatabaseAttributes

status = NSBSystemLib.SetDatabaseAttributes(cardNo, dbID, dbAttributes)

Parameters

cardNo as Integer
dbID as Integer
dbAttributes as Integer
	The attributes value is a bitmapped value.  The following
	list contains the bit mask values available:
	    Bit  0  (0x0001) - dmHdrAttrResDB
	    Bit  1  (0x0002) - dmHdrAttrReadOnly
	    Bit  2  (0x0004) - dmHdrAttrAppInfoDirty
	    Bit  3  (0x0008) - dmHdrAttrBackup
	    Bit  4  (0x0010) - dmhdrAttrOKToInstallNewer
	    Bit  5  (0x0020) - dmHdrAttrResetAfterInstall
	    Bit  6  (0x0040) - dmHdrAttrCopyPrevention
	    Bit  7  (0x0080) - dmHdrAttrStream
	    Bit  8  (0x0100) - dmHdrAttrHidden
	    Bit  9  (0x0200) - hmHdrAttrLaunchableData
	    Bit 15  (0x8000) - dmHdrAttrOpen

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbAttributes as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbAttributes = 2
status = NSL.SetDatabaseAttributes(cardNo, dbID, dbAttributes)

SetDatabaseVersion

status = NSBSystemLib.SetDatabaseVersion(cardNo, dbID, dbVersion)

Parameters

cardNo as Integer
dbID as Integer
dbVersion as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbVersion as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbVersion = 6
status = NSL.SetDatabaseVersion(cardNo, dbID, dbVersion)

SetDatabaseCreationDate

status = NSBSystemLib.SetDatabaseCreationDate(cardNo, dbID, dbCreationDate)

Parameters

cardNo as Integer
dbID as Integer
dbCreationDate as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbCreationDate as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbCreationDate = NSL.SystemTime("", "", 0, 0)
status = NSL.SetDatabaseCreationDate(cardNo, dbID, _
                                    dbCreationDate)

SetDatabaseModificationDate

status = NSBSystemLib.SetDatabaseModificationDate(cardNo, dbID, dbModificationDate)

Parameters

cardNo as Integer
dbID as Integer
dbModificationDate as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbModificationDate as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbModificationDate = NSL.SystemTime("", "", 0, 0)
status = NSL.SetDatabaseModificationDate(cardNo, dbID, _
                                        dbModificationDate)

SetDatabaseBackupDate

status = NSBSystemLib.SetDatabaseBackupDate(cardNo, dbID, dbBackupDate)

Parameters

cardNo as Integer
dbID as Integer
dbBackupDate as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbBackupDate as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbBackupDate = NSL.SystemTime("", "", 0, 0)
status = NSL.SetDatabaseModificationDate(cardNo, dbID, _
                                        dbBackupDate)

SetDatabaseModificationNumber

status = NSBSystemLib.SetDatabaseModificationNumber(cardNo, dbID, dbModificationNumber)

Parameters

cardNo as Integer
dbID as Integer
dbModificationNumber as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbModificationNumber as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbModificationNumber = 0
status = NSL.SetDatabaseModificationNumber(cardNo, dbID, _
                                          dbModificationNumber)

SetDatabaseAppInfoID

status = NSBSystemLib.SetDatabaseAppInfoID(cardNo, dbID, dbAppInfoID)

Parameters

cardNo as Integer
dbID as Integer
dbAppInfoID as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbAppInfoID as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbAppInfoID = 0
status = NSL.SetDatabaseAppInfoID(cardNo, dbID, _
                                 dbAppInfoID)

SetDatabaseSortInfoID

status = NSBSystemLib.SetDatabaseSortInfoID(cardNo, dbID, dbSortInfoID)

Parameters

cardNo as Integer
dbID as Integer
dbSortInfoID as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbSortInfoID as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbSortInfoID = 0
status = NSL.SetDatabaseSortInfoID(cardNo, dbID, _
                                 dbSortInfoID)

SetDatabaseType

status = NSBSystemLib.SetDatabaseType(cardNo, dbID, dbType)

Parameters

cardNo as Integer
dbID as Integer
dbType as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbType as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbType = String4ToInt("appl")
status = NSL.SetDatabaseType(cardNo, dbID, dbType);

SetDatabaseCreatorID

status = NSBSystemLib.SetDatabaseCreatorID(cardNo, dbID, dbCreatorID)

Parameters

cardNo as Integer
dbID as Integer
dbCreatorID as Integer

Returns

status as Integer
	0 = success
	515 = dmErrInvalidParam
	537 = dmErrAlreadyExists
	538 = InvalidDatabaseName

Example

Dim status as Integer
Dim dbID as Integer
Dim cardNo as Integer
Dim dbCreatorID as Integer

cardNo = 0
dbName = "NSBAlarmProxy5"
dbID = NSL.FindDatabase(cardNo, dbName)
dbCreatorID = String4ToInt("TEST")
status = NSL.SetDatabaseCreatorID(cardNo, dbID, dbCreatorID);

Event Functions

GetEvent

eventType = NSBSystemLib.GetEvent(timeoutTicks, consumePenEvents, returnVirtualEvents)

Parameters

timeoutTicks as Integer
	The number of system ticks to wait before
			returning.
consumePenEvents as Integer
	0 = do not consume pen events
	1 = consume pen events
	  This function calls the PalmOS EvtGetEvent function.
	  EvtGetEvent removes events from the events queue.  In
	  order for these events to still be available for other
	  processing, this shared library function requeues the
	  events that it detects.  This may not be desired if
	  this function is used for capturing pen events for
	  drawing.  When consumePenEvents is set to 1, the pen
	  events are not requeued but the pen data is still
	  available.
returnVirtualEvents as Integer
	0 = do not return with virtual key events
	1 = return with virtual key events
	  Virtual key events are events generated by the PalmOS
	  system or other third party system level features.
	  These events include things like low battery warning,
	  backlight change of state, etc.  For the most part,
	  virtual key events should not be returned.  If they
	  are returned, it is probably wise to let the system
	  handle them by calling this library's SysHandleEvent()
	  function.

Returns

eventType as Integer
	-1 if no event was available within the
			timeout specified.
	0 = nilEvent
	1 = penDownEvent
	      Retrieve pen coordintates with:
	          GlobalX(), and GlobalY()
	2 = penUpEvent
	      Retrieve pen coordintates with:
	          GlobalX(), GlobalY()
	      Retrieve pen stroke coordinates with:
	          GlobalStartX(), GlobalStartY(),
	          GlobalEndX(), and GlobalEndY()
	3 = penMoveEvent
	      Retrieve pen coordintates with:
	          GlobalX(), and GlobalY()
	4 = keyDownEvent
	      Retrieve key data with:
	          KeyEventChr(), KeyEventKeyCode(),
	          and KeyEventModifiers()
	5 = winEnterEvent
	6 = winExitEvent
	7 = ctlEnterEvent
	8 = ctlExitEvent
	9 = ctlSelectEvent
	10 = ctlRepeatEvent
	11 = lstEnterEvent
	12 = lstSelectEvent
	13 = lstExitEvent
	14 = popSelectEvent
	15 = fldEnterEvent
	16 = fldHeightChangedEvent
	17 = fldChangedEvent
	18 = tblEnterEvent
	19 = tblSelectEvent
	20 = daySelectEvent
	21 = menuEvent
	22 = appStopEvent
	21 = frmOpenEvent
	22 = frmGotoEvent
	23 = frmUpdateEvent
	24 = frmSaveEvent
	25 = frmCloseEvent
	26 = frmTitleEnterEvent
	27 = frmTitleSelectEvent
	28 = tblExitEvent
	29 = sclEnterEvent
	30 = sclExitEvent
	31 = sclRepeatEvent
	35 = tsmConfirmEvent
	36 = tsmFepButtonEvent
	37 = tsmFepModeEvent
	
	2048 = menuCmdBarOpenEvent
	2049 = menuOpenEvent
	2050 = menuCloseEvent
	2051 = frmGadgetEnterEvent
	2052 = frmGadgetMiscEvent
	
	4096 = firstINetLibEvent
	4352 = firstWebLibEvent
	
	24576 = firstUserEvent

Example

Dim eventType as Integer
Dim timeoutTicks as Integer

NSL.FlushEvents()
eventType = 0
Do While eventType <= 0
    'do something
    eventType = NSL.GetEvent(timeoutTicks, 0, 0)
Loop

SysHandleEvent

NSBSystemLib.SysHandleEvent()

Example

NSL.SysHandleEvent()

FlushEvents

NSBSystemLib.FlushEvents()

Example

NSL.FlushEvents()

KeyEventChr

keyChr = NSBSystemLib.KeyEventChr()

Returns

keyChr as Integer

Example

Dim keyChr as Integer
keyChr = NSL.KeyEventChr()

KeyEventKeyCode

keyCode = NSBSystemLib.KeyEventKeyCode()

Returns

keyCode as Integer

Example

Dim keyCode as Integer
keyCode = NSL.KeyEventKeyCode()

KeyEventModifiers

modifiers = NSBSystemLib.KeyEventModifiers()

Returns

modifiers as Integer

Example

Dim modifiers as Integer
modifiers = NSL.KeyEventModifiers()

Field and Form Functions

A number of these functions allow the use of 0 as the first argument to refer to the current field. Starting with the LifeDrive, Tungsten E2 and some Treo models, this feature is no longer supported. The underlying Palm OS call, FrmGetFocus, no longer returns a valid value. To correct for this, you will need to keep track the of current field yourself.

Here is how to program around this:

1. In your Startup code create a global to contain the object id of the last field that had focus :

    Sub main()
        Global focus as Integer
        LoadLibrary "NSBSystemLib","NSL"
    End Sub

2. Double-click each field to create a "click" event subroutine. Set the value of your new global to the value of your field's object id. Its really convenient that the subroutine has the object id in it's name! ;-) :

    Sub object1005()
        focus = 1005
    End Sub

    Sub object1023()
        focus = 1023
    End Sub

    Sub object1025()
        focus = 1025
    End Sub

3. Now, since we know the last field with focus, we can use the object id instead of trying to get the current field with focus (which we know doesn't work on some newer devices):

    Sub object1015()
        NSL.FIeldInsert focus, "1"
    End Sub

Granted, it's not quite as elegant as the way NSL used to work on older devices but it's not too bad.

ControlHitControl

NSBSystemLib.ControlHitControl objID

Parameter:

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Example

Dim objID as Integer

objID = 1008
NSL.ControlHitControl objID

FieldCopy

NSBSystemLib.FieldCopy objID

Parameter:

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Example

Dim objID as Integer

objID = 1008
NSL.FieldCopy objID

FieldCut

NSBSystemLib.FieldCut objID

Parameter:

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Example

Dim objID as Integer

objID = 1008
NSL.FieldCut objID

FieldInsert

NSBSystemLib.FieldInsert objID, insString

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

insString as String

Example

Dim objID as Integer
Dim insString as String

objID = 1008
insString = "Insert This!"
NSL.FieldInsert objID, insString

FieldPaste

NSBSystemLib.FieldPaste objID

Parameter:

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Example

Dim objID as Integer

objID = 1008
NSL.FieldPaste objID

FieldUndo

NSBSystemLib.FieldUndo objID

Parameter:

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Example

Dim objID as Integer

objID = 1008
NSL.FieldUndo objID

FieldGetInsPtPosition

pos = NSBSystemLib.FieldGetInsPtPosition(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

pos as Integer

Example

Dim pos as Integer
Dim objID as Integer

objID = 1008
pos = NSL.FieldGetInsPtPosition(objID)

FieldGetSelection

startPos = NSBSystemLib.FieldGetSelection(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

startPos as Integer

Example

Dim startPos as Integer
Dim objID as Integer
Dim endPos as Integer

objID = 1008
startPos = NSL.FieldGetSelection(objID)
endPos = NSL.GlobalEndPos()

FieldAnyDirty

dirty = NSBSystemLib.FieldAnyDirty()

Returns

dirty as Integer

Example

Dim dirty as Integer
dirty = NSL.FieldAnyDirty()

FieldDirty

dirty = NSBSystemLib.FieldDirty(objID)

Parameter

objID as Integer
	0 = check field that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

dirty as Integer

Example

Dim dirty as Integer
Dim objID as Integer

objID = 1008
dirty = NSL.FieldDirty(objID)

FieldSetDirty

NSBSystemLib.FieldSetDirty objID, dirty

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

dirty as Integer
	0 = not dirty
	1 = dirty

Example

Dim objID as Integer
Dim dirty as Integer

objID = 1008
dirty = 1
NSL.FieldSetDirty objID, dirty

FieldSetAllDirty

NSBSystemLib.FieldSetAllDirty dirty

Parameter:

dirty as Integer
	0 = not dirty
	1 = dirty

Example

Dim dirty as Integer
NSL.FieldSetAllDirty dirty

FieldSetSelection

NSBSystemLib.FieldSetSelection objID, startPos, endPos

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

startPos as Integer

endPos as Integer

Example

Dim objID as Integer
Dim startPos as Integer
Dim endPos as Integer

objID = 1008
NSL.FieldSetSelection objID, startPos, endPos

FieldSetInsertionPoint

NSBSystemLib.FieldSetInsertionPoint objID, pos

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

pos as Integer

Example

Dim objID as Integer
Dim pos as Integer

objID = 1008
NSL.FieldSetInsertionPoint objID, pos

FieldSetInsPtPosition

NSBSystemLib.FieldSetInsPtPosition objID, pos

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

pos as Integer

Example

Dim objID as Integer
Dim pos as Integer

objID = 1008
NSL.FieldSetInsPtPosition objID, pos

FieldGetAttributes

attributes = NSBSystemLib.FieldGetAttributes(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

attributes as Integer
	A bitmapped integer with the following values:
	   bit 0 - reserved
	   bit 1 - numeric
	   bit 2 - hasScrollBar
	   bit 3 - autoShift
	   bits 4 and 5 - justification
	       00 - leftAlign
	       01 - centerAlign (may not be supported)
	       10 - rightAlign
	   bits 6 and 7 - underlined
	       00 - noUnderline
	       01 - grayUnderline
	       10 - solidUnderline
	   bit 8 - dirty
	   bit 9 - insPtVisible
	   bit 10 - dynamicSize
	   bit 11 - hasFocus
	   bit 12 - singleLine
	   bit 13 - editable
	   bit 14 - visible
	   bit 15 - usable

Example

Dim attributes as Integer
Dim objID as Integer

objID = 1008
attributes = NSL.FieldGetAttributes(objID)

FieldSetAttributes

NSBSystemLib.FieldSetAttributes objID, attributes

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

attributes as Integer
	A bitmapped integer with the following values:
	   bit 0 - reserved
	   bit 1 - numeric
	   bit 2 - hasScrollBar
	   bit 3 - autoShift
	   bits 4 and 5 - justification
	       00 - leftAlign
	       01 - centerAlign (may not be supported)
	       10 - rightAlign
	   bits 6 and 7 - underlined
	       00 - noUnderline
	       01 - grayUnderline
	       10 - solidUnderline
	   bit 8 - dirty
	   bit 9 - insPtVisible
	   bit 10 - dynamicSize
	   bit 11 - hasFocus
	   bit 12 - singleLine
	   bit 13 - editable
	   bit 14 - visible
	   bit 15 - usable

Example

Dim objID as Integer
Dim attributes as Integer

objID = 1008
NSL.FieldSetAttributes objID, attributes

FieldGetFont

fontId = NSBSystemLib.FieldGetFont(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

fontId as Integer

Example

Dim fontId as Integer
Dim objID as Integer

objID = 1008
fontId = NSL.FieldGetFont(objID)

FieldSetFont

NSBSystemLib.FieldSetFont objID, fontId

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

fontId as Integer

Example

Dim objID as Integer
Dim fontId as Integer

objID = 1008
fontId = 2  'large font
NSL.FieldSetFont objID, fontId

FieldGetScrollPosition

position = NSBSystemLib.FieldGetScrollPosition(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

position as Integer

Example

Dim position as Integer
Dim objID as Integer

objID = 1008
position = NSL.FieldGetScrollPosition(objID)

FieldSetScrollPosition

NSBSystemLib.FieldSetScrollPosition objID, position

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

position as Integer

Example

Dim objID as Integer
Dim position as Integer

objID = 1008
position = 20
NSL.FieldSetScrollPosition objID, position

FieldGetScrollValues

totalLines = NSBSystemLib.FieldGetScrollValues(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

totalLines as Integer

Example

Dim totalLines as Integer
Dim objID as Integer
Dim position as Integer
Dim height as Integer

objID = 1008
totalLines = NSL.FieldGetScrollValues(objID)
position = GlobalStartPos()
height = GlobalHeight()

FieldGetVisibleLines

lines = NSBSystemLib.FieldGetVisibleLines(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

lines as Integer

Example

Dim lines as Integer
Dim objID as Integer

objID = 1008
lines = NSL.FieldGetVisibleLines(objID)

FieldGetNumberOfBlankLines

lines = NSBSystemLib.FieldGetNumberOfBlankLines(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

lines as Integer

Example

Dim lines as Integer
Dim objID as Integer

objID = 1008
lines = NSL.FieldGetNumberOfBlankLines(objID)

FieldScrollable

yesNo = NSBSystemLib.FieldScrollable(objID, direction)

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.
direction as Integer
	0 = up
	1 = down

Returns

yesNo as Integer

Example

Dim yesNo as Integer
Dim objID as Integer
Dim direction as Integer

objID = 1008
yesNo = NSL.FieldScrollable(objID, direction)

FieldScrollField

NSBSystemLib.FieldScrollField objID, nbrLines, direction

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

nbrLines as Integer

direction as Integer
	0 = up
	1 = down

Example

Dim objID as Integer
Dim nbrLines as Integer
Dim direction as Integer

objID = 1008
NSL.FieldScrollField objID, nbrLines, direction

FieldSetBounds

NSBSystemLib.FieldSetBounds objID, topLeftX, topLeftY, width, height

Parameters

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

topLeftX as Integer

topLeftY as Integer

width as Integer

height as Integer

Example

Dim objID as Integer
Dim topLeftX as Integer
Dim topLeftY as Integer
Dim width as Integer
Dim height as Integer

objID = 1008
NSL.FieldSetBounds objID, topLeftX, topLeftY, width, height

FormGetNumberOfObjects

nbr = NSBSystemLib.FormGetNumberOfObjects()

Returns

nbr as Integer
	-1 if no form is active

Example

Dim nbr as Integer
nbr = NSL.FormGetNumberOfObjects()

FormGetObjectBounds

x = NSBSystemLib.FormGetObjectBounds(objID)

Parameter

objID as Integer
	0 = use object that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

x as Integer
	-1 if the object is invalid or no object has focus

Example

Dim x as Integer
Dim objID as Integer
Dim y as Integer
Dim width as Integer
Dim height as Integer

objID = 1008
x = NSL.FormGetObjectBounds(objID)
y = NSL.GlobalY()
width = NSL.GlobalWidth()
height = NSL.GlobalHeight()

FormGetObjectPosition

x = NSBSystemLib.FormGetObjectPosition(objID)

Parameter

objID as Integer
	0 = use object that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

x as Integer
	-1 if the object is invalid or no object has focus

Example

Dim x as Integer
Dim objID as Integer
Dim y as Integer

objID = 1008
x = NSL.FormGetObjectPosition(objID)
y = NSL.GlobalY

FormGetObjectType

type = NSBSystemLib.FormGetObjectType(objID)

Parameter

objID as Integer
	0 = use object that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

type as Integer
	-1 if the object is invalid or no object has focus
	 0 = frmFieldObj
	 1 = frmControlObj
	 2 = frmListObj
	 3 = frmTableObj
	 4 = frmBitmapObj
	 5 = frmLineObj
	 6 = frmFrameObj
	 7 = frmRectangleObj
	 8 = frmLabelObj
	 9 = frmTitleObj
	10 = frmPopupObj
	11 = frmGraffitiStateObj
	12 = frmGadgetObj
	13 = frmScrollbarObj

Example

Dim type as Integer
Dim objID as Integer
objID = 1008
type = NSL.FormGetObjectType(objID)

FormSetObjectPosition

NSBSystemLib.FormSetObjectPosition objID, x, y

Parameters

objID as Integer
	0 = use object that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

x as Integer

y as Integer

Example

Dim objID as Integer
Dim x as Integer
Dim y as Integer

objID = 1008
x = 120
y = 40
NSL.FormSetObjectPosition objID, x, y

FormSetObjectBounds

NSBSystemLib.FormSetObjectBounds objID, topLeftX, topLeftY, width, height

Parameters

objID as Integer
	0 = use object that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

topLeftX as Integer

topLeftY as Integer

width as Integer

height as Integer

Example

Dim objID as Integer
Dim topLeftX as Integer
Dim topLeftY as Integer
Dim width as Integer
Dim height as Integer

objID = 1008
NSL.FormSetObjectBounds objID, topLeftX, topLeftY, width, height

FormGetTitle

title = NSBSystemLib.FormGetTitle()

Returns

title as String

Example

Dim title as String
title = NSL.FormGetTitle()

FormReplaceTitle

NSBSystemLib.FormReplaceTitle title, forceLength

Parameters

title as String

forceLength as Integer

Example

Dim title as String
Dim forceLength as Integer

NSL.FormReplaceTitle title, forceLength

ListGetTopItem

topItem = NSBSystemLib.ListGetTopItem(objID)

Parameter

objID as Integer

Returns

topItem as Integer

Example

Dim topItem as Integer
Dim objID as Integer

topItem = NSL.ListGetTopItem(objID)

ListSetTopItem

NSBSystemLib.ListSetTopItem objID, topItem

Parameters

objID as Integer

topItem as Integer

Example

Dim objID as Integer
Dim topItem as Integer

NSL.ListSetTopItem objID, topItem

ListGetVisibleItems

visibleItems = NSBSystemLib.ListGetVisibleItems(objID)

Parameter

objID as Integer

Returns

visibleItems as Integer

Example

Dim visibleItems as Integer
Dim objID as Integer

visibleItems = NSL.ListGetVisibleItems(objID)

ListScrollList

result = NSBSystemLib.ListScrollList(objID, direction, nbrItems)

Parameters

objID as Integer
direction as Integer
	0 = up
	1 = down
nbrItems as Integer

Returns

result as Integer
	0 = if the list box could not be scrolled
	1 = if the list box was scrolled successfully

Example

Dim result as Integer
Dim objID as Integer
Dim direction as Integer
Dim nbrItems as Integer

result = NSL.ListScrollList(objID, direction, nbrItems)

Font Support

FontGetFont

fontId = NSBSystemLib.FontGetFont()

Returns

fontId as Integer

Example

Dim fontId as Integer
fontId = NSL.FontGetFont()

FontSetFont

oldFontId = NSBSystemLib.FontSetFont(fontId)

Parameter

fontId as Integer

Returns

oldFontId as Integer

Example

Dim oldFontId as Integer
Dim fontId as Integer

oldFontId = NSL.FontSetFont(fontId)

FontSelect

fontId = NSBSystemLib.FontSelect()

Returns

fontId as Integer

Example

Dim fontId as Integer
fontId = NSL.FontSelect()

FontCharWidth

width = NSBSystemLib.FontCharWidth(charString)

Parameter

charString as String

Returns

width as Integer

Example

Dim width as Integer
Dim charString as String

width = NSL.FontCharWidth(charString)

FontCharsWidth

width = NSBSystemLib.FontCharsWidth(charString, optionalLen)

Parameters

charString as String
optionalLen as Integer
	0 = use actual string length

Returns

width as Integer

Example

Dim width as Integer
Dim charString as String
Dim optionalLen as Integer

width = NSL.FontCharsWidth(charString, optionalLen)

FontWidthToOffset

offset = NSBSystemLib.FontWidthToOffset(charString, optionalLen, width)

Parameters

charString as String
optionalLen as Integer
	0 = use actual string length
width as Integer

Returns

offset as Integer

Example

Dim offset as Integer
Dim charString as String
Dim optionalLen as Integer
Dim width as Integer

offset = NSL.FontWidthToOffset(charString, optionalLen, width)

FontCharsInWidth

length = NSBSystemLib.FontCharsInWidth(charString, optionalLen, width)

Parameters

charString as String
optionalLen as Integer
	0 = use actual string length
width as Integer

Returns

length as Integer

Example

Dim length as Integer
Dim charString as String
Dim optionalLen as Integer
Dim width as Integer

length = NSL.FontCharsInWidth(charString, optionalLen, width)

FontWordWrap

length = NSBSystemLib.FontWordWrap(charString, width)

Parameters

charString as String
width as Integer
	0 = use actual string length

Returns

length as Integer

Example

Dim length as Integer
Dim charString as String
Dim width as Integer

length = NSL.FontWordWrap(charString, width)

HotSync Data

SyncUserName

userName = NSBSystemLib.SyncUserName()

Returns

userName as String

Example

Dim userName as String
userName = NSL.SyncUserName()

SuccessfulSync

syncDate = NSBSystemLib.SuccessfulSync()

Returns

syncDate as Integer

Example

Dim syncDate as Integer
syncDate = NSL.SuccessfulSync()

LastSync

syncDate = NSBSystemLib.LastSync()

Returns

syncDate as Integer

Example

Dim syncDate as Integer
syncDate = NSL.LastSync()

Localization Functions

LocalizeNumber

localNbrStr = NSBSystemLib.LocalizeNumber(stdNbrStr)

Parameter

stdNbrStr as String

Returns

localNbrStr as String

Example

Dim localNbrStr as String
Dim stdNbrStr as String

stdNbrStr = "4,123.56"
localNbrStr = NSL.LocalizeNumber(stdNbrStr)

DelocalizeNumber

stdNbrStr = NSBSystemLib.DelocalizeNumber(localNbrStr)

Parameter

localNbrStr as String

Returns

stdNbrStr as String

Example

Dim stdNbrStr as String
Dim localNbrStr as String

locNbrStr = "4.123,56"
stdNbrStr = NSL.DelocalizeNumber(localNbrStr)

LocalizeDate

localDateStr = NSBSystemLib.LocalizeDate(stdDateStr, ToDateFormat, longDateFormat)

Parameters

stdDateStr as String
	The date string may also contain the time.  Time values
	will be ignored.
ToDateFormat as Integer
	0 = stdDateStr format is "MM/DD/YY[YY]"
	1 = stdDateStr format is "[YY]YY/MM/DD"
longDateFormat as Integer
	0 = use short date format preference
	1 = user long date format preference

Returns

localDateStr as String

Example

Dim localDateStr as String
Dim stdDateStr as String
Dim ToDateFormat as Integer
Dim longDateFormat as Integer

stdDateStr = DateMMDDYY(Today())
ToDateFormat = 0
longDateFormat = 0
localDateStr = NSL.LocalizeDate(stdDateStr, ToDateFormat, longDateFormat)

Preference Functions

GetAppPreferences

data = NSBSystemLib.GetAppPreferences(pgmName, prefId, saved)

Parameters

pgmName as String
	Program Name - This is case sensitive
prefId as Integer
	Preference ID
saved as Integer
	0 = preference does not get restored after a hard reset
	1 = preference does get restored after a hard reset

Returns

data as String

Example

Dim data as String
Dim pgmName as String
Dim prefId as Integer
Dim saved as Integer

pgmName = "SysLibTest"
prefId = 1
saved = 0
data = NSL.GetAppPreferences(pgmName, prefId, saved)

SetAppPreferences

status = NSBSystemLib.SetAppPreferences(pgmName, prefId, data, saved)

Parameters

pgmName as String
	Program Name - This is case sensitive
prefId as Integer
	Preference ID
data as String
saved as Integer
	0 = preference does not get restored after a hard reset
	1 = preference does get restored after a hard reset

Returns

status as Integer
	 0 = Success
	-1 = Invalid program name

Example

Dim status as Integer
Dim pgmName as String
Dim prefId as Integer
Dim data as String
Dim saved as Integer

pgmName = "SysLibTest"
prefId = 1
data = "anything I want!"
saved = 0
status = NSL.SetAppPreferences(pgmName, prefId, data, saved)

GetSysPreference

data = NSBSystemLib.GetSysPreference(prefID)

Parameter

prefID as Integer
	 From Preferences.h in the PalmOS SDK:
	 0 = prefVersion
	 1 = prefCountry
	 2 = prefDateFormat
	 3 = prefLongDateFormat
	 4 = prefWeekStartDay
	 5 = prefTimeFormat
	 6 = prefNumberFormat
	 7 = prefAutoOffDuration
	         prefAutoOffDurationSecs is now preferred
	         (prefAutoOffDuration is in minutes)
	 8 = prefSysSoundLevelV20
	 9 = prefGameSoundLevelV20
	10 = prefAlarmSoundLevelV20
	11 = prefHidePrivateRecordsV33
	12 = prefDeviceLocked
	13 = prefLocalSyncRequiresPassword
	14 = prefRemoteSyncRequiresPassword
	15 = prefSysBatteryKind
	16 = prefAllowEasterEggs
	17 = prefMinutesWestOfGMT
	         deprecated old unsigned minutes EAST of GMT
	18 = prefDaylightSavings
	         deprecated old daylight saving time rule
	19 = prefRonamaticChar
	20 = prefHard1CharAppCreator
	         App creator for hard key #1
	21 = prefHard2CharAppCreator
	22 = prefHard3CharAppCreator
	23 = prefHard4CharAppCreator
	24 = prefCalcCharAppCreator
	25 = prefHardCradleCharAppCreator
	26 = prefLauncherAppCreator
	27 = prefSysPrefFlags
	28 = prefHardCradle2CharAppCreator
	29 = prefAnimationLevel
	
	Additions for PalmOS 3.0:
	-------------------------
	30 = prefSysSoundVolume
		actual amplitude - error beeps and other
	        non-alarm/game sounds
	31 = prefGameSoundVolume
	32 = prefAlarmSoundVolume
	33 = prefBeamReceive
	         not used - use ExgLibControl with ir(Get/Set)
	         ScanningMode instead
	34 = prefCalibrateDigitizerAtReset
	         True makes the user calibrate at soft reset time
	35 = prefSystemKeyboardID
	         ID of the preferred keyboard resource
	36 = prefDefSerialPlugIn
	         creator ID of the default serial plug-in
	
	Additions for PalmOS 3.1:
	-------------------------
	37 = prefStayOnWhenPluggedIn
	38 = prefStayLitWhenPluggedIn
	
	Additions for PalmOS 3.2:
	-------------------------
	39 = prefAntennaCharAppCreator
	         App creator for antenna key
	
	Additions for PalmOS 3.3:
	-------------------------
	40 = prefMeasurementSystem
	         English, Metric, etc.
	
	Additions for PalmOS 3.5:
	-------------------------
	41 = prefShowPrivateRecords
	         returns privateRecordViewEnum
	42 = prefAutoOffDurationSecs
	
	Additions for PalmOS 4.0:
	-------------------------
	43 = prefTimeZone
	         GMT offset in minutes, + for east of GMT, - for west
	44 = prefDaylightSavingAdjustment
	         current DST adjustment in minutes (typically 0 or 60)
	45 = prefAutoLockType
	          Never, on poweroff, after preset delay or at preset time.
	46 = prefAutoLockTime
	          Auto lock preset time or delay.
	47 = prefAutoLockTimeFlag
	          For Minutes or Hours.
	48 = prefLanguage
	          Language spoken in country selected via
	          Setup app/Formats panel
	49 = prefLocale
	          Locale for country selected via Setup app/Formats panel
	50 = prefTimeZoneCountry
	          Country used to specify time zone.
	51 = prefAttentionFlags
	          User prefs for getting user's attention
	52 = prefDefaultAppCreator
	          Default application launched on reset.

Returns

data as Integer

Example

Dim data as Integer
Dim prefID as Integer

prefID = 7   'prefAutoOffDuration - in seconds
data = NSL.GetSysPreference(prefID)

SetSysPreference

NSBSystemLib.SetSysPreference prefID, data

Parameters

prefID as Integer
	See GetSysPreference() for preference ID values

data as Integer

Example

Dim prefID as Integer
Dim data as Integer

prefID = 7   'prefAutoOffDuration - in minutes
data = 3     '3 minutes
NSL.SetSysPreference prefID, data

Progress Manager Functions

ProgressStartDialog

NSBSystemLib.ProgressStartDialog title

Parameter:

title as String
	must be 20 characters or less.

Example

Dim title as String
Dim message as String
Dim stage as Integer
Dim error as Integer
Dim force as Integer
Dim canceled as Integer
Dim strValue as String
Dim resolution as Integer
Dim completeChar as String
Dim incompleteChar as String
Dim percent as Integer
Dim count as Integer

completeChar = "|"
incompleteChar = "."
resolution = 5
count = 100

title = "Progress Test..."
NSL.ProgressStartDialog title
Delay 1
error = 0
stage = 1
Do While stage <= count
    canceled = NSL.ProgressUserCancel()
    If canceled = 1 Then
        Exit Do
    End If
    percent = NSL.ProgressPercent(stage, count)
    strValue = NSL.ProgressPercentString(percent, resolution, _
                                         completeChar, incompleteChar)
    Message = strValue + Chr(10) + Str(percent) _
            + "% complete" + Chr(10) _
            + "stage = " + Str(stage)
    NSL.ProgressUpdateDialog error, message
    stage = stage + 1
    Delay 0.25
Loop

force = 0
Delay 1
NSL.ProgressStopDialog(force)

ProgressStopDialog

NSBSystemLib.ProgressStopDialog force

Parameter:

force as Integer
	0 = do not force an immediate exit of the dialog
	1 = force an immediate exit of the dialog
	    This parameter only has meaning if the dialog is
	    in the process of displaying an error message.  If
	    "force" is set to 0, then the user must press the
	    "OK" button on the dialog before the dialog disappears.

Example

See the example provided with ProgressStartDialog()

ProgressUpdateDialog

NSBSystemLib.ProgressUpdateDialog error, message

Parameters

error as Integer
	0 = no error
	1 = use error processing
	    if "error" is set to 1, the dialog will display the
	    specified message and only present one button - "OK".

message as String
	Message string to display.  This string must be less than
	128 characters in length.

Example

See the example provided with ProgressStartDialog().

ProgressUserCancel

canceled = NSBSystemLib.ProgressUserCancel()

Returns

canceled as Integer

Example

See the example provided with ProgressStartDialog().

ProgressPercent

percent = NSBSystemLib.ProgressPercent(current, count)

Parameters

current as Integer
	Current iteration number of your process loop.
count as Integer
	Number of iterations required to be 100 percent complete.

Returns

percent as Integer

Example

See the example provided with ProgressStartDialog().

ProgressPercentString

strValue = NSBSystemLib.ProgressPercentString(percent, resolution, completeChar, incompleteChar)

Parameters

percent as Integer
	Percent complete - see also ProgressPercent().
resolution as Integer
	The resolution size of the percent string.
	  A resolution of 1 means that there will be 100
	  characters in the percent string.  Every 1% change
	  will be reflected in the percent string.  A
	  resolution of 5 means that there will be 20
	  characters in the percent string.  Every 5% change
	  will be reflected in the percent string.
	  As you can see, the total length of the percent
	  string is calculated as (100 / resolution).  As such,
	  resolution values should be one of the following:
	      1, 2, 4, 5, 10, 20, 25, or 50
completeChar as String
	The character to display for the percent completed.
	    "|" is recommended.
incompleteChar as String
	The character to display for the percent incomplete.
	    "." is recommended.
	  The "completeChar" and "incompleteChar" characters
	  should probably be characters with the exact same
	  pixel width.  Otherwise, the percent string display
	  width will vary as the percentage complete changes.

Returns

strValue as String

Example

See the example provided with ProgressStartDialog().

String Functions

String4ToInt

intValue = NSBSystemLib.String4ToInt(fourByteString)

Parameter

fourByteString as String

Returns

intValue as Integer

Example

Dim intValue as Integer
Dim fourByteString as String

fourByteString = "libr"
intValue = NSL.String4ToInt(fourByteString)

IntToString4

fourByteString = NSBSystemLib.IntToString4(intValue)

Parameter

intValue as Integer

Returns

fourByteString as String

Example

Dim fourByteString as String
Dim intValue as Integer

intValue = 1818845810  '"libr"
fourByteString = NSL.IntToString4(intValue)

DelimitedItem

item = NSBSystemLib.DelimitedItem(inputStr, delimiter, nbr)

Parameters

inputStr as String
	A string containing delimited items.
delimiter as String
	A string containing the delimiter character or characters.
nbr as Integer
	The item number to return.  Item numbers begin with 1.

Returns

item as String
	The delimiter string will be returned if the requested
	item is not present.

Example

Dim item as String
Dim inputStr as String
Dim delimiter as String
Dim nbr as Integer

inputStr = "Joe;Mary;Jane"
delimiter = ";"
nbr = 2
'Returns the string "Mary"
item = NSL.DelimitedItem(inputStr, delimiter, nbr)

FixedWidthString

fixedStr = NSBSystemLib.FixedWidthString(origStr, width, options)

Parameters

origStr as String
	Original string.
width as Integer
	Width in pixels.
options as Integer
	0 = left justify string
	1 = right justify string
	2 = left justify string and use ellipsis (...) if truncated
	3 = right justify string and use ellipsis (...) if truncated
	4 = center justify string and use ellipsis (...) if truncated
	5 = center justify string

Returns

fixedStr as String
	Fixed width string

Example

Dim fixedStr as String
Dim origStr as String
Dim width as Integer
Dim options as Integer

origStr = "This is a test"
width = 80
options = 0
fixedStr = NSL.FixedWidthString(origStr, width, options)

NormalSpacedString

normalStr = NSBSystemLib.NormalSpacedString(origStr)

Parameter

origStr as String

Returns

normalStr as String

Example

Dim normalStr as String
Dim origStr as String

normalStr = NSL.NormalSpacedString(origStr)

System Time Functions

SelectOneTime

newTimeSelected = NSBSystemLib.SelectOneTime(defHour, defMinute, title)

Parameters

defHour as Integer
	Default hour for selection
defMinute as Integer
	Default minute for selection
title as String

Returns

newTimeSelected as Integer

Example

Dim newTimeSelected as Integer
Dim defHour as Integer
Dim defMinute as Integer
Dim title as String

defHour = 10
defMinute = 30
title = "Some Title"
newTimeSelected = NSL.SelectOneTime(defHour, defMinute, title)
If newTimeSelected = 1 Then
    defHour = NSL.GlobalHour()
    defMinute = NSL.GlobalMinute()
End If

IncrementSystemTime

newSysTime = NSBSystemLib.IncrementSystemTime(oldSysTime, hours, minutes, seconds)

Parameters

oldSysTime as Integer
	0 = use current system time.
hours as Integer
minutes as Integer
seconds as Integer

Returns

newSysTime as Integer

Example

Dim newSysTime as Integer
Dim oldSysTime as Integer
Dim hours as Integer
Dim minutes as Integer
Dim seconds as Integer

oldSysTime = 0
hours = 0
minutes = 30
seconds = 0
'Add 30 minutes
newSysTime = NSL.IncrementSystemTime(oldSysTime, hours, minutes, seconds)

SystemTime

sysTime = NSBSystemLib.SystemTime(strDate, strTime, seconds, ToDateFormat)

Parameters

strDate as String
	See the ToDateFormat parameter for date string formats.
strTime as String
	The time string is specified as: "HH[:MM[:SS]][AM|PM|am|pm]"
	(actually, if the character 'P' or 'p' is present, the time
	 will be interpreted as AM/PM format and the hour will be
	 appropriately adjusted).
seconds as Integer
	Increment (or decrement, if negative) the returned systemTime
	by the specified number of seconds.
ToDateFormat as Integer
	0 = strDate string is in MM/DD/YYYY or MM/DD/YY format.
	1 = strDate string is in YYYY/MM/DD or YY/MM/DD format.

Returns

sysTime as Integer
	Integer time as expressed as the number of seconds since
	January 1st, 1904.

Example

Dim sysTime as Integer
Dim strDate as String
Dim strTime as String
Dim seconds as Integer
Dim ToDateFormat as Integer

strDate = ""
strTime = ""
Seconds = 5
ToDateFormat = 0
sysTime = NSL.SystemTime(strDate, strTime, seconds, ToDateFormat)

StringDateTime

strDateTime = NSBSystemLib.StringDateTime(sysTime, ToDateFormat, ToTimeFormat, AMPMFormat)

Parameters

sysTime as Integer
	Integer time as expressed as the number of seconds since
	January 1st, 1904.
ToDateFormat as Integer
	0 = the date string will be in MM/DD/YY format.
	1 = the date string will be in YYYY/MM/DD format.
	2 = the date string will be in MM/DD/YYYY format.
	3 = the date string will be in YY/MM/DD format.
ToTimeFormat as Integer
	0 = the time string will be in HH:MM format.
	1 = the time string will be in HH:MM:SS format.
AMPMFormat as Integer
	0 = no AM/PM indicators will be added.
	1 = " AM" or " PM" indicator will be added and the hour will
	    will be adjusted appropriately.

Returns

strDateTime as String

Example

Dim strDateTime as String
Dim sysTime as Integer
Dim ToDateFormat as Integer
Dim ToTimeFormat as Integer
Dim AMPMFormat as Integer

sysTime = SystemTime("", "", 0, 0)
strDateTime = NSL.StringDateTime(sysTime, ToDateFormat, ToTimeFormat, AMPMFormat)

StringDate

strDate = NSBSystemLib.StringDate(sysTime, ToDateFormat)

Parameters

sysTime as Integer
	Integer time as expressed as the number of seconds since
	January 1st, 1904.
ToDateFormat as Integer
	0 = the date string will be in MM/DD/YY format.
	1 = the date string will be in YYYY/MM/DD format.
	2 = the date string will be in MM/DD/YYYY format.
	3 = the date string will be in YY/MM/DD format.

Returns

strDate as String

Example

Dim strDate as String
Dim sysTime as Integer
Dim ToDateFormat as Integer

sysTime = SystemTime("", "", 0, 0)
strDate = NSL.StringDate(sysTime, ToDateFormat)

StringTime

strTime = NSBSystemLib.StringTime(sysTime, ToTimeFormat, AMPMFormat)

Parameters

sysTime as Integer
	Integer time as expressed as the number of seconds since
	January 1st, 1904.
ToTimeFormat as Integer
	0 = the time string will be in HH:MM format.
	1 = the time string will be in HH:MM:SS format.
AMPMFormat as Integer
	0 = no AM/PM indicators will be added.
	1 = " AM" or " PM" indicator will be added and the hour will
	    will be adjusted appropriately.

Returns

strTime as String

Example

Dim strTime as String
Dim sysTime as Integer
Dim ToTimeFormat as Integer
Dim AMPMFormat as Integer

sysTime = SystemTime("", "", 0, 0)
strTime = NSL.StringTime(sysTime, ToTimeFormat, AMPMFormat)

Version 1.4 Changes and Additions

PostEvent

NSBSystemLib.PostEvent eventNbr

Parameter:

eventNbr as Integer

Example

Dim eventNbr as Integer
eventNbr = 30000
NSL.PostEvent eventNbr

FormGetFocus

objID = NSBSystemLib.FormGetFocus()

Returns

objID as Integer
	-1 if no object has focus.

Example

Dim objID as Integer
objID = NSL.FormGetFocus()

FieldGetTextLength

txtLen = NSBSystemLib.FieldGetTextLength(objID)

Parameter

objID as Integer
	0 = use field that currently has focus (not on all devices, see above.)
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

txtLen as Integer

Example

Dim txtLen as Integer
Dim objID as Integer

objID = 1008
txtLen = NSL.FieldGetTextLength(objID)

RandomNumber

nbr = NSBSystemLib.RandomNumber(seed, minNbr, maxNbr)

Parameters

seed as Integer
	New seed value, use 0 to use the existing seed.
minNbr as Integer
	Min must be >= 0 and less than Max
maxNbr as Integer
	Max must be <= 32767 and greater than Min

Returns

nbr as Integer

Example

Dim nbr as Integer
Dim seed as Integer
Dim minNbr as Integer
Dim maxNbr as Integer

minNbr = 1
maxNBR = 10
nbr = NSL.RandomNumber(seed, minNbr, maxNbr)

ResetAutoOffTimer

NSBSystemLib.ResetAutoOffTimer()

Example

NSL.ResetAutoOffTimer()

SetAutoOffTime

oldSeconds = NSBSystemLib.SetAutoOffTime(newSeconds)

Parameter

newSeconds as Integer

Returns

oldSeconds as Integer

Example

Dim oldSeconds as Integer
Dim newSeconds as Integer

newSeconds = 600  '10 minutes
oldSeconds = NSL.SetAutoOffTime(newSeconds)

ProgramVersionString

verStr = NSBSystemLib.ProgramVersionString(cardNbr, pgmName)

Parameters

cardNbr as Integer
pgmName as String

Returns

verStr as String

Example

Dim verStr as String
Dim cardNbr as Integer
Dim pgmName as String

cardNbr = 0
pgmName = "NSBSystemLib"
verStr = NSL.ProgramVersionString(cardNbr, pgmName)

DynamicHeapSize

heapSize = NSBSystemLib.DynamicHeapSize()

Returns

heapSize as Integer

Example

Dim heapSize as Integer
heapSize = NSL.DynamicHeapSize()

DynamicHeapFree

freeSize = NSBSystemLib.DynamicHeapFree()

Returns

freeSize as Integer

Example

Dim freeSize as Integer
freeSize = NSL.DynamicHeapFree()

DynamicHeapMaxChunk

maxChunkSize = NSBSystemLib.DynamicHeapMaxChunk()

Returns

maxChunkSize as Integer

Example

Dim maxChunkSize as Integer
maxChunkSize = NSL.DynamicHeapMaxChunk()

SortInit

error = NSBSystemLib.SortInit(maxItems, itemType)

Parameters

maxItems as Integer
	The maximum number of data items to be added to the sort array.
itemType as String
	The data type to be sorted.
	   Valid values are:  "string", "integer", or "double"

Returns

error as Integer
	 0 = no error
	-1 = insufficient dynamic memory
	-2 = invalid itemType parameter

Example

See either the SortQSort() or SortInsertionSort() functions.

SortAddString

error = NSBSystemLib.SortAddString(strItem)

Parameter

strItem as String
	String data to add.

Returns

error as Integer
	 0 = no error
	-1 = insufficient dynamic memory
	-2 = sort array has not been initialized
	-3 = sort array was not initialized for string data
	-4 = exceeded the initialized number of items for
	     the sort array

Example

See either the SortQSort() or SortInsertionSort() functions.

SortAddInteger

error = NSBSystemLib.SortAddInteger(intItem)

Parameter

intItem as Integer
	String data to add.

Returns

error as Integer
	 0 = no error
	-1 = insufficient dynamic memory
	-2 = sort array has not been initialized
	-3 = sort array was not initialized for integer data
	-4 = exceeded the initialized number of items for
	     the sort array

Example

See either the SortQSort() or SortInsertionSort() functions.

SortAddDouble

error = NSBSystemLib.SortAddDouble(dblItem)

Parameter

dblItem as Double
	String data to add.

Returns

error as Integer
	 0 = no error
	-1 = insufficient dynamic memory
	-2 = sort array has not been initialized
	-3 = sort array was not initialized for double data
	-4 = exceeded the initialized number of items for
	     the sort array

Example

See either the SortQSort() or SortInsertionSort() functions.

SortGetString

strItem = NSBSystemLib.SortGetString(index)

Parameter

index as Integer
	The index or subscript of a data item in the sort array.

Returns

strItem as String

Example

See either the SortQSort() or SortInsertionSort() functions.

SortGetInteger

intItem = NSBSystemLib.SortGetInteger(index)

Parameter

index as Integer
	The index or subscript of a data item in the sort array.

Returns

intItem as Integer

Example

See either the SortQSort() or SortInsertionSort() functions.

SortGetDouble

dblItem = NSBSystemLib.SortGetDouble(index)

Parameter

index as Integer
	The index or subscript of a data item in the sort array.

Returns

dblItem as Double

Example

See either the SortQSort() or SortInsertionSort() functions.

SortQSort

numItems = NSBSystemLib.SortQSort(reverseSort, caselessSort)

Parameters

reverseSort as Integer
	0 = list is sorted from lowest to highest values
	1 = list is sorted from highest to lowest values
caselessSort as Integer
	0 = sort is case sensitive
	1 = sort is not case sensitive

Returns

numItems as Integer
	the number of items sorted
	  Use the appropriate function (SortGetString(),
	  SortGetInteger(), or SortGetDouble()) to return the
	  items from the sort array.

Example

Dim error as Integer
Dim maxItems as Integer
Dim itemType as String
Dim numItems as Integer
Dim reverseSort as Integer
Dim caselessSort as Integer
Dim i as Integer
Dim tmpStr as String

maxItems = 100
itemType = "string"
error = NSL.SortInit(maxItems, itemType)
If error <> 0 Then
    MsgBox "SortInit error = " + Str(error)
    Exit Sub
End If

For i = 1 to someNumber
    error = NSL.SortAddString(someStringArray(i))
    If error <> 0 Then
        MsgBox "SortAddString error = " + Str(error)
        Exit Sub
    End If
Next

reverseSort = 0     'Sort from lowest to highest
caselessSort = 1    'Case insensitive sort
numItems = NSL.SortQSort(reverseSort, caselessSort)

For i = 1 to numItems
   tmpStr = NSL.SortGetString(i)
   someStringArray(i) = tmpStr
Next

SortInsertionSort

numItems = NSBSystemLib.SortInsertionSort(reverseSort, caselessSort)

Parameters

reverseSort as Integer
	0 = list is sorted from lowest to highest values
	1 = list is sorted from highest to lowest values
caselessSort as Integer
	0 = sort is case sensitive
	1 = sort is not case sensitive

Returns

numItems as Integer
	the number of items sorted
	  Use the appropriate function (SortGetString(),
	  SortGetInteger(), or SortGetDouble()) to return the
	  items from the sort array.

Example

Dim error as Integer
Dim maxItems as Integer
Dim itemType as String
Dim numItems as Integer
Dim reverseSort as Integer
Dim caselessSort as Integer
Dim i as Integer
Dim tmpStr as String

maxItems = 100
itemType = "string"
error = NSL.SortInit(maxItems, itemType)
If error <> 0 Then
    MsgBox "SortInit error = " + Str(error)
    Exit Sub
End If

For i = 1 to someNumber
    error = NSL.SortAddString(someStringArray(i))
    If error <> 0 Then
        MsgBox "SortAddString error = " + Str(error)
        Exit Sub
    End If
Next

reverseSort = 0     'Sort from lowest to highest
caselessSort = 1    'Case insensitive sort
numItems = NSL.SortInsertionSort(reverseSort, caselessSort)

For i = 1 to numItems
   tmpStr = NSL.SortGetString(i)
   someStringArray(i) = tmpStr
Next

ListQSort

numItems = NSBSystemLib.ListQSort(objID, reverseSort, caselessSort)

Parameters

objID as Integer
	objectID of the list object
	  Use 0 to specify the object that currently has focus.
reverseSort as Integer
	0 = list is sorted from lowest to highest values
	1 = list is sorted from highest to lowest values
caselessSort as Integer
	0 = sort is case sensitive
	1 = sort is not case sensitive

Returns

numItems as Integer
	the number of items sorted

Example

Dim numItems as Integer
Dim objID as Integer
Dim reverseSort as Integer
Dim caselessSort as Integer

objID = 1008
reverseSort = 0
caselessSort = 0
numItems = NSL.ListQSort(objID, reverseSort, caselessSort)

ListInsertionSort

numItems = NSBSystemLib.ListInsertionSort(objID, reverseSort, caselessSort)

Parameters

objID as Integer
	objectID of the list object
	  Use 0 to specify the object that currently has focus.
reverseSort as Integer
	0 = list is sorted from lowest to highest values
	1 = list is sorted from highest to lowest values
caselessSort as Integer
	0 = sort is case sensitive
	1 = sort is not case sensitive

Returns

numItems as Integer
	the number of items sorted

Example

Dim numItems as Integer
Dim objID as Integer
Dim reverseSort as Integer
Dim caselessSort as Integer

objID = 1008
reverseSort = 0
caselessSort = 0
numItems = NSL.ListInsertionSort(objID, reverseSort, caselessSort)

Version 2.0 Changes and Additions

FormGetAllObjectTypes

type = NSBSystemLib.FormGetAllObjectTypes(objID)

Parameter

objID as Integer
	0 = use object that currently has focus
	    objID may be either an Object ID or an Object Index.
	    If the value of objID is between 1 and the number of
	    objects on the form, objID is assumed to be an Object
	    Index, otherwise, it is assumed to be an Object ID.

Returns

type as Integer
	-1 if the object is invalid or no object has focus
	 0 = frmFieldObj
	 2 = frmListObj
	 3 = frmTableObj
	 4 = frmBitmapObj
	 5 = frmLineObj
	 6 = frmFrameObj
	 7 = frmRectangleObj
	 8 = frmLabelObj
	 9 = frmTitleObj
	10 = frmPopupObj
	11 = frmGraffitiStateObj
	12 = frmGadgetObj
	13 = frmScrollbarObj
	100 = buttonCtl
	101 = pushButtonCtl
	102 = checkboxCtl
	103 = popupTriggerCtl
	104 = selectorTriggerCtl
	105 = repeatingButtonCtl
	106 = sliderCtl
	107 = feedbackSliderCtl

Example

Dim type as Integer
Dim objID as Integer
objID = 1008
type = NSL.FormGetAllObjectTypes(objID)

FieldClearAll

NSBSystemLib.FieldClearAll()

Example

NSL.FieldClearAll()

ObjectWithPoint

obj = NSBSystemLib.ObjectWithPoint(x, y, returnType, searchOption)

Parameters

x as Integer
	x coordinate
y as Integer
	y coordinate
returnType as Integer
	0 = return the object's ID
	1 = return the object's index
	    This index is in the range of 1 to number of objects
	    on the form. It is the PalmOS index incremented by 1
	    so that it can be used with other functions in this
	    library.  If you use this value with a Systrap, you
	    must subtract 1 from the index.
	2 = return the object's pointer (use variant as the return type)
searchOption as Integer
	0 = search for objects that are usable, visible, and enabled/editable
	1 = search for objects that are usable and visible
	2 = search for all objects

Returns

obj as Integer
	object as either an object ID, index, or pointer
	-1 or NULL (0 if returning a pointer) when no object was found

Example

Dim obj as Integer
Dim x as Integer
Dim y as Integer
Dim returnType as Integer
Dim searchOption as Integer

obj = NSL.ObjectWithPoint(x, y, returnType, searchOption)

ANDInt

result = NSBSystemLib.ANDInt(int1, int2)

Parameters

int1 as Integer
int2 as Integer

Returns

result as Integer

Example

Dim result as Integer
Dim int1 as Integer
Dim int2 as Integer

result = NSL.ANDInt(int1, int2)

ORInt

result = NSBSystemLib.ORInt(int1, int2)

Parameters

int1 as Integer
int2 as Integer

Returns

result as Integer

Example

Dim result as Integer
Dim int1 as Integer
Dim int2 as Integer

result = NSL.ORInt(int1, int2)

XORInt

result = NSBSystemLib.XORInt(int1, int2)

Parameters

int1 as Integer
int2 as Integer

Returns

result as Integer

Example

Dim result as Integer
Dim int1 as Integer
Dim int2 as Integer

result = NSL.XORInt(int1, int2)

OnesComplement

result = NSBSystemLib.OnesComplement(intValue)

Parameter

intValue as Integer

Returns

result as Integer

Example

Dim result as Integer
Dim intValue as Integer

result = NSL.OnesComplement(intValue)

BitValue

result = NSBSystemLib.BitValue(intValue, bitNumber)

Parameters

intValue as Integer
bitNumber as Integer
	Bits are numbered from right to left from 0 to 31.

Returns

result as Integer

Example

Dim result as Integer
Dim intValue as Integer
Dim bitNumber as Integer

result = NSL.BitValue(intValue, bitNumber)

BitsValue

result = NSBSystemLib.BitsValue(intValue, startBit, endBit)

Parameters

intValue as Integer
startBit as Integer
	Bits are numbered from right to left from 0 to 31.
endBit as Integer
	Bits are numbered from right to left from 0 to 31.

Returns

result as Integer

Example

Dim result as Integer
Dim intValue as Integer
Dim startBit as Integer
Dim endBit as Integer

result = NSL.BitsValue(intValue, startBit, endBit)

SetBitValue

result = NSBSystemLib.SetBitValue(intValue, bitNumber, bitValue)

Parameters

intValue as Integer
bitNumber as Integer
	Bits are numbered from right to left from 0 to 31.
bitValue as Integer

Returns

result as Integer

Example

Dim result as Integer
Dim intValue as Integer
Dim bitNumber as Integer
Dim bitValue as Integer

result = NSL.SetBitValue(intValue, bitNumber, bitValue)

SetBitsValue

result = NSBSystemLib.SetBitsValue(intValue, bitsValue, startBit, endBit)

Parameters

intValue as Integer
bitsValue as Integer
	Bits are numbered from right to left from 0 to 31.
startBit as Integer
	Bits are numbered from right to left from 0 to 31.
endBit as Integer

Returns

result as Integer

Example

Dim result as Integer
Dim intValue as Integer
Dim bitsValue as Integer
Dim startBit as Integer
Dim endBit as Integer

result = NSL.SetBitsValue(intValue, bitsValue, startBit, endBit)

IntToHex

hexValue = NSBSystemLib.IntToHex(intValue, trimLeading)

Parameters

intValue as Integer
trimLeading as Integer
	0 = do not trim leading zeros from result string
	1 = trim leading zeros from result string.

Returns

hexValue as String

Example

Dim hexValue as String
Dim intValue as Integer
Dim trimLeading as Integer

hexValue = NSL.IntToHex(intValue, trimLeading)

HexToInt

intValue = NSBSystemLib.HexToInt(hexValue)

Parameter

hexValue as String

Returns

intValue as Integer

Example

Dim intValue as Integer
Dim hexValue as String

intValue = NSL.HexToInt(hexValue)

IntToBin

binValue = NSBSystemLib.IntToBin(intValue, trimLeading)

Parameters

intValue as Integer
trimLeading as Integer
	0 = do not trim leading zeros from result string
	1 = trim leading zeros from result string.

Returns

binValue as String

Example

Dim binValue as String
Dim intValue as Integer
Dim trimLeading as Integer

binValue = NSL.IntToBin(intValue, trimLeading)

BinToInt

intValue = NSBSystemLib.BinToInt(binValue)

Parameter

binValue as String

Returns

intValue as Integer

Example

Dim intValue as Integer
Dim binValue as String

intValue = NSL.BinToInt(binValue)

Screen and Color Functions

GetSupportedDepths

depths = NSBSystemLib.GetSupportedDepths()

Returns

depths as Integer

Example

Dim depths as Integer
depths = NSL.GetSupportedDepths()

DepthSupported

boolean = NSBSystemLib.DepthSupported(depth)

Parameter

depth as Integer

Returns

boolean as Integer

Example

Dim boolean as Integer
Dim depth as Integer

depth = 4
boolean = NSL.DepthSupported(depth)

ColorSupported

boolean = NSBSystemLib.ColorSupported()

Returns

boolean as Integer

Example

Dim boolean as Integer
boolean = NSL.ColorSupported()

SetDepth

NSBSystemLib.SetDepth depth

Parameter:

depth as Integer

Example

Dim depth as Integer

depth = 4
NSL.SetDepth depth

SetColor

NSBSystemLib.SetColor boolean

Parameter:

boolean as Integer
	1 = support color
	0 = do not support color

Example

Dim boolean as Integer

boolean = 1
NSL.SetColor boolean

SaveScreenMode

NSBSystemLib.SaveScreenMode()

Example

NSL.SaveScreenMode()

RestoreScreenMode

NSBSystemLib.RestoreScreenMode()

Example

NSL.RestoreScreenMode()

CurrentDepth

depth = NSBSystemLib.CurrentDepth()

Returns

depth as Integer

Example

Dim depth as Integer
depth = NSL.CurrentDepth()

CurrentColor

boolean = NSBSystemLib.CurrentColor()

Returns

boolean as Integer

Example

Dim boolean as Integer
boolean = NSL.CurrentColor()

SetToDefaults

NSBSystemLib.SetToDefaults()

Example

NSL.SetToDefaults()

DefaultDepth

depth = NSBSystemLib.DefaultDepth()

Returns

depth as Integer

Example

Dim depth as Integer
depth = NSL.DefaultDepth()

DefaultColor

boolean = NSBSystemLib.DefaultColor()

Returns

boolean as Integer

Example

Dim boolean as Integer
boolean = NSL.DefaultColor()

GetTableEntryIndex

index = NSBSystemLib.GetTableEntryIndex(which)

Parameter

which as Integer
	UIObjectFrame = 0,
	UIObjectFill = 1
	UIObjectForeground = 2
	UIObjectSelectedFill = 3
	UIObjectSelectedForeground = 4
	
	UIMenuFrame = 5
	UIMenuFill = 6
	UIMenuForeground = 7
	UIMenuSelectedFill = 8
	UIMenuSelectedForeground = 9
	
	UIFieldBackground = 10
	UIFieldText = 11
	UIFieldTextLines = 12
	UIFieldCaret = 13
	UIFieldTextHighlightBackground = 14
	UIFieldTextHighlightForeground = 15
	UIFieldFepRawText = 16
	UIFieldFepRawBackground = 17
	UIFieldFepConvertedText = 18
	UIFieldFepConvertedBackground = 19
	UIFieldFepUnderline = 20
	
	UIFormFrame = 21
	UIFormFill = 22
	
	UIDialogFrame = 23
	UIDialogFill = 24
	
	UIAlertFrame = 25
	UIAlertFill = 26
	
	UIOK = 27
	UICaution = 28
	UIWarning = 29

Returns

index as Integer
	-1 = PalmOS version is less than 3.5

Example

Dim index as Integer
Dim which as Integer

which = 11   'UIFieldText
index = NSL.GetTableEntryIndex(which)

GetTableEntryRGB

index = NSBSystemLib.GetTableEntryRGB(which)

Parameter

which as Integer
	(see the GetTableEntryIndex function for
	 a list of valid "Which" values")

Returns

index as Integer
	-1 = PalmOS version is less than 3.5

Example

Dim index as Integer
Dim which as Integer
Dim red as Integer
Dim green as Integer
Dim blue as Integer

which = 11   'UIFieldText
index = NSL.GetTableEntryRGB(which)
red = SL.GetRGBRed()
green = SL.GetRGBGreen()
blue = SL.GetRGBBlue()

GetRGBIndex

index = NSBSystemLib.GetRGBIndex()

Returns

index as Integer

Example

Dim index as Integer
index = NSL.GetRGBIndex()

GetRGBRed

red = NSBSystemLib.GetRGBRed()

Returns

red as Integer

Example

See the example provided with either the GetTableEntryRGB or
IndexToRGB functions.

GetRGBGreen

green = NSBSystemLib.GetRGBGreen()

Returns

green as Integer

Example

See the example provided with either the GetTableEntryRGB or
IndexToRGB functions.

GetRGBBlue

blue = NSBSystemLib.GetRGBBlue()

Returns

blue as Integer

Example

See the example provided with either the GetTableEntryRGB or
IndexToRGB functions.

SetTableEntryIndex

NSBSystemLib.SetTableEntryIndex which, index

Parameters

which as Integer
	(see the GetTableEntryIndex function for
	 a list of valid "Which" values")

index as Integer

Example

Dim which as Integer
Dim index as Integer

NSL.SetTableEntryIndex which, index

SetTableEntryRGB

NSBSystemLib.SetTableEntryRGB which, red, green, blue

Parameters

which as Integer
	(see the GetTableEntryIndex function for
	 a list of valid "Which" values")

red as Integer

green as Integer

blue as Integer
	Red, Green, Blue valid values are 0 to 255

Example

Dim which as Integer
Dim red as Integer
Dim green as Integer
Dim blue as Integer

NSL.SetTableEntryRGB which, red, green, blue

BrightnessAdjust

NSBSystemLib.BrightnessAdjust()

Example

NSL.BrightnessAdjust()

ContrastAdjust

NSBSystemLib.ContrastAdjust()

Example

NSL.ContrastAdjust()

PickColorIndex

changed = NSBSystemLib.PickColorIndex(index, title)

Parameters

index as Integer
	Suggested index
title as String
	Title to display on dialog

Returns

changed as Integer
	-1 = PalmOS version is less than v3.5
	 0 = User cancelled or chose suggested index
	 1 = User chose a new index

Example

Dim changed as Integer
Dim index as Integer
Dim title as String

changed = NSL.PickColorIndex(index, title)

PickColorRGB

changed = NSBSystemLib.PickColorRGB(red, green, blue, title)

Parameters

red as Integer
green as Integer
blue as Integer
	Suggested Red, Green, Blue values (0 to 255)
title as String
	Title to display on dialog

Returns

changed as Integer
	-1 = PalmOS version is less than 3.5
	 0 = User cancelled or chose suggested colors
	 1 = User chose a new index

Example

Dim changed as Integer
Dim red as Integer
Dim green as Integer
Dim blue as Integer
Dim title as String

changed = NSL.PickColorRGB(red, green, blue, title)

IndexToRGB

NSBSystemLib.IndexToRGB index

Parameter:

index as Integer

Example

Dim index as Integer
NSL.IndexToRGB index

RGBToIndex

index = NSBSystemLib.RGBToIndex(red, green, blue)

Parameters

red as Integer
green as Integer
blue as Integer
	Red, Green, Blue valid values are 0 to 255

Returns

index as Integer
	-1 = PalmOS version is less than 3.5

Example

Dim index as Integer
Dim red as Integer
Dim green as Integer
Dim blue as Integer

index = NSL.RGBToIndex(red, green, blue)

SetForeColor

oldIndex = NSBSystemLib.SetForeColor(newIndex)

Parameter

newIndex as Integer

Returns

oldIndex as Integer
	Previous foreground index
	-1 = PalmOS version is less than 3.5

Example

Dim oldIndex as Integer
Dim newIndex as Integer

oldIndex = NSL.SetForeColor(newIndex)

SetBackColor

oldIndex = NSBSystemLib.SetBackColor(newIndex)

Parameter

newIndex as Integer

Returns

oldIndex as Integer
	Previous background index
	-1 = PalmOS version is less than 3.5

Example

Dim oldIndex as Integer
Dim newIndex as Integer

oldIndex = NSL.SetBackColor(newIndex)

SetTextColor

oldIndex = NSBSystemLib.SetTextColor(newIndex)

Parameter

newIndex as Integer

Returns

oldIndex as Integer
	Previous text color index
	-1 = PalmOS version is less than 3.5

Example

Dim oldIndex as Integer
Dim newIndex as Integer

oldIndex = NSL.SetTextColor(newIndex)

DrawLine

NSBSystemLib.DrawLine x1, y1, x2, y2

Parameters

x1 as Integer

y1 as Integer

x2 as Integer

y2 as Integer

Example

Dim x1 as Integer
Dim y1 as Integer
Dim x2 as Integer
Dim y2 as Integer

NSL.DrawLine x1, y1, x2, y2

DrawGrayLine

NSBSystemLib.DrawGrayLine x1, y1, x2, y2

Parameters

x1 as Integer

y1 as Integer

x2 as Integer

y2 as Integer

Example

Dim x1 as Integer
Dim y1 as Integer
Dim x2 as Integer
Dim y2 as Integer

NSL.DrawGrayLine x1, y1, x2, y2

EraseLine

NSBSystemLib.EraseLine x1, y1, x2, y2

Parameters

x1 as Integer

y1 as Integer

x2 as Integer

y2 as Integer

Example

Dim x1 as Integer
Dim y1 as Integer
Dim x2 as Integer
Dim y2 as Integer

NSL.EraseLine x1, y1, x2, y2

InvertLine

NSBSystemLib.InvertLine x1, y1, x2, y2

Parameters

x1 as Integer

y1 as Integer

x2 as Integer

y2 as Integer

Example

Dim x1 as Integer
Dim y1 as Integer
Dim x2 as Integer
Dim y2 as Integer

NSL.InvertLine x1, y1, x2, y2

DrawPixel

NSBSystemLib.DrawPixel x, y

Parameters

x as Integer

y as Integer

Example

Dim x as Integer
Dim y as Integer

NSL.DrawPixel x, y

ErasePixel

NSBSystemLib.ErasePixel x, y

Parameters

x as Integer

y as Integer

Example

Dim x as Integer
Dim y as Integer

NSL.ErasePixel x, y

InvertPixel

NSBSystemLib.InvertPixel x, y

Parameters

x as Integer

y as Integer

Example

Dim x as Integer
Dim y as Integer

NSL.InvertPixel x, y

GetPixel

index = NSBSystemLib.GetPixel(x, y)

Parameters

x as Integer
y as Integer

Returns

index as Integer

Example

Dim index as Integer
Dim x as Integer
Dim y as Integer

index = NSL.GetPixel(x, y)

ScreenLock

success = NSBSystemLib.ScreenLock(mode)

Parameter

mode as Integer
	winLockCopy = 0 - copy old screen to new
	winLockErase = 1 - erase new screen to white
	winLockDontCare = 2 - don't do anything

Returns

success as Integer
	-1 = PalmOS version is less than 3.5
	 1 = success
	 0 = failure

Example

Dim success as Integer
Dim mode as Integer

success = NSL.ScreenLock(mode)

ScreenUnlock

NSBSystemLib.ScreenUnlock()

Example

NSL.ScreenUnlock()

WinSaveBits

NSBSystemLib.WinSaveBits index, x, y, width, height

Parameters

index as Integer

x as Integer

y as Integer

width as Integer

height as Integer

Example

Dim index as Integer
Dim x as Integer
Dim y as Integer
Dim width as Integer
Dim height as Integer

NSL.WinSaveBits index, x, y, width, height

WinRestoreBits

NSBSystemLib.WinRestoreBits index, x, y

Parameters

index as Integer

x as Integer

y as Integer

Example

Dim index as Integer
Dim x as Integer
Dim y as Integer

NSL.WinRestoreBits index, x, y

Sleep and Wake Event Functions

SetSleepEvent

NSBSystemLib.SetSleepEvent eventNbr

Parameter:

eventNbr as Integer
	Use 0 to cause no event to be posted.

Example

Dim eventNbr as Integer
eventNbr = 30000
NSL.SetSleepEvent eventNbr

SetWakeEvent

NSBSystemLib.SetWakeEvent eventNbr

Parameter:

eventNbr as Integer
	Use 0 to cause no event to be posted.

Example

Dim eventNbr as Integer
eventNbr = 30001
NSL.SetWakeEvent eventNbr

GetSleepEvent

eventNbr = NSBSystemLib.GetSleepEvent()

Returns

eventNbr as Integer

Example

Dim eventNbr as Integer
eventNbr = NSL.GetSleepEvent()

GetWakeEvent

eventNbr = NSBSystemLib.GetWakeEvent()

Returns

eventNbr as Integer

Example

Dim eventNbr as Integer
eventNbr = NSL.GetWakeEvent()

GetSleepEventTime

eventTime = NSBSystemLib.GetSleepEventTime()

Returns

eventTime as Integer
	eventTime in system time format.  This value is expressed
	as the number of seconds since January 1st, 1904.

Example

Dim eventTime as Integer
eventTime = NSL.GetSleepEventTime()

GetWakeEventTime

eventTime = NSBSystemLib.GetWakeEventTime()

Returns

eventTime as Integer
	eventTime in system time format.  This value is expressed
	as the number of seconds since January 1st, 1904.

Example

Dim eventTime as Integer
eventTime = NSL.GetWakeEventTime()

String Encryption and Decryption Functions

0 1 2 3 4 5 6 7 8
--- --- --- --- --- --- --- --- ---
x 0 x x 0 x x x

becomes

3 x 6 x x 255 x x x

Dim KeyStr As String
Dim DecryptedStr As String
Dim EncryptedStr As String
Dim StrLen As Integer



KeyStr = "secret"
DecryptedStr = "The quick brown fox jumps over the lazy dog!"
StrLen = EncryptData(KeyStr, DecryptedStr, EncryptedStr)
DecryptedStr = ""
StrLen = DecryptData(KeyStr, EncryptedStr, DecryptedStr)

char keyStr[25];
char decryptedStr[251];
char encryptedStr[251];
int  len;



strcpy(keyStr, "secret");
strcpy(decryptedStr, "The quick brown fox jumps over the lazy dog!");
len = encryptData(keyStr, decryptedStr, encryptedStr);
strcpy(decryptedStr, "");
len = decryptData(keyStr, encryptedStr, decryptedStr);

EncryptDESString

encryptedStr = NSBSystemLib.EncryptDESString(decryptedStr)

Parameter

decryptedStr as String

Returns

encryptedStr as String

Example

Dim encryptedStr as String
Dim decryptedStr as String

encryptedStr = NSL.EncryptDESString(decryptedStr)

DecryptDESString

decryptedStr = NSBSystemLib.DecryptDESString(encryptedStr)

Parameter

encryptedStr as String

Returns

decryptedStr as String

Example

Dim decryptedStr as String
Dim encryptedStr as String

decryptedStr = NSL.DecryptDESString(encryptedStr)

SetDESKey

NSBSystemLib.SetDESKey keyStr

Parameter:

keyStr as String

Example

Dim keyStr as String
NSL.SetDESKey keyStr