WIP
Introduction
Since patch 2.5 is finally out, I decided to release a little tutorial on menus I wrote some time ago. It will especially describe the new menu commands coming with patch 2.5.
To fully understand this tutorial you should at least know how arrays work, because they are the basis for menus.
Other than that, there is not much to know.
Index
1. lib.scrat.format
Files:
Purpose
This library formats input data for menus. The input is an array of arrays which can either represent rows or columns and the library outputs a menu array, ready to be used in a custom menu. The advantage of this library over the manual approach is, that you have to specify your column format only once and it will automatically be applied to your input data. Additionally your code becomes more compact and less error prone.
Example usage
Arguments
| Name | Type | Description | Default |
|---|---|---|---|
| arrays | Var/Array | Array of arrays, which hold the rows or columns to be formatted | None |
| column format | Value | Describes how columns should be formatted | Left aligned with calculated widths |
| format | Var/Number | Describes format of input data | Row major |
| menu type | Var/Number | Describes for which menu type the input data is formatted | Small menu |
| page ref | Var/Number | Reference page id for integer entries | None |
Detailed information
Input
The library takes an array of arrays as input. Each array can either represent a row (as seen in the usage example) or a column.
Column format
The column format can be specified either explicitly or implicitly.
Explicit formatting
To explictly tell the library how the columns should be formatted simply pass it an array of integers with the formatting values. The library then will use these exact integers to format the menu. This way of formatting a menu can be seen in the usage example above.
Implicit format
There are two ways to implicitly format your menu. The simplest is to pass either 1 or -1 to the library, where 1 means that all columns will be left aligned and -1 means that all columns will be right aligned. The widths of each column will be calculated by the library depending on the texts that each column will hold. This algorithm is not heavily tested so might not always produce perfect results.
The second way to implicitly format your menu is to pass it an array of just 1s and -1s. Again 1 stands for a right aligned column and -1 for a left aligned one. The width of each column will again be calculated by the library. If you don't supply only 1s and -1s the library will use the array as an explicit format array. Following are two examples of implicit formatting:
Input format
To distinguish between row major (input arrays represent rows) and column major (input arrays represent columns) you have to specify an integer, which is either 0 or 1. 0 means that the input arrays represent rows, 1 means that they represent columns.
Menu types
Since there are two different custom menu types (normal and info) the library also has to consider those. This is done via the fourth parameter. Passing 'menu' to the library will make it use the width values for normal custom menus, passing it 'info' makes it use the width values for the info menu. This argument is of course only considered if the menu has to calculate the widths of each row by itself.
Item types
As you can see in the usage example normal menu items are created with their return value as the first array item and then the texts for the columns. In a similar manner all other item types have to be specified. All item types are supported of course and can be specified as stated in the following overview.
Menu item
| Index | 0 | 1...n |
|---|---|---|
| Content | return value | text1...textn |
To put the above structure in words, the menu item has the return value as the first array element and the texts for the columns in the following elements.
Info line
| Index | 0 | 1...n |
|---|---|---|
| Content | 'i' or 'info' | text1...textn |
In words: The info line has as the first element the string 'i' or 'info' which is followed by the texts for the columns.
Section
| Index | 0 |
| Content | 's' or 'section' |
|---|
The section is simple an array of one element containing the string 's' or 'section'.
Value selection
| Index | 0 | 1...n-1 | n |
| Content | 'v' or 'valsel' | text1...textn-1 | [value array, default, return id] |
|---|
Since the value selection has the most complicated structure, it deserves a longer explanation.
The first element is either 'v' or 'valsel'. The elements from 1 to n-1 are the texts for the columns, as in the other item types. Note that there is one text column less in a value selection since the last column is used by the selection. The last element of the value selection array should be known to you from the built-in command to create value selections. Here value array holds the values which are displayed and which can be chosen by the player, default is the default index into that value array and return id is the return id which is part of the return value of a menu containing a value selection. These three things packed together into an array make up the last element of the whole array.
As you see, creating a value selection for the library is not harder than creating one for the built-in command - you have to create the same data, but pack them differently.
Page Ref
Setting up the input array can get cumbersome, if your menu contains many texts from a text file. To avoid this, I recently added this parameter, which allows you to specify a reference page id for text lookup. Thus, if any element in the input array is an integer the corresponding text will be fetched from the specified page. Note that the script doesn't load any textfile. If the page doesn't contain a text with the given text id, the text will not be loaded, so you won't get ReadText errors.
Performance
For the best performance, the input data should be in row major order and the column format passed explicitly. Like this, the library will perfom merely more than assembling column format and input data together into a menu array. If the input data are in column major order, the library first has to transpose it into row major order, but even for large menus this turned out to be reasonably fast. Only if the library has to calculate the widhts of the columns by itself it can take considerably longer, depending on the size of your input data.
Dynamics
The library doesn't support dynamic menus directly. As you can see in the usage example, the input data are in a different format than the output data. Thus the library has to copy values from the input array into the ouptut array. So a change to the input array after it was passed to the library, will not change the contents of the output array. Of course you can still use the output array as a dynamic array, since it is a normal menu array. E.g. you could let the library build your menu once in a setup script and use it dynamically afterwards.