German documentation is available at http://www.mschei.de/cmndialog/pdatcdlib-de-help.zip

The Common Dialog Library (CDL) is a shared library for PDA Toolbox applications.  It provides commonly used dialogs to your application .  The common dialog library is compatible with both PDAT/Advanced and PDA Toolbox 6.0 Professional.

This library provides several extended time and date routines, a string input dialog, a popup category editor, and a note editor.  These dialogs either cannot be created in PDA Toolbox or are tedious to create.  All of these routines edit data in your database.

It is also used as a "Plug-In" to PDAT/Advanced to provide additional Actions to your PDA Toolbox programs.  PDAT 6.0 Pro requires the Windows "Plug-In" to support the Script Editor.

This manual assumes the reader has familiarity with the PDAT/Advanced application or the PDAT 6.0 Pro Script Editor.

The Common Dialog Library is a Shareware Library for the Palm OS 3.1 and above.  This library requires approx. 22k of memory storage.  For more information click here.

The Actions provided by this library are divided into several basic categories of functionality:

Text Editing Actions

• dlg.AskText - Displays a dialog with a prompt and allows user to enter text into a text field.
• dlg.AskText.Num - Displays a dialog with a prompt and allows user to enter text into a numeric text field.
• dlg.NoteEditor - Displays a full screen dialog to allow editing of a memo style text field.

Date Actions

• dlg.Select.Day - Dialog to select a single date.
• dlg.Select.Month - Dialog to select a date by month.
• dlg.Select.Week - Dialog to select a date by week.

Time Actions

• dlg.Select.Now - An alert that will reset a time back to now.
• dlg.Select.Time - Selects a single time.
• dlg.Select.Times - Selects two times - a start and ending time.
• dlg.TimeEditor - Enter one or two times using a numeric keypad.

PopUp Category Action

• dlg.CatEditor - A popup list editor similar, but more powerful, than the Palm OS Category Editor.
• dlg.PickList - A popup list used solely for selection.

Numeric Text Editing Actions

• dlg.NumEditor - A popup list editor similar, but more powerful, than the Palm OS Category Editor.
• dlg.NumEditorEx - A popup list used solely for selection.
• dlg.CalcEditor - A popup calculator with editable text field.
• dlg.IPEditor - A specialized numeric editor for internet protocol (IP) addresses

Dialogs Samples

dlg.AskText, dlg.AskText.Num	dlg.CalcEditor	dlg.CatEditor	dlg.IPEditor
dlg.NoteEditor	dlg.NumEditor	dlg.NumEditorEx	dlg.PickList
dlg.Select.Day	dlg.Select.Week	dlg.Select.Month	dlg.Select.Now
dlg.Select.Time	dlg.Select.Times	dlg.TimeEditor (1 time)	dlg.TimeEditor (2 times)

PDA Toolbox 6.0 Pro Script Editor

To use this library with the Pro Script Editor, you need to download the PDA Toolbox Windows Plug-In for the Common Dialog Library.  This is available at www.SandsUSA.com/PDAT.  Follow the installation instructions contained within the archive.

The primary difference between using these actions with PDAT/Advanced and the Pro Script Editor is that the Script Editor does not require the leading "$" for each action.  In addition, in PDAT/Advanced, you can can wrap your action statements with carriage-returns and in the Script Editor, you must use the "_" line continuation character.

For PDAT/Advanced Only

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 "PDATCDLib.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 "Common Dialogs Library" is not shown in the list, tap the "Add" button.
4. In the "Add Library" dialog, enter in the Library ID of "Pcdl" ( without the quotes.  The "l" is an lowercase "L").
5. Next, enter the license information you received when you registered or tap ok to run in DEMO MODE.
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 DEMO MODE will allow you to compile your application with PDAT/Advanced and the Common Dialog Library, but will display a "Nag" alert every time the library is invoked.

The file "PDATCDLib.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.  

For all dialogs, if the record being edited is new, then the record is created and becomes the "current record."  Note: The record is created at the end of the database without regards to the current sort order.  If you want to have the record sorted, you must do a sort action upon return.

The title parameter may include special coding to insert special characters or database fields. The following table shows the available codes: 

Displays a dialog to input text. Show the "prompt" as the question, and the "default" as the default value.  Both prompt and default parameters should be double-quoted if they contain spaces or commas. Both prompt and default may use the embedded codes described in the text coding section. The dlg.AskText.Num behaves as dlg.AskText but only allows digits and a decimal point. The title on this dialog is fixed to "Enter Text" for dlg.AskText, and "Enter Number" for dlg.AskText.Num.  This is not be customizable..

Displays an dialog to edit category-style databases. Category-Style databases must be limited to a single text field per record. This action does not require the database to be in existence. It will create the database with the "Backup Bit" set. Users may create new entries, edit existing entries, move entries up or down, delete and sort entries. The filename and title are limited to 31 characters.

with "nomove" option

The Option parameter has these values: nomove - Hides the NEW, Up/Down, Sort, Delete buttons. unique - Enforces new and edited categories to be unique. togglesort - Allows the sort button to behave as a toggle between sort A-Z and Z-A.  Default is to only sort by A-Z. all - Shows all buttons Options should be put in as lower-case (e.g. "all" is not "ALL").  You may join together multiple options as a quoted string with commas separating them (spaces ok, too): "unique, togglesort"

The TIP icon will display info about the buttons as appropriate to the mode (nomove or normal) the editor is being displayed in. 

The title parameter may include special codes as described in the special code table.

