# `MAX` — `mPOPUP`

## Contents

- `MAX` — Maximum value
- `mCARD` — Defines a menu card
- `mCASC` — Defines a menu cascade
- `MEAN` — Calculates a mean value
- `MENU` — Displays a menu
- `MID$` — Gets the middle part of a string
- `MIN` — Minimum value
- `mINIT` — Initialises menus
- `MIME` — Associates an OPL application with a MIME type
- `MINUTE` — Gets the current minute
- `MKDIR` — Creates a new folder
- `MODIFY` — Changes a record without moving it
- `MONTH` — Gets the current month
- `MONTH$` — Converts a numeric month to a string
- `mPOPUP` — Presents a popup menu

## `MAX` — Maximum value

Usage: `m=MAX(list)
`or `m=MAX(array(),element)`

Returns the greatest of a list of numeric items. The list can be either:

- A list of variables, values and expressions, separated by commas

or

- The elements of a floating-point array.

When operating on an array, the first argument must be the array name followed by `()`. The second argument, separated from the first by a comma, is the number of array elements you wish to operate on for example `m=MAX(arr(),3)` would return the value of the largest of elements `arr(1)`, `arr(2)` and `arr(3)`.

## `mCARD` — Defines a menu card

Usage: `mCARD title$,n1$,k1%
`or `mCARD title$,n1$,k1%,n2$,k2%` etc.

Defines a menu. When you have defined all of the menus, use MENU to display them.

`title$` is the name of the menu. From one to eight items on the menu may be defined, each specified by two arguments. The first is the item name, and the second the keycode for a shortcut key. This specifies a key which, when pressed together with Ctrl will select the option. If the keycode is for an upper case key, the shortcut key will be Shift+Ctrl.

The options can be divided into logical groups by displaying a separating line under the final option in a group. To do this, pass the negative value corresponding to the shortcut key keycode for the final option in the group. For example, `-%A` specifies shortcut key Shift+Ctrl+A and displays a separating line under the associated option in the menu.

Menu items without shortcuts can be specified using shortcut values between 1 and 32. For these items the value specified is still returned if the item is selected.

Other properties can be specified by adding one or more of the following flags to the shortcut keycode:

`KMenuDimmed%` | $1000 | Menu item is dimmed.
`KMenuSymbolOn%` | $2000 | Checkbox option button symbol on.
`KMenuSymbolIndeterminate%` | $4000 | Checkbox or option button symbol indeterminate.
`KMenuCheckBox%` | $0800 | Item has a checkbox.
`KMenuOptionStart%` | $0900 | Item starts an option button list.
`KMenuOptionMiddle%` | $0A00 | In the middle of an option button list.
`KMenuOptionEnd%` | $0B00 | Ends an option button list.

These constants are supplied in Const.oph.

The start, middle and end option buttons are for specifying a group of related items that can be selected exclusively (i.e. if one item is selected then the others are deselected). The number of middle option buttons is variable. A single menu card can have more than one set of option buttons and checkboxes, but option buttons in a set should be kept together. For speed, OPL does not check the consistency of these items’ specification.

If a separating line is required when any of these effects had been added, you must be sure to negate the whole value, not just the shortcut key keycode. For example:

        mCARD "Options","View1",%A OR $2900,"View2",-(%B OR $B00), "Another option",%C

Here, the second shortcut key keycode and its flag value is correctly negated to display a separating line.

A ‘Too wide’ error is raised if the menu title length is greater than or equal to 40. Shortcut values must be alphabetic character codes or numbers between the values of 1 and 32. Any other values will raise an ‘Invalid arguments’ error.

If any menu item fails to be added successfully, a menu is discarded. It is therefore incorrect to ignore `mCARD` errors by having an `ONERR` label around an `mCARD` call. If you do, the menu is discarded and a ‘Structure fault’ will be raised on using `mCARD` without first using `mINIT` again. See `MENU` for an example of this.

If more menu items are displayed in a menu card or cascade than are displayable on the screen, the menu will be drawn with a scroll bar. It is recommended that programmers do not define menus which scroll to keep the pen actions the user has to make to use the program to a minimum: see Defining the menus.

#### Compatibility

No changes need to be made to existing code to use this new functionality.

See also: `mCASC` and Menus.

## `mCASC` — Defines a menu cascade

Usage: `mCASC title$,item1$,hotkey1%,item2$,hotkey2%`

Creates a cascade for a menu, on which less important menu items can be displayed. The cascade must be defined before use in a menu card. For example, a ‘Bitmap’ cascade under the File menu of a possible OPL drawing application could be defined like this:

        mCASC "Bitmap","Load",%L,"Merge",%M
        mCARD "File","New",%n,"Open",%o,"Save",%s,"Bitmap>",16,"Exit",%e

