MC2 HOWTO [ MC2 ] : contacts
|
||||||||
MC2 HOWTO | ||||||||
While MC2 is being improved (I'd like to say so but actually I don't work on it much being busy with other things - Uhh) I want to provide some hints about MC2 internals (inspite nobody seems using it - that won't stop me :). In the text below there're some examples, I recommend you try them in a phone simulator such as Sun Wireless Toolkit (SUN WTK) - it's more convenient to type text there than on real phone.
|
||||||||
MC2 Lisp in worksheet formulas | ||||||||
Probably you have already heard that MC2 differs from old MC by using Lisp as a scripting language. I came to this idea when undestood that MC worksheet formulas can be repesented by Lisp s-expressions (s-exp for short reference). Let's do this experiment - enter into [A1] cell this formula:
Now if go to menu cell/edit lisp we'll see:
It's Lisp representation of the formula. In Lisp language each expression is represented by a list starting with '(' and ending with ')'. The first element of the list is often called functor, and it defines action to be performed with all rest arguments of the list. So in the expression above (sin 1.0) will call 'sin' function passing 1.0 float value as an argument. Then Lisp will calculate 'add' functor with 2 arguments - the result of 'sin' calculation and number 2 (it's an integer value in contrary with 1.0). Lisp scans s-expression from root to branches, and it recursivelly evaluates inner s-expressions (if any) before evaluate parent ones. That's all about MC2 Lisp I'd like to say right now, just to note that Lisp code can be entered in a cell.
|
||||||||
Lisp macro code | ||||||||
When evaluating s-exp in a cell formula, MC2 displays result of evaluation as cell value. So normaly we'll see in formulas functors representing functions (like 'sin' above) and operators (like 'add' functor represents '+' math operator). There's special routine in MC2 converting worksheet formulas to Lisp representation called 'worksheet formula parser'. Still functor may not only return some value but it may do some other 'side-effects'. Let's do one more experiment and enter this formula in a cell:
Just after this formula is enetered into cell, the cursor will move to 2 cells down (just like you ressed DOWN key twice). This is because cursor-move is a 'system' internally functor used by MC2 (BTW you can see this in MC2 log in SUN WTK, as MC2 reports what it's doing to console - it isn't shown in phone). The cursor-move functor takes 2 arguments:
One argument is the offset to move cursor from current location, 'axis' can be 0 if we want to move along X axis (columns) and 1 for Y axis (rows). Both arguments are integer numbers. The result of evaluation is special Lisp value called nil, and it's represented by an empty cell. We can show cell's formula on sheet via menu cell/show formula. (If you see '######' after that - change column width in menu column/fit). There are many 'system' functors like that in MC2, as a matter of fact everything you enter into MC2 is being internally performed by those functors, and you can use them whenever you like, in WS formulas as well (still of course it isn't the best place, I'll show a better place below). Moreover, you can define your own new functors (see below), in Lisp code or in Java language.
|
||||||||
Defining new functors and names | ||||||||
Now it's time to do one more experiment:
This will define a new function (and a functor) log10. It is missed in standard MC2 package, and in this way you can extend MC2 functionality. You can use this function in a WS formula::
It's worth mentioning that this new function definition will live only in current MC2 session (if you open other sheet in this session - it can be used). There're several ways to use this definition in new MC2 sessions, one of them (not best) could be to save an MC2 sheet with definitions, and to load the sheet next time before you start using the log10 function. It's not an elegant way, sure - it would be better to make MC2 know about this new definition just 'by default', without opening a sheets. And here goes another approach - we can place the definition into MC2 startup code. Now it's time to describe this.
|
||||||||
MC2 Startup code | ||||||||
Let's have a look at mc2lite.jad file (if you don't know what it means, say installed MC2 from network - it is another problem, I just don't want to discuss it here. Try to use SUN WTK for this experiments). In mc2lite.jad among other things, there's this line:
We can place our log10 definition near by (Startup.startapp) call, say so:
You may want to write a long Lisp program (actually Startup.startapp functor is Lisp code, just a 'preinstalled' one - we will talk about it a bit later). And in this case it would be more convenient to place your code in standalone file, say mycode.mc2, place it into .jar file, and load this file in startup:
I added definition of Faraday constant as well, just in case. After that we can use F name in WS formulas:
So you see setq is used to define names, in contrary with defun used for functors. Character ';' denotes comments in Lisp language, these lines are ignored till the end of line from ';'. Don't forget that the size of .jar file must be reflected in .jad file (as you add new data into .jar). Some emulators and most of phones will reject installing midlets with inproper size.
|
||||||||
Key binding | ||||||||
One of the reasons to implement Lisp support in MC2 was tu allow User Interface (UI) customization. As layout of handsets varies (in screen size, number of buttons, some vendor specific things, etc), it would be great to have features to customize UI, so that it could be done by an ordinary user without recompiling MC2 source code (Its original language is of course Java), just with editing some configuration data on the handset. In our case we will use Lisp in configuration file. It will allow us to define behavioural things as well as some constant definitions. A typical use of this feature is key bindings - we can assign lisp code to button pressed by user. Having that, we can incredible extend MC2 configurability. Now let's see how it is archived in MC2. There's set of 'binding' functions, to bind to a key we may use:
gameaction and keycode define the key to which the code is assigned. The code itself goes in functor argument. 'gameaction' and 'keycode' have come from J2ME MIDP programming (If you are a J2ME programmer - have a look at javax.microedition.lcdui.Canvas class constants) - gameaction can be:
gameactions are device-independed, each device can assign them to any suitable buttons. So say UP/DOWN actions on devices without joystick/arrows will be emulated by numeric keys (most likely '2' and '8'. Alternatively, you can bind to exact buttons (device specific as well), using keycodes. Here go keycodes for standard keys, from MIDP 1.0 specification:
You can bind both to gameaction and to keycode, if you don't need something - just set nil there screenmodemask defines what screen mode this binding applies to. screenmodemask is a bit mask of: 1/2/4/8 - NORMAL / GOLD / NUMERIC / FORMULA modes. NUMERIC screen mode is the mode when 'NUM:' string is displayed in status bar (there's column headers there in NORMAL mode). In FORMULA mode the cell address is shown in status bar, with the formula in current cell, say [A2]: =A1+34.1. GOLD mode - 'GOLD' string is in the status bar, and GOLD keys sequence is being entered. The purpose of GOLD mode is to support hot keys starting with GOLD key, by default it's the '#' button on phone keypad (can be customized in Lisp code as well). An example of binding to move cursor up:
-1 mask turns on this binding for all modes, gameaction=1 (GAME UP, see above), nil for keycode (so it is not specified), and the binded Lisp code
is
|
||||||||
User forms | ||||||||
There's a possibility to prompt user for entering some values in a binded Lisp code. When being executed this code will create a form, show it to user and then pass enetered values to lisp code. In binded code we can use special functor
|
||||||||
(C) 2001-2004 WAP Industrial |