For sorted lists, the user may use Graffiti characters to quickly navigate through the list.  Characters are buffered up to a maximum length of 15 and are accumulative.  As the entered characters progresses, it will move the selection to the next matching item.  If no match is found, the non-matching character is tossed so a search string of "ABB" will match "AB" with the second "B" tossed.  This way, a user can enter in "ABBC" to match "ABC".  Any control character such as a backspace or carriage return will clear the buffer and reset it to the first item in the list.

This will edit the IP address contained in the field.  If there is no IP address or an invalid address (e.g. "Rick"), then the default address will be "0.0.0.0".  The IP address is validated whenever 3 digits are entered to be in the range of 0 to 3.  An empty field will result in a "0" being used. The title parameter may include special codes as described in the special code table.

This will popup a "Note/Memo" editor complete with support for the scrollbar, standard edit menu, and shortcuts. The title is limited to 31 characters. Notes are limited to 4096 characters. The title parameter may include special codes as described in the special code table.

This will popup a numeric editor.  The number/edit buttons are large so a finger can be used to tap the buttons.  Unlike the OS numeric keyboard, all keys are active including the minus sign.  The title is limited to 31 characters.  The title parameter may include special codes as described in the special code table.

This dialog is to be used as an alternative to a dynamic popup.  One of the advantages of this is that you can use the entire screen for selecting longer items. The user interface to support this can be a read-only text field with a button-graphic next to it.  You can also use this to create a "editable popup" by placing a text field that's editable and a small button-graphic next to it to use to select an item. The title parameter may include special codes as described in the special code table.

For sorted lists, the user may use Graffiti characters to quickly navigate through the list.  Characters are buffered up to a maximum length of 15 and are accumulative.  As the entered characters progresses, it will move the selection to the next matching item.  If no match is found, the non-matching character is tossed so a search string of "ABB" will match "AB" with the second "B" tossed.  This way, a user can enter in "ABBC" to match "ABC".  Any control character such as a backspace or carriage return will clear the buffer and reset it to the first item in the list.

Displays the "Date Picker" dialog with the title "Title". Sets the date into the fieldID.  This is the same dialog as the standard PDA Toolbox dialog, however, it will retain the value from the database. The title parameter may include special codes as described in the special code table.

Displays the "Month Date Picker" dialog with the title "Title". The "day" parameter may be one of the following values: A numeric value representing the date of the month (e.g. 1, 15, 30) "end" - End of the calendar month. Special care must be taken when dealing with the end of the month - use the "End" value. Sets the date into the fieldID. The title parameter may include special codes as described in the special code table.

Displays an alert asking to set the time to the current time and sets that value into FieldID if the user taps the OK button. The TaltID is the ID of an alert resource you create in your app. You can use the default Talt if provided the value "Default" instead of an ID.  The Talt message must have 3 replaceable parameters: ^1, ^2, and ^3.  ^1 = The FieldName value (e.g. "Starting Time") ^2 = The existing field's time value as a string (e.g. "11:45 pm") ^3 = The current time. The default alert's message is "^1 is set to ^2. Do you want to set to ^3?" The title is fixed to "Set Time To Now" and may not be changed.

Displays the single time "Time Picker" dialog with the title "Title". This will display a single-time dialogs. The existing times are used as the starting values. The title parameter may include special codes as described in the special code table.

Displays the "Start/End Time Picker" dialog with the title "Title". This will display a single dialog if the OS is 3.5 or greater, or show two single-time dialogs for OS < 3.5. If the two single time dialogs are shown, the title provided is ignored and instead "Select Start Time" and "Select End Time" is shown. The existing times are used as the starting values. The title parameter may include special codes as described in the special code table.  If the OS is less than 3.5 the title may not be changed.

Displays the "Week Date Picker" dialog with the title "Title".  The "day" parameter may be one of the following values: 0 - Sunday  1 - Monday  2 - Tuesday  3 - Wednesday  4 - Thursday 5 - Friday 6 - Saturday "start" - Start of week based on system preferences "end" - End of week based on system preferences Sets the date into the fieldID.   The title parameter may include special codes as described in the special code table.

This dialog can be used for a variety of time entry needs.  With it, you can request the user enter one time or two.  The times can be a mix of times and durations. If times are entered, they can be cross day boundaries.  If durations are entered, they can be longer than 24 hrs.  The "start" time does not need to be less than the "end" time.  These values can be stored in one of two ways according to the "type" parameter.  If the type is "text", then the time is stored as a text string compatible with text or number fields (numbers may not know how to interpret the time, though).  If the type is "time", then the time is encoded into the number of minutes since midnight.  The title parameter may include special codes as described in the special code table.  If the OS is less than 3.5 the title may not be changed.

 

Purchasing and Support Information

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

You may use the unregistered version for testing purposes only.  A nag alert will display as you run your application.

 The cost of this package is US$9.95.

The official support forum for this library is at www.PDATNutsAndBolts.com.   However, you can always contact me at:

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

"The Software" is "PDAT/Advanced Common Dialog Library" aka "PDATCDLib.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 "PDATCDLib.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. 

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 is Copyrighed by Richard R. Sands dba Sands USA

PDAT Toolbox is Copyrighted by Paul Prejean

PDA Toolbox "Professional" Copyrighted by Paul Anderson, Paul Prejean, Richard R. Sands

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.

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

And Finally, ...

palmOne, Zire, Tungsten, Treo, Blazer, VersaMail, Addit, Handspring, stylizations and design marks associated with all the preceding, and trade dress associated with palmOne, Inc.’s products, are among the trademarks or registered trademarks owned by or exclusively licensed to palmOne, Inc. All other brand and product names are or may be trademarks of, and are used to identify products or services of, their respective owners.