Display Screen Templates

Pimlical Android Help

Display Screen Template Formats

The Details view in Pimlical formats an appointment or a contact for a nice read-only display of information. These views, however, are not hard-wired as you might normally expect. They are in fact created from a format specifiation in a text file that the user has access to and which can be modified.

Now it goes without saying that this feature is for power users and not something that every user is expected to be able to handle! However, you can easily restore the original template from the install folder if you get stuck, and since you can make a small change and immediately see the result in Pimlical, neither is it quite as difficult as it might appear at first. All screen display templates use an identical command set which is described below.

The display in the Details view is completely user-defined from a template file with the name: DetailsScreenDisplayTemplate.txt. The template file consists of free-form text which can be formatted, field specifications which pull information from the selected record, and some special drawing commands to draw and fill rectangles, which can be used to create background panes, drop-shadow effects, borders etc. Task Views are formatted with a template called TasksScreenDisplayTemplate.txt

Similarly the display of a contact in the Contacts View is defined from a template file with the name LocalContactsScreenDisplayTemplate.txt (Note: if you are using Pimlical/Desktop and the old MDB databases, the file is called ContactsScreenDisplayTemplate.txt). Be sure to edit the file in the User Profile Folder (see path in the About dialog if you are unsure where this is). Do not edit the file with the same name from the Install Folder as you will use that to restore the file if it gets corrupted or you make a mistake that you do not know how to correct. In that event, just copy the file from the Install folder to the User Folder and you will have restored it to its original install default.

Formatting in the Template File

There are commands which simply take a field from the database and format it for display on the screen, and other commands that perform conditional tests to see if a field is present. The conditional tests make it possible to suppress the display of a field label if the field itself is blank.

The table below shows the available formatting commands:

Drawing Command	Description
[FillRectangle,x,y,w,h,R-G-B] Example: [FillRectangle,0,0,0,0,250-250-250	Fills a rectangle at X,Y with W-idth and H-eight in a color specified by an RGB string. A value of 0 for the width means extend to the right edge of the dialog (a negative value offsets to the left from that edge). A value of 0 for the height means extend to the bottom edge of the dialog (again with a negative value signifying an offset). In the example here, the entire dialog background is painted in an off-white color (Pure white would be 255,255,255).
[DrawRectangle,x,y,w,h,R-G-B]	As above except only the frame of the rectangle is drawn in the specified color.
[DisplayAt,x,y,w,h,just,fmt,font,color]	Displays all prior text (back to last DisplayAt or field specifiation) at the designated X/Y coordinates with W-idth and H-eight and justified left/right/center. Format (fmt) is always ignored in this command, but the Font (in the standard font format) and color as an RGB string can be present. Trailing spaces are always stripped from the string and line endings are ignored.
[{field}x,y,w,h,just,fmt,font,color]	Displays the field {field} from the current record. {field} is one of the fieldnames specified in the Table below. The remaining parameters are identical to those used in the DisplayAt command.
[DisplayUserIcons,x,y]	Displays User Icons at position X,Y on the screen. User Icons are drawn from left-to-right. A negative X value indicates the starting position is X pixels from the right edge of the screen.
[DisplaySystemIcons,x,y]	Displays System Icons at position X,Y on the screen. System icons are drawn from right-to-left. A negative X value indicates the starting position is X pixels from the right edge of the screen.
[DrawLine,x1,y1,x2,y2,color]	Draws a line from (x1,y1) to (x2,y2) with an optional color specified.
[DrawLineTo,x,y,color]	Draws a line from end of last line drawn to relativel position (x,y) with an optional color specified.

An RGB string consists of three decimal numbers in the range 0-255 separated by hyphens. For example, 255-0-0 is pure red (Red component is 255 - the maximum value, while blue and green components are 0), 0-0-0 is pure black and 255-255-255 is pure white, 0-0-255 is pure blue, etc. If in doubt, you can go into Pimlical’s Preferences, pick any color preference and play around with the slider to see what colors are generated by various numbers.

Field Specification

A field specifiation pulls information from the record using a field name (see Table below with all the names of the fields) along with positional and formatting information in this format:

[fieldname,x,y,width,height,justify,format,font,color]

x,y are the X/Y coordinates on the screen in absolute pixels, while width and height define the width and the height of the rectangular region in which the field information will be drawn. Long text (such as description or note text) will be word-wrapped to multiple lines if the height of the container provided is sufiient to display the text and the format character is set to the vertical bar (|).

Negative values for these four parameters have an important special meaning here:

X: negative value of -N means this items starts N pixels after the end of the prior item.
Y: negative value of -N means this item starts N pixels below the prior item.
Width: negative value of -N means this item extends to the current right edge of the dialog screen, less N pixels. A 0 value means use the current right margin of the screen.
Height: negative value of -N means this item extends to the current bottom of the dialog screen, less N pixels. A 0 value means use the bottom of the screen (but this is extended as far as as is needed to accomodate all text since the screen can scroll).

The above four parameters must always be present. The remaining parameters below are optional and may be omitted.

Justify is a single character ( < is left-justify, > is right-justify, = is center-justify, and | is left-justify using multiple lines if necessary).

Format is a single digit which provides additional control over the formatting of items. For Date items, 1 is short date format, 2 is medium date format and 3 is long date format. For Time items, 1 is short time format and 2 is long Time Format.

Font - specifies the font to be used in the standard font format of {FontName}-{Style}-{size} - so for example, “Arial-Bold-18” would specify an 18pt. bold Arial font.

Color - specifies the color to be used as an RGB value and defined by three numbers in the range 0-255 separated by hyphens, so for example, 255-0-0 would be pure Red, 0-0-255 would be Blue, 0-0-0 is black, 255-255-255 is white, etc.

If the characters [ ] { } need to be used in the free-form text, use a backslash in front of them so they are not interpreted as being a special character. For examle: \} would not prematurely end a conditional range.

