The Runtime Resource Editor Library is a share library for PDA Toolbox applications.  It provides application resource manipulation actions.

This library provides the ability for the PDA Toolbox application to modify it's own resources by copying resources from an external file.  There are several possibilities that this provides: Your applications can be made "skinnable", that is, to change the user-interface of the app often by changing the graphics in the application.  It can provide user selectable "language" interfaces by providing alternate UIs contained in additional files.  More advanced operations could be done by changing the fundamental actions a program performs by "skinning" the action and other PDA Toolbox resources.

Additionally, there are some PDA Toolbox Application specific actions that are used strictly to modify the behavior of a PDA Toolbox-PDAT/Advanced app.  These are $Rsrc.StartForm, $Rsrc.Popup, and $Rsrc.TableRowColor.

The Runtime Resource Editor Library works by opening source resource databases and merging the entire file or selected resources into the application.  Each resource database can either be specified by file name and automatically set as the source database, or it can be selected by the user from a list of files.  The list of files are all files of a particular Creator ID and Type.

It is also used as a "Plug-In" to PDAT/Advanced to provide additional Actions to your PDA Toolbox programs.  

This manual assumes the reader has familiarity with the PDAT/Advanced application.

The Runtime Resource Editor Library is a Shareware Library for the Palm OS™ 3.1 and up unless specifically mentioned.  This library requires approx. 16k of internal hand-held memory.  For purchasing information click here.

PDA Toolbox 6.0 Professional Instructions

1. Download the Windows Plug-In from www.SandsUSA.com/PDAT.
2. Following instructions for plugging in libraries contained in the included readme file.

PDAT/Advanced Instructions

Before you can use the actions contained in this library, you must first "plug" it into PDAT/Advanced.  Once plugged in and registered, you will be able to use and distribute this library freely.

1. First, install the "PDATRsrc.prc" file onto your development handheld.  This should also have a copy of PDAT/Advanced.
2. At PDAT/Advanced's Open Screen, tap the menu and choose from the Advanced menu "Manage Libraries".
3. Next, if the "Runtime Resource Editor Library" is not shown in the list, tap the "Add" button.
4. In the "Add Library" dialog, enter in the Library ID of "PRed" (without the quotes).
5. Next, enter the license information you received when you registered.
6. Lastly, tap the "Done" button.

After successful registration, when you are editing actions, you'll have a second button named "Lib" which pops up a list of all the commands available to you.

The general idea behind skinning applications, or changing the appearance of the application, is to create resource databases that contain all of the bitmaps of an app, each with the same resource ID as the graphic in the app.  By using this library, your app then selects the resource database to merge into your app.  Since your app's bitmaps are being overwritten by the resource database, the appearance of your app is changed.

General steps to create a resource database on the emulator (POSE) with RsrcEdit:

1. Start RsrcEdit and from the Options menu, select New Database.
2. For the Name field enter a descriptive name that describes what kind of skin it is: Enter "MyAppSpySkin" (or something).  For the Creator, you can use your application's ID.  This means, when a user deletes your app, the skins will be deleted with it.  The Type may be anything you want, I've used "skin."  The Resource DB must be checked.
3. When you tap OK, the database will be created and hi-lited in the main window.
4. Still in RsrcEdit, find your PDA Toolbox Application.
5. Open it up and find a bitmap to copy to the clipboard.
6. Go back to your "MyAppSpySkin" file and open it.
7. Now paste the graphic resource into the file.  The ID should remain the same.
8. Perform steps 7-10 as many times as needed.
9. Now you have a "Skin" file (resource database) that can be a starting point for all new skins by copying the file and changing the images.

You want all your skin files to have the same Creator ID and Type.  This is so that your application can display a list of skins to the user.

The coding is small:

1. Start PDAT/Advanced and open your PDA Toolbox App.
2. Find or create a button or menu item to be the "Change Skin" command.
3. The actions for this command will be something like this:

$Rsrc.Select "ABCD", "skin"
$Rsrc.CopyFile

There are many variations on this theme: You can allow skinning a complete app, or just merging specific resources.  The $Rsrc.CopyFile is the simplist approach.

The file "PDATRsrc.prc" must be distributed with any application that uses this library.  Since you are distributing multiple PRC files that must be installed on the hand-held device, you may want to check out Ecamm's NutShell for the Palm OS at http://www.ecamm.com/palm/nutshell.  Nutshell is a unique installer solution, which allows users distribute multiple Palm files and data as a single self-expanding PRC file.  With this tool, the user installs a single file onto their hand-held and the first time your app is run, all the libraries, databases, and sub-programs are automatically unpacked and your app runs.  A very good solution to a sticky problem.

Each Action in the library will be described here.

Before you can call this action, you must first select a resource database either by user-selection, or by filename.  Each resource specified as parameters will be copied into the calling application.  When you return to the app, the resources merged will be automatically loaded. 

