MnuPak 0ß5 by Cédric Vidal released the 4th June 2000

1. What's this ?
2. Requirements / Installation
3. Missing features
4. Known bugs
5. Credits
6. About
7. History
8. OK, How do I use this wonderful program :o)
    8.1 Explanations (what you need to know)
    8.2 Arguments
    8.3 Returned value

9. Exemples (contains detailed explanations and pictures)
    9.1 Simple exemple
    9.2 Complex exemple
    9.3 How to use the result stored in mnu_res

10.Warning !!!!!! read this please.
    (comments about the choices taken for this prog)

1. What's this ?

Powerfull menu system for BASIC users.
It features:
- UNLIMITED SUBMENUS
- an efficient (i hope) argument system.

It DOES NOT use the internal menu system, I made MnuPak from scratch in C with TIGCC and Zeljko Juric's TIGCCLIB.
This permits future nice additions :o)

I tried to make it the easiest to deal with an unlimited depth architecture. Please, if you have any idea of an easier or more efficient argument system, email me.

2. Requirements / Installation

It requires no shell, well just nothing. It should work on any hardware and any rom version. Please email me if i'm wrong. I have only tested it on a ti89 HW 1 rom 1.00 and 2.03
Please tell me if it works on a TI92.
Just copy he following files on your calc and you're on your way:

3. Missing features:

- there is just a little text arrow at the right of items indicating submenus. This will be fixed soon, I really don't like that.
- there is nothing indicating that a menu contains more items than those shown. Although the scrolling system works just great.
- the first menu appeares on top left of the screen. This will be changeable sometime. Notice that all submenus are placed smartly on the screen (If you notice any misplacement, please email me)
- NO APD !!!!!

4. Known bugs:

None (for now). Please give me any feedback.

5. Credits

Thanx goes to:

    Xavier VASSOR for tigcc
    Zeljko Juric for tigcclib
    Rusty Wagner for Virtual Ti.

6. About:

    Cédric Vidal aka CedFoo or CFu
    Student in maths sup in Paris France.
    mail:    cedfoo@chez.com
    web:    http://www.multimania.com/cedfoo/

7. History

8. OK, How do I use this wonderful program :o)

8.1 Explanations (what you need to know)

MnuPak is based on lists. They are stored as lists under the name mnu_xxxx where xxxx is the ID of the menu. The ID is a positive number ranging from 0000, 0001, 0002 ... to 9999. Menu names are always 8 chars long. There can be up to 10000 menus. There is no differences between menus and submenus. Each menu is stored as a list whose first item is the title of the menu.

The actual difference is that the title of the first menu to be displayed will not be shown in the present version of MnuPak. But even if it's unused, the title must be there. The FIRST ITEM OF THE LIST WILL ALWAYS BE ASSUMED TO BE THE TITLE OF THE MENU.

Each menu is consisted of STRINGS and/or POSITIVE INTEGERS only. Strings will simply be displayed. Integers represent the ID's of submenus.

The power of this system is that you can refer to the same submenu from different menus, and menus can even contain themselves.

8.2 Arguments

You give to mnu_shw the ID of the first menu to be displayed (the parent).

8.3 Returned value

Because of the rom 2.03 's limitations, the result will be returned in mnu_res.
mnu_shw returns a two column matrix representing the path the user chose.
mnu_res contains in the first column the ID's of the menus the user entered in, and in the second column the numbers of the corresponding items the user selected.

Note that if the user pushed the esc button, then mnu_shw returns an empty list {} because TIOS doesn't accept as far as I know empty matrices.
Important, the first line of the matrice contains the menu ID and the line number of the  LAST item the user clicked on.

Note that in this version and until I find it stupid or anybody with a constructive reason email me it's stupid, you can select the title of a submenu and mnu_shw will return the position of the submenu in its parent menu (am I clear here ?!?).

If you have any other question, don't hesitate to email me.

9. Exemples

9.1 Simple exemple: (similar to the use of the internal function popup)

	Store a menu whose title is "mnu_0001" and contains 4 items in mnu_0001: {"mnu_0001","item1","item2","item3","item4"}->mnu_0001 show that menu: mnu_shw(1)
	Select the 3rd item
	mnu_shw returns in mnu_res [1,3] where 1 is the ID of the menu containing the item we selected and 3 is the item number of the item we selected.