Conditional Commands

In many cases, one does not want to display any text or a field if the field is blank or has some default value. So Pimlical includes conditional commands to test whether or not a field has something of interest.

A list of all the conditional commands is in the following table. Note that the use of negative parameters on the x/y/w/h coordinates are important as absolutely positioning would leave ‘holes’ if these conditional commands are used. In general, only the fist item should have absolute coordinates. Every subsequent item should use relative positioning commands.

IfString conditionals can be nested to any level (i.e. a conditional can be included inside another conditional). For example, in the example below, the location and status fields will never appear if the custom1 field is blank (colors are used here to make nesting more obvious)::

{ifCustom1?
{ifLocation?
Location: [DisplayAt,0,-20,90,0,>,0,Arial-Bold-12][location,-10,0,0,0,<]
}
{ifStatus?
Status: [DisplayAt,0,-20,90,0,>,0,Arial-Bold-12][Status,-10,0,0,0,<]
}
End custom 1}

Note that you can put a comment in front of a closing brace and it will be ignored - this can be helpful in documenting the
template when you are nesting conditional items so you know what item the closing brace goes with

Reversing the conditional test

You can reverse the meaning of an If conditional by putting the tilde character (~) in front of the if command as shown below:

{~ifTimed
{ifLocation?
Location: [DisplayAt,0,-20,90,0,>,0,Arial-Bold-12][location,-10,0,0,0,<]
}}

This would only include the location field for untimed events. Without the tilde, this would only include the location field for
timed events.

Table of Field Names for the Calendar/Tasks Database

