Introduction:

The NSBLifeDriveLib shared library allows many of the multimedia features of the LifeDrive Palm device to be used from within an NSBasic program.

In order to use the NSBLifeDriveLib shared library, the library must be loaded using the NSBasic LoadLibrary statement. This statement should be located in the Startup Code of the program, as in this example:

Sub main()
    LoadLibrary "NSBLifeDriveLib"
End Sub

This document assumes that the shared library has been loaded this way. The LoadLibrary statement also has an optional second parameter to allow you to specify an abbreviated reference name for the library's functions, as in this example:

Sub main()
    LoadLibrary "NSBLifeDriveLib", "LD"
End Sub

For this example, you can use the functions and subroutines described in this document with a prefix of LD instead of NSBLifeDriveLib.

In order to use the NSBLifeDriveLib Shared Library, the NSBLifeDriveLib.inf file must be present in your C:\nsbasic\lib directory, and the NSBLifeDriveLib.prc file must be downloaded to your device or included in your NSBasic program. For more information on shared libraries, refer to the NSBasic documentation.

Many of the subroutines and functions within the NSBLifeDriveLib shared library use virtual files. Utility subroutines and functions for accessing these files are found in the NSBVFSLib library. See Tech Note 28 for more information.

For an example of how to use this library, see LifeDriveTest.prj, which is included with full distributions of NSBasic 5 or later.

Index and Quick Reference:

Full Reference:

BrowserOpen

success = NSBLifeDriveLib.BrowserOpen(volumeID, path, extensions, title)

BrowserOpen presents a file brower dialog window to open a file. VolumeID and path are the volume ID and full path name of the file selected by the user. Extensions is a string containing a list of filename extensions or MIME types, separated by commas. Only files with these extensions will be shown. Title is the title of the dialog window.

Do not use BrowserOpen to open images or videos. Use PhotoSelectImage, PhotoSelectImages, PhotoSelectVideo, or PhotoSelectVideos.

BrowserOpen returns true (-1) if the user selects a file or false (0) if the user cancels.

Example:

Also see:

BrowserPresent

success = NSBLifeDriveLib.BrowserPresent

The file browser on the LifeDrive and some other devices mimics the behavior of the Open and Save As... dialog windows on desktop machines. PalmOne recommends this only in cases where a PalmOS program must look like its desktop equivalent.

BrowserPresnt returns true (-1) if the file browser is present and false (0) otherwise. Do not use any subsequent file browser functions if the browser is not present.

BrowserSave

success = NSBLifeDriveLib.BrowserSave(volumeID, path, extensions, title)

BrowserOpen presents a file brower dialog window to open a file. VolumeID and path are the volume ID and full path name of the file selected by the user. Extensions is a string containing a list of filename extensions or MIME types, separated by commas. The first entry in this list should be the default extension of a saved file and should be an extension, not a MIME type. Title is the title of the dialog window.

BrowserSave returns true (-1) if the user chooses to save a file or false (0) if the user cancels.

Example:

Also see:

PhotoAlbumCount

numAlbums = NSBLifeDriveLib.PhotoAlbumCount(volumeID)

PhotoAlbumCount returns the number of photo albums on volumeID, which is an integer volume ID. Pass 0 for volumeID to specify the device itself. Other volumes IDs can be obtained using the NSBVFSLib library or from any of the LifeDrive functions that return volume IDs.

PhotoAlbumID

albumID = NSBLifeDriveLib.PhotoAlbumID(volume, index)

PhotoAlbumID returns the ID of the photo album specified by volume and index. The ID should be stored in a variable of type Integer. Volume is the ID of the volume on which to look for the photo album. Pass 0 for volume to use the local volume on the device. Other volumes can be obtained from functions in the NSBVFSLib library or from any of the LifeDrive functions that return volume IDs. Index must be between 1 and the number of albums returned from PhotoAlbumCount.

Also see:

PhotoAlbumName

name = NSBLifeDriveLib.PhotoAlbumName(albumID)

PhotoAlbumName returns as a string the name of the photo album specified by albumID, which should have been returned by PhotoAlbumID.

Also see:

PhotoDeleteAlbumAndContents

success = NSBLifeDriveLib.PhotoDeleteAlbum(albumID)

PhotoDeleteAlbum deletes the specified album. Photos within the album are deleted as well. Returns true (-1) if successful and false (0) otherwise. The Unfiled album cannot be deleted.

Also see:

PhotoDeleteAlbum

success = NSBLifeDriveLib.PhotoDeleteAlbum(albumID)

PhotoDeleteAlbum deletes the specified album. Photos within the album are moved to Unfiled. Returns true (-1) if successful and false (0) otherwise. The Unfiled album cannot be deleted.

Also see:

PhotoDisplayImage

NSBLifeDriveLib.PhotoDisplayImage(imageID, left, top, width, height)