9.2 Complex exemple: use of submenus, here only one submenu but there can be as many as you want.

	Store a menu whose title is "mnu_0002" and contains 5 items in mnu_0002 {"mnu_0002","item2.1","item2.2","item2.3","item2.4","item2.5"}->mnu_0002 (Of course, the title can be anything, "mnu_0002" has been chosen for clarity)
	Store a menu whose title is "mnu_0001" and contains 3 items and a submenu in mnu_0001 {"mnu_0001","item1",2,"item3","item4"}->mnu_0001
	Select the 5th item of the submenu
	mnu_shw returns in mnu_res [[2,5][1,2]]. The important part is [2,5]. It indicates that the user selected the 5 th item of the menu whose ID is 2 that is "mnu_0002". The remaining items of the matrix can be used in complex menus to determine the path chosen by the user :o) This is important, because the same menu can be used several times.

9.3 How to use the result stored in mnu_res
(I'll be referring to the exemple given in 9.2.)

You can obtain the name of the menu containing the item that the user selected with mnu_name(mnu_res[1,1]).
The same way, the number of  the item the user selected is mnu_res[1,2]

For exemple, if you want to get the name of the item that the user selected, one method is the following:
mnu_name(mnu_res[1,1]) -> m_name    name of the menu
mnu_res[1,2] -> pos                                 position of the item
#name[pos] -> i_name                             name of the item
should return "item2.5"

The following is more efficient if you only need the name of the item (ie no other information needed):
(mnu_get(mnu_res[1,1]))[mnu_res[1,2]] -> i_name
should return "item2.5"

Please, note that mnu_name is a basic prog, so it is slow, you should store its result in a var, and refer to it with the var. Same goes for mnu_get because it calls mnu_name.

10. Warning

The menu system may be subject to changes.

Some of you may think that the fact that the menu must be named mnu_xxxx is a limitation, xxxx being made of the ID of the menu. (and actually I think it is a problem). But I made this choice, because when I was planning this prog, I imagined a recursive system, which could have been done on the rom 1.00 and which was based on those mnu_xxxx vars.

My original idea was the following recursive architecture:

a menu constructor:
int mnu_mk(STRING title, LIST items)
    would create a new random ID number
    would store the newly created menu in a list called mnu_xxxx, xxx being computed with the given ID
    would return the given ID

a simple menu would then be:
    mnu_mk("title", {"item1","item2","item3"} )

and there comes the interesting point, a complex menu, ie a menu with submenus would then be:
    mnu_mk("title1", {"item1", mnu_mk("title2", {"item2.1","item2.2","item2.3"} ),"item3"} )->mnu_id

    which is equivalent to the following:
        mnu_mk("title2", {"item2.1","item2.2","item2.3"} ) -> sub_id
        mnu_mk("title1", {"item1", sub_id,"item3"} ) -> mnu_id

the main function would be:
MAT mnu_shw(ID menu_id)

to show your menu, you would do:
    mnu_shw(mnu_id) -> path    to show the main menu with its sub menu
    or mnu_shw(sub_id) -> path    to show only the sub menu    interesting !!!

or to show the main menu with its submenu directly:
mnu_shw( mnu_mk("title1", {"item1", mnu_mk("title2", {"item2.1","item2.2","item2.3"} ),"item3"} ) ) -> path

THE BIG PROBLEM IS THAT THIS FU!:,;!,:&é"é new rom 2.03 has removed the possibility for asm progs to return values that is to act as functions. So my first menu system is not portable to the rom 2.03.

The main consequence is that mnu_mk no longer exists, and that mnu_shw has become a simple prog, that is the returned matrix is stored in mnu_res. (and I don't like that). You have to store yourself the menu (see the exemples)

MnuPak should now work on any rom with no shell but without the original recursive architecture.

I decided to keep the compatibility with the rom 2.03 because it has a great new feature that keeps the archive after a crash, so I doubt that anyone would use the old rom 1.00, except maybe for games in conjonction with archive utility.

On the other hand, I know that the latest version of doorsos (DoorsOS 0.97 pre-version 2 at this time) enables asm functions on the rom 2.03, but I want my prog to be nostub (working without a shell).

In a future release, I may port MnuPak to doorsos in order to implement the original recursive menu system and to gain space. Any discuss about this issue is welcome.    mail me about that