*Database Field*	*Description*
ApptStartDate	Start Date for appointment (native date)
ApptStartTime	Start Time for appointment (native time)
AdjustedApptStartDate	Start Date as adjusted by timezone adjustment
AdjustedApptStartTime	Start Time as adjusted by timezone adjustment
ApptEndDate	End Date for appointment (native date)
ApptEndTime	End Time for appointment (native time)
AdjustedApptEndDate	End Date as adjusted by timezone adjustment
AdjustedApptEndTime	End Time as adjusted by timezone adjustment
PrimaryAlarm	Primary Alarm as Duration String
SecondaryAlarm	Secondary Alarm as Duration String
Repeat	Description of the repeat specification present
Description	Description field for event (aka "title' or 'Summary')
Note	Note Field for event (aka 'description' in other calendars)
Location	Location of event (could also be a linked, phone#)
Status	Status (Normal, Canceled, Completed, Deferred)
Type	Type (Busy, Free, Tentative, Out Of Office)
ApptType	Regular (“Appt”) or Floating event (“Float”)
FloatingDueDate	Due date of Floating event
Categories	List of category names
Advance	Advance on item as a Duration String
CustomAlarm	Text of the custom Alarm field
ForeColor	Foreground Color as an RGB Value
BackColor	Background Color as an RGB Value
Priority	Priority of event
Urgency	Urgency of event
Secret	returns “Private” or “Public” if set/clear
CustomField1	Custom Field contents
CustomField2	Custom Field contents
CustomField3	Custom Field contents
CustomField4	Custom Field contents
ActionTags	List of all Action Tags associated with event
CreationDate	Date on which event was created
Creator	User ID of individual creating event
Modifier	User ID of individual creating event
ModificationDate	Date on which item was last modified
DirtyFlag	True if this event was modifid on the most recent editing pass
Deleted	True if the item was deleted
Duration	The duration of the event as a standard Pimlical Duration (not actually a field in the database - calculated from Start and End date/times).

Table of Conditional Commands for the Calendar/Tasks Database

The table below includes all the conditional commands that can be used with the calendar database. The meaning in the right-hand column can be reversed in all cases below by putting tilde character (~) in front of the if:

*Conditional Name*	*Includes following items if the current record*...
ifNote	has a Note Field (or with Tilde(~) does not have a note field
ifRepeat	has a repeat specification
ifLocation	has a location (or phone number in location field) specified
ifCategory	has a category other than Unfiled (or with Tilde(~) in the Unfiled category)
ifCustom1	has a non-blank Custom 1 field
ifCustom2	has a non-blank Custom 2 field
ifCustom3	has a non-blank Custom 3 field
ifCustom4	has a non-blank Custom 4 field
ifAlarm1	has a primary alarm set
ifAlarm2	has a secondary alarm set
ifFloat	is a floating event
ifStatus	has a status type of other than Normal (or with Tilde(~) status type is Normal
ifType	has a type of other than Busy
ifAdvance	has an advance set on it
ifGroup	belongs to a group (GroupKey field non-blank)
ifPriority	has a priority set
ifUrgency	has an urgency set
ifuserIcon	has one or more user icons set
ifSystemIcon	has one or more system icons set
ifDateDiffers	has an event ending date different from the starting date
ifTimeDiffers	has an event time different from the starting time
iifTimed	is a timed event
ifPastDue	is a past-due floating event or task (appts are always treated as not past-due

Table of Field Names for the Contacts Database

Deleted	True if the Contact was Deleted
Modification_date	The date on which the contact was last modified
Modification_date_exists	True if there is a modification date for this contact
Creation_date	The date on which the contact was created in the database
Creation_date_exists	True if there is a creation date for this contact
Last_access_date	The date on which the contact was last accessed
Last_access_date_exists	True if there is a date on which the contact was last accessed
Prefix	Contents of the Prefix field
First_name	The first name of the contact
Middle_name	The middle name of the contact
Last_name	The last name of the contact
Suffix	Contents of the Suffix field
Nick_name	Nick name of the contact
Anniversary	Date of the Anniversary field for the contact
Anniversary_exists	True if this contact has an anniversary date
Birthday	Date fo the birthday for the contact
Birthday_exists	True if this contact has a birthday
Anniversary_alarm_set	True if an alarm was set for the anniversary of this contact
Anniversary_alarm_adv	The advance in days (ahead of the anniversary date) for which the alarm is to be set
Birthday_alarm_set	True if an alarm was set for the birthday of this contact
Birthday_alarm_adv	The advance in days (ahead of the birthday date) for which the alarm is to be set
Secret	True if this contact is marked as secret
Category	The category (or list of categories separated by commas) to which this contact belongs
Note	Contents of the Note field
Profession	Contents of the Profession field
Company	Name of the company
JobTitle	Job Title fo this contact
Street_1	The street number from the first address field
City_1	City from the first address field
State_1	State from the first address field
Zip_1	Zip/Postal Code from the first address field
Country_1	Country from the first address field
Street_2	Same as above for Second address field...
City_2
State_2
Zip_2
Country_2
Street_3	Same as above for Third address field...
City_3
State_3
Zip_3
Country_3
Street_4	Same as above for Fourth address field...
City_4
State_4
Zip_4
Country_4
AddressLabel_1	The label for the first address field (Home, work, etc.)
AddressLabel_2	The label for the second address field (Home, work, etc.)
AddressLabel_3	The label for the third address field (Home, work, etc.)
AddressLabel_4	The label for the fourth address field (Home, work, etc.)
Phone_1	First Phone number
Phone_2	Second Phone number
Phone_3	Third Phone number
Phone_4	Fourth Phone number
Phone_5	Fifth Phone number
Phone_6	Sixth Phone number
Phone_7	Seventh Phone number
Phone_8	Eighth Phone number
PhoneLabel_1	First Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_2	Second Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_3	Third Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_4	Fourth Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_5	Fifth Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_6	Sixth Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_7	Seventh Phone number Label field (Work, Home, Mobile, etc.)
PhoneLabel_8	Eighth Phone number Label field (Work, Home, Mobile, etc.)
Preferred_label	The label which is used by default for displaying the contact
Email_1	First Email address
Email_2	Second Email address
Email_3	Third Email address
Email_4	Fourth Email address
Email_5	Fifth Email address
Email_6	Sixth Email address
EmailLabel_1	First Email address Label (Work, home, etc.)
EmailLabel_2	Second Email address Label (Work, home, etc.)
EmailLabel_3	Third Email address Label (Work, home, etc.)
EmailLabel_4	Fourth Email address Label (Work, home, etc.)
EmailLabel_5	Fifth Email address Label (Work, home, etc.)
EmailLabel_6	Sixth Email address Label (Work, home, etc.)
Custom_1	Contents of the first Custom Contact Field
Custom_2	Contents of the second Custom Contact Field
Custom_3	Contents of the third Custom Contact Field
Custom_4	Contents of the fourth Custom Contact Field
Custom_5	Contents of the fifth Custom Contact Field
Custom_6	Contents of the sixth Custom Contact Field
Custom_7	Contents of the seventh Custom Contact Field
Custom_8	Contents of the eighth Custom Contact Field
Custom_9	Contents of the ninth Custom Contact Field
CustomLabel_1	Label for the first Custom Contact field
CustomLabel_2	Label for the second Custom Contact field
CustomLabel_3	Label for the third Custom Contact field
CustomLabel_4	Label for the fourth Custom Contact field
CustomLabel_5	Label for the fifth Custom Contact field
CustomLabel_6	Label for the sixth Custom Contact field
CustomLabel_7	Label for the seventh Custom Contact field
CustomLabel_8	Label for the eighth Custom Contact field
CustomLabel_9	Label for the ninth Custom Contact field
Url	Contents of the URL field (example: www.pimlicosoftware.com)
Photo	Base-64 encoded representation of the contact's picture (probably not useful to display!)
Picture_filename	The filename for the contact photo (if linked, rather than embedded)
Ringtone	Name/Path of the custom Ringtone associated with this contact
Unique_id	Contents of the UniqueID field for this contact
Favorite	True if this contact is a favorite
Custom_vcards	All the custom vCard statements (statements not defined in the vCard standard)
Inactive	True if this contact is inactive
VersionString	Not implemented at this time (for possible future use of defining the version of Pimlical used to create this contact?)
Fullname	The full name of the contact (assembled from other fields) as first name, middle name, last name
CompanyOrName	The company name, but if no company name, use the full name instead
NameorCompany	Full name, but if that is blank, use the company name instead
LastNameFirst	Full Name as Last name, comma, first name, middle name

Table of Conditional Commands for the Contacts Database

The table below includes all the conditional commands that can be used with the Contacts database. The meaning in the right-hand column can be reversed in all cases below by putting tilde character (~) in front of the if:

ifDeleted	True if the contact was deleted
ifModification_date	True if the contact has a modification date
ifCreation_date	True if the contact has a creation date
ifLast_access_date	True if the contact has a last access date
ifPrefix	True if the contact has an explicit Prefix field
ifFirst_name	True if the contact has a first name
ifMiddle_name	True if the contact has a middle name
ifLast_name	True if the contact has a last name
ifSuffix	True if the contact has a suffix
ifNick_name	True if the contact has a nickname
ifAnniversary	True if there is an anniversary date for this contact
ifBirthday	True if there is a birthday set for this contact
ifAnniversary_alarm_set	True if the anniversary has an alarm set
ifAnniversary_alarm_adv	True if the anniversary alarm has an advance set on it
ifBirthday_alarm_set	True if the birthday has an alarm set
ifBirthday_alarm_adv	True if the birthday alarm has an advance set on it
ifSecret	True if the contact is marked as secret
ifCategory	True if the contact is assigned to a category other than Unfiled
ifNote	True if the contact has a note field
ifProfession	True if the contact has a Profession field
ifCompany	True if the contact has a Company field
ifJobtitle	True if the contact has a Job Title
ifStreet_1	True if the contact has a non-blank street set in the First address field
ifCity_1	True if the contact has a non-blank city name set in the First address field
ifState_1	True if the contact has a non-blank State set in the First address field
ifZip_1	True if the contact has a non-blank Zip/Postal Code set in the First address field
ifCountry_1	True if the contact has a non-blank Country set in the First address field
ifStreet_2	same as above for the second address field
ifCity_2
ifState_2
ifZip_2
ifCountry_2
ifStreet_3	same as above for the third address field
ifCity_3
ifState_3
ifZip_3
ifCountry_3
ifStreet_4	same as above for the fourth address field
ifCity_4
ifState_4
ifZip_4
ifCountry_4
ifAddressLabel_1	True if the first address field has a label value
ifAddressLabel_2	...
ifAddressLabel_3	...
ifAddressLabel_4	...
ifPhone_1	True if the first phone field has a phone number
ifPhone_2	...
ifPhone_3	...
ifPhone_4	...
ifPhone_5	...
ifPhone_6	...
ifPhone_7	...
ifPhone_8	...
ifPhoneLabel_1	True if the first phone field has a label name
ifPhoneLabel_2	...
ifPhoneLabel_3	...
ifPhoneLabel_4	...
ifPhoneLabel_5	...
ifPhoneLabel_6	...
ifPhoneLabel_7	...
ifPhoneLabel_8	...
ifPreferredLabel	True if there is a preferred label set for this contact
ifEmail_1	True if the first Email field has an email address
ifEmail_2	...
ifEmail_3	...
ifEmail_4	...
ifEmail_5	...
ifEmail_6	...
ifEmailLabel_1	True if the first Email field has a label
ifEmailLabel_2	...
ifEmailLabel_3	...
ifEmailLabel_4	...
ifEmailLabel_5	...
ifEmailLabel_6	...
ifCustom_1	True if the first custom field is non-blank
ifCustom_2	...
ifCustom_3	...
ifCustom_4	...
ifCustom_5	...
ifCustom_6	...
ifCustom_7	...
ifCustom_8	...
ifCustom_9	...
ifCustomLabel_1
ifCustomLabel_2
ifCustomLabel_3
ifCustomLabel_4
ifCustomLabel_5
ifCustomLabel_6
ifCustomLabel_7
ifCustomLabel_8
ifCustomLabel_9
ifUrl
ifPhoto
ifpicturefilename
ifRingtone
ifUnique_id
ifFavorite
ifCustom_vcards
ifInactive
IfVersionString
iffullname
ifcompanyorname
ifnameorcompany
iflastnamefirst
ifAnyPhone