The practical number of resources you can specify is about 50.

Unlike the other CopyXXXX actions, you do not need to first select a resource database.  The application itself defaults as the source and destionation file.  However, you may select a resource database either by user-selection, or by filename.  You may specify a list of resource pairs (sourceID, destID) to copy many specific resources.

The practical number of resources you can specify is about 30.

Before you can call this action, you must first select a resource database either by user-selection, or by filename.  All resources that match the types specified will copied into the calling application.  When you return to the app, the resources merged will be automatically loaded. 

The practical number of resources you can specify is about 60.

Before you can call this action, you must first select a resource database either by user-selection, or by filename.  All resources will copied into the calling application.  When you return to the app, the resources merged will be automatically loaded. 

NOTE: Use this at your own risk.

Before you can call this action, you may first select a resource database either by user-selection, or by filename.  If you do not, the calling application will be the source the resources are deleted from.  Each resource specified as parameters will be deleted from the database. 

The practical number of resources you can specify is about 50.

This will allow you to change the data that appears in a dynamic popup.  For instance, if you have a database that has Last Name and SSN, you could you this action to fill the popup with the last name or the SSN.   You can specify any database and any TEXT or NUMBER field.

The PopD is actually a 'PopD' resource editor.  It behaves identically to .Popup with the exception that you can specify that it should link related fields.  Use "Link" to link or anything else to make no link (e.g. "NoLink" or "None").

This action must be called before any other actions in this library are called.  If a Creator ID and Type are provided, then the user will be presented with a list of files matching those parameters.  The user may then select a file and tap OK and the actions following this will be executed.  If the user taps cancel, then the actions following this command are ignored.

You can use this method to set or reset the attributes of an application or database.  You can either turn ON or turn OFF the attributes - so if you have to turn some on, and some off, then it will take two calls of this action.  Existing attributes are retained, so, for instance, if you turn on BACKUP, it will not effect READONLY.

 The numeric values in the above table can be added together to combine attributes into a single group.

Basically, this is similar to the $rsrc.Source action except based on OS version rather than the user selecting the file manually.  This action will select one of the provided filenames based on the user's OS version.  If less than 3.5, then the first file is selected for use.  If the version is 3.5 and less than 5.0, then the second file is chosen.  If a third file was provided, it is used when it's OS 5.0 and up.

This is used to set the startup form to a different form than is currently using.  This action applies only to the calling application.  It will not modify resources in another app. 

This action provides support  for scrolling tables horizontally (by columns).  $Rsrc.Table.Cols defines all the columns that are to be in your table.  This action should be in your startup script.  You can only have one $Rsrc.Table.Cols per table as it generates a "Actf" resource with the table ID as it's ID.

Defining Table Columns

The $Rsrc.Table.Cols action requires the table ID as the first parameter.  Then you give it the total number of columns you want to show.  This total value must be in the range of 1 to 5 (max).  Every table may have 0 or more columns frozen, that is, not scrollable and always in the table.  This value must be 0 to showCols-1.  A value of 0 would mean that no columns are frozen.  The last set of parameters are pairs of Field ID and Column Width for that field.  Currently, all scrollable fields should have the same width.  Technically, you can vary the width as long as the total of any set of scrollable columns widths is always the same: 20, 40, 20, 40, 20 (any two consecutive columns total 60).

Your table definition as defined in PDAT must match the first n columns of this action.

Scrolling

You scroll by placing two buttons on the form.  The one used to scroll the table left should have the $Rsrc.Table.Scroll action specifying the table ID and the word "Left".  The one used to scroll the table right should have the $Rsrc.Table.Scroll action specifying the table ID and the word "Right".

When the user taps either button, the 'Tabl' resource is loaded and modified according to the columns defined above.

This action provides support  for scrolling tables horizontally (by columns).   Once the table has been defined with $rsrc.Table.Cols, you have two buttons/graphics that use the $Rsrc.Table.Scroll actions to scroll the table 1 column to the left or right.  The reset keyword is used to reset the columns back to the first column.  This action may not be used in the Startup Script.

Defining Table Columns

The $Rsrc.Table.Cols action requires the table ID as the first parameter.  Then you give it the total number of columns you want to show.  This total value must be in the range of 1 to 5 (max).  Every table may have 0 or more columns frozen, that is, not scrollable and always in the table.  This value must be 0 to showCols-1.  A value of 0 would mean that no columns are frozen.  The last set of parameters are pairs of Field ID and Column Width for that field.  Currently, all scrollable fields should have the same width.  Technically, you can vary the width as long as the total of any set of scrollable columns widths is always the same: 20, 40, 20, 40, 20 (any two consecutive columns total 60).

Your table definition as defined in PDAT must match the first n columns of this action.

Scrolling