PhotoDisplayImage displays the image given by imageID in the rectangle described by left, top, width, and height. Coordinates are given in NSBasic coordinates, where the standard LifeDrive screen is 160 by 160. Images with higher resolution will make use of the higher resolution of the LifeDrive screen. For example, a 320 by 320 JPEG image will display at perfect resulution in a 180 by 180 rectangle. Images that do not perfectly fit within the rectangle will be shrunk to fit.

If imageID refers to a still image, the function will return immediately after the image has been displayed. An ideal use of this is to display an image within the bounds of a gadget.

If imageID refers to a video rather than a still image, the rectangle will be ignored, and the video will open within the video player.

Also see:

PhotoImageCount

numImages = NSBLifeDriveLib.PhotoImageCount(albumID)

PhotoImageCount returns the number of images in the album specified by albumID.

Also see:

PhotoImageName

name = NSBLifeDriveLib.PhotoImageName(imageID)

PhotoImageName returns the name of the image specified by imageID. The name is the full path name of the image within the volume it resides on.

Also see:

PhotoNewAlbum

albumID = NSBLifeDriveLib.PhotoNewAlbum(volumeID, name)

PhotoNewAlbum creates a new photo album named name on the volume specified by volumeID. Pass 0 for volume to use the local volume on the device. Other volumes can be obtained from functions in the NSBVFSLib library or from any of the LifeDrive functions that return volume IDs. PhotoNewAlbum returns the ID of the newly created photo album or -1 if the album could not be created.

PhotoPresent

success = NSBLifeDriveLib.PhotoPresent

PhotoPresent returns true (-1) if the photo functions are present or false (0) if they are absent. Check the value of this before trying to use any of the photo functions.

PhotoRenameAlbum

success = NSBLifeDriveLib.PhotoRenameAlbum(albumID, newName)

PhotoRenameAlbum renames a photo album specified by albumID to newName, returning true (-1) if renaming was successful and false (0) otherwise.

Also see:

PhotoSelectFromAlbum

NSBLifeDriveLib.PhotoSelectFromAlbum(albumID, start, numImages)

PhotoSelectFromAlbum selects one or more images from an album specified by albumID. Start is the number of the first image to select and must be between 1 and the number of images returned by PhotoImageCount. NumImages is the number of images to select. For example, NSBLifeDriveLib.PhotoSelectFromAlbum(ID, 2, 3) will select images 2, 3, and 4 from album ID.

Only one selection containing zero or more images or videos is available at one time. It is called the current selection.

Also see:

PhotoSelectImages

NSBLifeDriveLib.PhotoSelectImages

PhotoSelectImages presents the user with a dialog window to select any number of images. If the user cancels the dialog window, the selection will remain unchanged.

Only one selection containing zero or more images or videos is available at one time. It is called the current selection.

On older devices, this subroutine may select videos as well as images but should only select images on newer devices.

Also see:

PhotoSelectImage

NSBLifeDriveLib.PhotoSelectImage

PhotoSelectImage presents the user with a dialog window to select a single image. If the user cancels the dialog window, the selection will remain unchanged.

Only one selection containing zero or more images or videos is available at one time. It is called the current selection.

On older devices, this subroutine may select videos as well as images but should only select images on newer devices.

Also see:

PhotoSelectNone

NSBLifeDriveLib.PhotoSelectNone

PhotoSelectNone clears the current selection. Use this before a PhotoSelectImage(s) or PhotoSelectVideo(s) to determine whether the user selected images or videos.

PhotoSelectVideos

NSBLifeDriveLib.PhotoSelectVideos

PhotoSelectVideos presents the user with a dialog window to select any number of videos. If the user cancels the dialog window, the selection will remain unchanged.

Only one selection containing zero or more images or videos is available at one time. It is called the current selection.

On older devices, this subroutine may select images as well as videos but should only select videos on newer devices.

Also see:

PhotoSelectVideo

NSBLifeDriveLib.PhotoSelectVideo

PhotoSelectVideo presents the user with a dialog window to select a single video. If the user cancels the dialog window, the selection will remain unchanged.

Only one selection containing zero or more images or videos is available at one time. It is called the current selection.

On older devices, this subroutine may select images as well as videos but should only select videos on newer devices.

Also see:

PhotoSelectedImage

imageID = NSBLifeDriveLib.PhotoSelectedImage(which)

PhotoSelectedImage returns the ID of of image which in the current selection. Which must be between 1 and the number of images returned by PhotoSelectionCount. The return value should be stored in a variable of type Integer.

ImageID can be a still image or a video, depending on the type of media in the selection.

Also see:

PhotoSelectionCount

numImages = NSBLifeDriveLib.PhotoSelectionCount

PhotoSelectionCount returns the number of images or videos in the current selection.