The trailing `>` character specifies that a previously defined cascade item is to be used in the menu at this point: it is not displayed in the menu item. A cascade has a filled arrow head displayed along side it in the menu. The cascade title in `mCASC` is also used only for identification purposes and is not displayed in the cascade itself. This title needs to be identical to the menu item text apart from the `>`. For efficiency, OPL doesn’t check that a defined cascade has been used in a menu and an unused cascade will simply be ignored. To display a `>` in a cascaded menu item, you can use `>>`.

Shortcut keys used in cascades may be added to the appropriate constant values as for `mCARD` to enable checkboxes, option buttons and dimming of cascade items.

As is typical for cascade titles, a shortcut value of 16 is used in the example above. This prevents the display or specification of any shortcut key. However, it is possible to define a shortcut key for a cascade title if required, for example to cycle through the options available in a cascade.

If more menu items are displayed in a menu card or cascade than are displayable on the screen, the menu will be drawn with a scroll bar. It is recommended that programmers do not define menus which scroll to keep the pen actions the user has to make to use the program to a minimum: see Defining the menus.

See also: `mCARD`, `MENU`, `mINIT`, and Menus.

## `MEAN` — Calculates a mean value

Usage: `m=MEAN(list)`
or `m=MEAN(array(),element)`

Returns the arithmetic mean (average) of a list of numeric items. The list can be either:

- A list of variables, values and expressions, separated by commas

or

- The elements of a floating-point array.

When operating on an array, the first argument must be the array name followed by `()`. The second argument, separated from the first by a comma, is the number of array elements you wish to operate on for example `m=MEAN(arr(),3)` would return the average of elements `arr(1)`, `arr(2)` and `arr(3)`.

This example displays `15.0`:

        a(1)=10
        a(2)=15
        a(3)=20
        PRINT MEAN(a(),3)

## `MENU` — Displays a menu

Usage: `val%=MENU
`or `val%=MENU(var init%)`

Displays the menus defined by `mINIT`, `mCARD` and `mCASC`, and waits for you to select an item. Returns the shortcut key keycode of the item selected, as defined in `mCARD`, in lower case.

If you cancel the menu by pressing Esc, `MENU` returns 0.

If the name of a variable is passed, it sets the initial menu pane and item to be highlighted. `init%` should be `256*(menu%)+item%`; for both `menu%` and `item%`, 0 specifies the first, 1 the second and so on. If `init%` is 517 (=256*2+5), for example, this specifies the 6th item on the third menu.

If `init%` was passed, `MENU` writes back to `init%` the value for the item which was last highlighted on the menu. You can then use this value when calling the menu again.

It is necessary to use `MENU(init%)`, passing back the same variable each time the menu is opened if you wish the menu to reopen with the highlight set on the last selected item.

It is incorrect to ignore `mCARD` and `mCASC` errors by having an `ONERR` label around an `mCARD` or `mCASC` call. If you do, the menu is discarded and a ‘Structure fault’ will be raised on using `mCARD`, `mCASC` or `MENU` without first using `mINIT` again.

The following bad code will not display the menu:

        REM  ** example of bad code **
              mINIT
              ONERR errIgnore1
              mCARD "Xxx","ItemA",0      REM bad shortcut
        errIgnore1::
              ONERR errIgnore2
              mCARD "Yyy",""
              REM ‘Structure fault’ error (mINIT discarded)
        errIgnore2::
              ONERR OFF
              MENU                              REM ‘Structure fault’ again

If more menu items are displayed in a menu card or cascade than are displayable on the screen, the menu will be drawn with a scroll bar. It is recommended that programmers do not define menus which scroll to keep the pen actions the user has to make to use the program to a minimum: see Defining the menus.

See also: `mCARD`, `mCASC`, `mINIT` and Menus.

## `MID$` — Gets the middle part of a string

Usage: `m$=MID$(a$,x%,y%)`

Returns a string comprising `y%` characters of `a$`, starting at the character at position `x%`.

E.g. if `name$="McConnell"` then `MID$(name$,3,4)` would return the string `Conn`.

## `MIN` — Minimum value

Usage: `m=MIN(list)`

or `m=MIN(array(),element)`

Returns the smallest of a list of numeric items. The list can be either:

- A list of variables, values and expressions, separated by commas

or

- The elements of a floating-point array.

When operating on an array, the first argument must be the array name followed by `()`. The second argument, separated from the first by a comma, is the number of array elements you wish to operate on for example `m=MIN(arr(),3)` would return the minimum of elements `arr(1)`, `arr(2)` and `arr(3)`.

## `mINIT` — Initialises menus

Usage: `mINIT`

Prepares for definition of menus, cancelling any existing menus. Use `mCARD` and `mCASC` to define each menu, then `MENU` to display them.

It is incorrect to ignore `mCARD` or `mCASC` errors by having an `ONERR` label around an `mCARD` or `mCASC` call. If you do, the menu is discarded and a ‘Structure fault’ will be raised if there is an occurrence of `mCARD`, `mCASC` or `MENU` without first using `mINIT` again. See `MENU` for an example of this.