You scroll by placing two buttons on the form.  The one used to scroll the table left should have the $Rsrc.Table.Scroll action specifying the table ID and the word "Left".  The one used to scroll the table right should have the $Rsrc.Table.Scroll action specifying the table ID and the word "Right".

When the user taps either button, the 'Tabl' resource is loaded and modified according to the columns defined above.

This action will change the filtering comparison fields. 

NOTE: This action is available only in OS 3.5 and up.

This is used to set the color used in tables as the alternate row color.  If you pass this action the word "Select", then the user will be shown the standard OS color table to choose a color.  If zero (0) is passed to this action, then alternating rows is turned off.  If a value is passed, then that value is treated as the color. 

This action applies only to the calling application.  It will not modify resources in another app.  

The source file that gets the new resource is either selected or if not selected, then it's the application.  Existing strings are expanded and overwritten, new strings are created.  You may have several strings specified.

Each string may be a normal double-quoted string with special commands embedded into them.  The following table illustrates the commands than may be embedded into the string:

This program is not Freeware.  It is Shareware.  This means that you can, and should, try the demo out before buying.  Shortly after you register via PayPal, PalmGear, or Handango, you will receive an unlock key that will enable developing with this library.

 The cost of this package is US$7.95.

You can always contact me at:

email: Rick@SandsUSA.com or at my site http://www.SandsUSA.com.

"The Software" is "Runtime Resource Editor Library" aka "PDATRsrc.prc" by Richard R. Sands dba Sands USA.

DISCLAIMER #1 - MUST READ

This product is an "After-Market" utility for PDA Toolbox(tm) and as such, is subject to obsolescence by changes in PDA Toolbox or the Palm OS(tm) itself.  This cannot be prevented.  I may choose to stop or limit development and support of this product if such situation occurs. 

USER LICENSE AGREEMENT

This Agreement sets forth your licensed rights to use "The Software" and is granted to you upon condition that you accept the terms of this license. Your electronic indication of agreement, or your use of the program constitute acceptance of all of the terms of this license.

The program copy and documentation are furnished to make "The Software" available for your use and remain the property of Sands USA.

IF YOU DO NOT AGREE WITH ANY PART OF THIS LICENSE, DO NOT USE THIS SOFTWARE. Delete "The Software" and all associated files from all media on which it has been copied. 

LICENSE TERMS AND CONDITIONS

THE LICENSED PRODUCT
"The Software" comprises copyrighted computer programs and utilities for the reporting of Palm OS(tm) application databases (PRC) created by the PDA Toolbox(tm) Application Generator. The Licensed Product in its entirety is protected by US and foreign copyright.  YOU MAY NOT DISTRIBUTE THE LICENSE CODE provided to you.

YOUR USE OF THE LICENSED PRODUCT
General Use. You have the right to use "The Software" with PDAT/Advanced and to distribute the library file "PDATRsrc.prc" but not documentation, license codes, or other information about this library.  For those purposes, you have the right to install the "The Software" and any associated files on one (1) computer. Use of "The Software" on a network or any other arrangement by which its functions are accessible to more than one user at a time is not permitted. 

LIMITATIONS ON USE
General Use Limitations. You have no right to reproduce, transfer, publish or otherwise distribute either the "The Software" software, or any components or documentation provided.

ALL RIGHTS NOT SPECIFICALLY GRANTED BY THIS LICENSE ARE RESERVED BY SANDS USA. 

WARRANTIES, WARNING, DISCLAIMER

Warning and Disclaimer of All Warranties. THE PROGRAM IS FURNISHED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, IN ALL JURISDICTIONS WHERE ALL WARRANTIES MAY BE DISCLAIMED IN THE LICENSING OF INTELLECTUAL PROPERTY.

PDAT/Advanced, ShellReg, ShellMaker, DeskReg, and MyName is Copyrighed by Richard R. Sands dba Sands USA

PDAT Toolbox is Copyrighted by Paul Prejean

Nutshell executable and documentation are Copyright ©2002 by Ecamm Network. All rights reserved.

RsrcEdit is apparently not copyrighted by Quartus, but they are the caretakers of RsrcEdit.

Windows is a Trademark of Microsoft Corporation

Documentation Copyright (C) 2002-2004 Richard R. Sands dba Sands USA
All Rights Reserved

And Finally, ...

Palm OS, Palm Computing, HandFAX, HandSTAMP, HandWEB, Graffiti, HotSync, iMessager, MultiMail, Palm.Net, PalmPak, PalmConnect, PalmGlove, PalmModem, PalmPoint, PalmPrint, and PalmSource are registered trademarks of Palm, Inc.  Palm, the Palm logo, MyPalm, PalmGear, PalmPix, PalmPower, AnyDay, EventClub, HandMAIL, the HotSync logo, PalmGlove, Palm Powered, the Palm trade dress, Smartcode, Simply Palm, WeSync, and Wireless Refresh are trademarks of Palm, Inc.