How to write SynCalc shortcuts

Intro

 So you want to write a SynCalc shortcut? Good for you! Shortcuts are what make SynCalc so useful for any calculation need. This guide will take you through the basics and touch on advanced topics so that you can write your own killer shortcuts!

In order to teach you how to write killer shortcuts, this web page will walk you through several examples which demonstrate all of the shortcut features, tips, and tricks the author of SynCalc could think of. The shortcuts used in this tutorial are included with SynCalc as "SCTutorial.pdb." You should follow along on SynCalc on your own PalmOS device.

The Basics

 The idea behind shortcuts is that you often need to enter the same calculations over and over again to get a particular result. Shortcuts take the repetion out of this process by allowing you to 'script' any calculation. When a shortcut is executed, SynCalc simply copies and pastes the shortcut into the main expression field.

What the heck is Avagadro's number again?

 Using shortcuts as constants

Relevant Shortcut: "Avagadro's Num"

The simplest shortcut is the idea of a constant. Say you often do chemistry calculations and thus use Avagadro's Number frequently. You could create a shortcut named "Avagadro's Num" with a value of "6.02e23". Whenever you need to use Avagodro's number in a calculation, simply choose it from the shortcuts list and voila! it is pasted into your calculation.

Using shortcuts as constants is pretty useful. But that's only the beginning. In this next example, we'll make a shortcut which calculates a 15% tip for a meal.

I don't feel like pushing the Equal button...

 Shortcuts that automatically calculate the answer
Relevant Shortcut: "15% Tip - Part 1"

There is a little more to shortcuts than just automatic copying and pasting. SynCalc knows to look for certain characters to do special tasks. One of those is the '=' character. When an '=' is found in a shortcut, SynCalc reacts by pressing the '=' button for you. We'll use a tip calculator as our next example, in which we use the '=' character to tell SynCalc that we want it to calculate the expression when we use this shortcut.

The value of our "15% Tip" shortcut is "*0.15=". To use it, we enter the cost of the meal into SynCalc, then choose "15% Tip" from the shortcut list. SynCalc adds "*0.15" to our expression and calculates the answer, which is displayed as normal in the answer area.

Advanced Topics

Don't make me ask you again...

 Using the in() feature
Relevant Shortcut: "15% Tip - Part 2"

This example will extend on the idea used above with the tip calculator. Using SynCalc's built-in in() function, you can have shortcuts prompt for user entry while they execute. The in() function will display a form and return to the expression the number entered by the user.

We've modified the "15% Tip - Part 1" shortcut to the following, now "15% Tip - Part 2":

in(Enter cost of meal:)*0.15=

Upon selecting this shortcut, an input query dialog will appear, with the prompt "Enter cost of meal:". The number you enter will then be used in the equation in place of the in(), which will be multiplied by 0.15, yielding the amount of a 15% tip for the meal price entered.

A few notes on in():
1) The first argument will be used as the 'prompt string.'
2) You need not enter a simple number in an input query; let's say, for instance, that your meal costs $35.18 WITH tax, and the tax is $2.76. Since you only want to tip the waiter on the meals subtotal, and since (for the sake of this example), the subtotal isn't on the bill, you can enter:

35.18-2.76

in the input dialog. How convenient!

Get out of my way!

 Clearing the expression field
Relevant Shortcut: "15% Tip - Part 3"

If you think it would be useful to have SynCalc hit the clear button before doing a shortcut, I like the way you think. Here's how to do it:

Make the first character of your shortcut a capital 'C'.

Cin(Cost of meal:)*0.15=

Now you can use this shortcut at any time without having to press the clear button first!

That's very pretty...

 Using the out() feature
Relevant Shortcuts: "Hello world" and "15% Tip - Part 4"

We're about to take this tip calculator to a ridiculous level... just remember it's all about education in the end. SynCalc has another great built-in feature, the out() function. For those of you who know what sprintf() is, you'll find out() very familiar. For those of you who don't, pay attention, because this is a little confusing.

The out() function takes in a minimum of 1 parameter. It always returns a value of 0. The first parameter is a text string. This string will be written to SynCalc's text console. The text console can be viewed by tapping the little note icon to the left of the answer area on SynCalc's main screen, or by choosing "Calc->View Console" from the menu. Here's the simplest example, enter (or choose the "Hello world" shortcut)

"out(Hello world)"

and press the equal button. The text console should pop up, with the words "Hello world" written in it. If the text console didn't pop up, tap the text console icon and make sure that "Auto-activate console" is selected.

The out() function becomes very cool when coupled with SynCalc's shortcut mechanism. It will allow us to use text to describe certain numbers that SynCalc generates. Let's add out() to our Tip Calculator. Here's what it looks like (the explanation is below):

in(Cost of Meal:)@c*0.15=out(\n15% tip for a $%n meal is: $%n, c, Ans)=

What?!?! you say? Ok, let's break it up into parts:

in(Cost of Meal:)@c*0.15=

This we've seen before... query with the prompt "Cost of Meal" and store the result in the variable 'c', then multiply by 0.15 and hit the equal button. On to the second part:

out(\n15% tip for a $%n meal is: $%n, c, Ans)=

The first parameter is the text which will be output, and the remaining numeric arguments are the numbers we want to write to the console:

ArgumentValue
1\n15% tip for a $%n meal is: $%n
2c
3Ans

The '\n' is a newline, so that the text starts on a new line. So what are those %n things? Well, since the out() function doesn't know automatically where to write out the number, the marker '%n' is used to signify where the number should go in the string. The numeric arguments are subsituted for %n in order from left to right. In this case, the value of 'c' will be substituted for the first %n, and the value of 'Ans' will be substituted for the second %n.

Try using this shortcut, entering 25 for the Cost of Meal, which should produce a tip of $3.75. Therefore, the value 25 will be stored in c, and the Ans will be 3.75. When out() executes, 25 will be written where the first %n is, and 3.75 will be written in place of the second %n. Your console should look like this:

15% tip for a $25 meal is: $3.75

Pretty cool, eh? A few more notes about the out() function:
1) For nice formatting, you can use '\n' for newline and '\t' for tab.
2) The character after the % tells SynCalc which output mode to use. Your choices are the same as for SynCalc's answer:
FormatUse
Normal%n
Fixed%f
Scientific%s
Hex%h

To be or not to be...

 Using the iftext() function
Relevant Shortcuts: "Conditional Output - Wrong 1", "Conditional Output - Wrong 2", and "Conditional Output - Right"

The Logic Plugin that comes with SynCalc contains a function called iftext(). This allows you to output different text depending on the results of a test. To explain the use of iftext(), we will create a shrotcut that provides the max() functionality, where max(a,b), returns the greater of the two. An advanced shortcut developer might think, why not use this:

out(\na is %n than b.,iftext(a>b,greater,not greater))=


Good idea, but unfortunately, it won't work. The arguments actually get calculated before the out() function gets to the %n, meaning that the above will actually write this to the console if a>b:

greater
a is 1 than b.

The '1' comes from the fact that iftext() returns 1 if true, else 0. What about this?

if(a>b,out(\na is greater than b),out(\na is not greater than b))=

Another good idea, but this will result:

a is greater than b
a is not greater than b

This occurs for the same reason as above. It's very simple to get your shortcut to do the intended thing:

out(\na is )iftext(a>b,greater,not greater)out( than b.)=

Fin.
That's all for the shortcut tutorial. I hope that you've learned a thing or two about SynCalc. If you come up with useful shortcuts you'd like to share with other SynCalc users, please submit them to the SynCalc Shortcut and Plugin Repository.




Copyright © 1997-1999 Synergy Solutions, Inc.