See also: `mCARD`, `mCASC` and Menus.

## `MIME` — Associates an OPL application with a MIME type

Usage: `MIME pri%, dtype$`

Associates an OPL application with the Internet MIME content type `dtype$`, using priority `pri%`. This command can only be used in the scope of an `APP`...`ENDA` construct. The priority value specifies how proficient the application is at handling the named data type. `dtype%` is the name of the data type this app is declaring that it can handle, e.g. `text/html`, `image/png` or `text/plain`.

Declaring a MIME association indicates to the system that the application allows the user to view or manipulate files and data of the named type.

`pri%` can take any of the following values:

`KDataTypePriorityUserSpecified%` | `KMaxInt%` | Reserved for future use.
`KDataTypePriorityHigh%` | 10000 | This app is superbly capable of handling this data type.
`KDataTypePriorityNormal%` | 0 | Typical priority. App is proficient at handling this data type.
`KDataTypePriorityLow%` | -10000 | App is merely capable of handling this document type.
`KDataTypePriorityLastResort%` | -20000 | App should only handle this data type if there are no other apps available which can use it.
`KDataTypePriorityNotSupported%` | `KMinInt%` |

These constants are supplied in Const.oph. Note that `KDataTypePriorityUserSpecified%` is reserved for future use.

The `.aif` file (application information file) for the app is used to store this information once the app has been translated. Only one MIME association is allowed per application, so only one `MIME` statement can be made in an OPL application’s `APP`...`ENDA` declaration.

There are recognisers in the ROM for the following MIME types:

- `text/plain`
- `text/html`
- `image/jpeg`
- `image/gif`
- `text/X-vCard`
- `text/X-vCalendar`

#### Compatibility

An translated application using the `MIME` keyword and its `.aif` file can be installed and run successfully on a pre-ER5 device; however on pre-ER5 machines, the MIME recognition functionality will not be present.

It is not possible to translate OPL source code using the `MIME` keyword under versions of EPOC prior to ER5.

See also OPL applications and OPL and MIME .

## `MINUTE` — Gets the current minute

Usage: `m%=MINUTE`

Returns the current minute number from the system clock (0 to 59).

E.g. at 8.54am `MINUTE` returns `54`.

## `MKDIR` — Creates a new folder

Usage: `MKDIR name$`

Creates a new folder/directory. For example, `MKDIR "C:\MINE\TEMP"` creates a `C:\MINE\TEMP` folder, also creating `C:\MINE` if it is not already there.

## `MODIFY` — Changes a record without moving it

Usage: `MODIFY`

Allows the current record of a view to be modified without moving the record. The fields can then be assigned to before using `PUT` or `CANCEL`.

## `MONTH` — Gets the current month

Usage: `m%=MONTH`

Returns the current month from the system clock as an integer between 1 and 12.

E.g. on 12th March 1992 `m%=MONTH` returns `3` (`KMarch%`) to `m%`.

`KJanuary%` | 1 | `KJuly%` | 7
`KFebruary%` | 2 | `August%` | 8
`KMarch%` | 3 | `September%` | 9
`KApril%` | 4 | `October%` | 10
`KMay%` | 5 | `November%` | 11
`KJune%` | 6 | `December%` | 12

These constants are supplied in Const.oph.

## `MONTH$` — Converts a numeric month to a string

Usage: `m$=MONTH$(x%)`

Converts `x%`, a number from 1 to 12, to the month name, expressed as a three-letter mixed case string.

E.g. `MONTH$(KJanuary%)` returns the string `Jan`.

See `MONTH` for the month number constants.

## `mPOPUP` — Presents a popup menu

Usage: `mPOPUP(x%,y%,posType%,item1$,key1%,item2$,key2%,...)`

Presents a popup menu. `mPOPUP` returns the value of the keypress used to exit the popup menu, this being 0 if Esc is pressed.

Note that `mPOPUP` defines and presents the menu itself, and should not and need not be called from inside the `mINIT`...`MENU` structure.

`posType%` is the position type controlling which corner of the popup menu `x%,y%` specifies and can take the values:

`KMPopupPosTopLeft%` | 0 | Top left.
`KMPopupPosTopRight%` | 1 | Top right.
`KMPopupPosBottomLeft%` | 2 | Bottom left.
`KMPopupPosBottomRight%` | 3 | Bottom right.

These constants are supplied in Const.oph.

`item$` and `key%` can take the same values as for `mCARD`, with `key%` taking the same constant values to specify checkboxes, option buttons and dimmed items. However, cascades in popup menus are not supported.

For example

        mPOPUP (0,0,0,"Continue",%c,"Exit",%e)

specifies a popup menu with 0,0 as its top left-hand corner with the items ‘Continue’ and ‘Exit’, with the shortcut keys Ctrl+C and Ctrl+E respectively.

See also `mCARD`.