shithub: pokecrystal

--- a/docs/menu.md

+++ b/docs/menu.md

@@ -1,7 +1,8 @@

-### Everything you've ever wanted to know about menus*

+# Everything you've ever wanted to know about menus*

-##### *but were afraid to ask

+**\* but were afraid to ask**

 ## Contents

 - [ScrollingMenu](#scrollingmenu)

@@ -10,12 +11,14 @@

 - [VerticalMenu](#verticalmenu)

 - [Misc/Generic](#miscgeneric)

-## ScrollingMenu

-This is the only menu that does scrolling. It doesn't draw any TextBox around the menu.

+## `ScrollingMenu`

+This is the only menu that does scrolling. It doesn't draw any `TextBox` around the menu.

 Structure:

-```

+```asm

 .MenuDataHeader:

 	db MENU_BACKUP_TILES ; flags

 	menu_coords 2, 4, SCREEN_WIDTH - 1, 13

@@ -32,7 +35,8 @@

 	dba Function3

```

-wMenuData2Flags:

+`wMenuData2Flags`:

```

 7: Select is functional

 6: Start is functional

@@ -44,9 +48,10 @@

 0: Call Function1 to display the cancel entry

```

-If the columns entry in MenuDataHeader2 of a scrolling menu is 0, Function2 isn't called either. It doesn't affect the position of the arrows.

+If the columns entry in `MenuDataHeader2` of a scrolling menu is 0, `Function2` isn't called either. It doesn't affect the position of the arrows.

-Call state for functions in MenuDataHeader2 of ScrollingMenu:

+Call state for functions in `MenuDataHeader2` of `ScrollingMenu`:

```

 All of them:

 [MenuSelection] = Current item. -1 is the CANCEL item.

@@ -60,10 +65,13 @@

 Function3: Called to display anything else, whenever the cursor is moved.

```

 There is no register of importance that should be preserved in any of these functions.

-The `; horizontal spacing` item in each MenuData2 is a misnomer. It changes how the Items struct looks.

+The `; horizontal spacing` item in each `MenuData2` is a misnomer. It changes how the `Items` struct looks.

 If it's 1:

```

 db entries not including cancel

 db entry1

@@ -71,7 +79,9 @@

 db -1 ; cancel

...

```

 If it's 2:

```

 db entries not including cancel

 db entry1, quantity1

@@ -79,14 +89,16 @@

 db -1 ; cancel

...

```

-In case it's 1, [MenuSelectionQuantity] will simply contain the next entry.

-## \_2DMenu

+In case it's 1, `[MenuSelectionQuantity]` will simply contain the next entry.

-This, like is implied by the name, is a 2-dimensional menu, where you can move your cursor in all 4 directions. It's only used for the battle menus as well as earl's academy.

+## `_2DMenu`

+This, like is implied by the name, is a 2-dimensional menu, where you can move your cursor in all 4 directions. It's only used for the battle menus as well as Earl's academy.

 Structure:

-```

+```asm

 .MenuDataHeader:

 	db MENU_BACKUP_TILES ; flags

 	db 12, 08 ; start coords

@@ -102,7 +114,8 @@

 	dba Function

```

-wMenuData2Flags:

+`wMenuData2Flags`:

```

 7: Leave one tile of spacing between the left textbox border and the text, enabling the cursor.

 6: Don't leave one tile of spacing between the top textbox border and the text

@@ -114,15 +127,19 @@

 0: Disable B button

```

-The bank for the Strings is generated when you call `_2DMenu`, and as such it doesn't really matter what bank you specify there (unless you callba `_2DMenu_` directly, of course).

+The bank for the `Strings` is generated when you call `_2DMenu`, and as such it doesn't really matter what bank you specify there (unless you callba `_2DMenu_` directly, of course).

 `; spacing` is not a misnomer here, it's used to define how much space there is between columns.

-`Function` is called after printing all the strings. `hl` will be pointed at the row below the last in the menu in TileMap. We don't know of its purpose, since it's never actually used anywhere. Only the bank number is always set to the same bank as the menu, but not used otherwise, since the address is 0.

-## DoNthMenu/SetUpMenu

+`Function` is called after printing all the strings. `hl` will be pointed at the row below the last in the menu in `TileMap`. We don't know of its purpose, since it's never actually used anywhere. Only the bank number is always set to the same bank as the menu, but not used otherwise, since the address is 0.

-These are like the regular VerticalMenu, except they allow for creating slightly more "dynamic" menus, where the options aren't predefined, much like the ScrollingMenu.

+## `DoNthMenu`/`SetUpMenu`

+These are like the regular `VerticalMenu`, except they allow for creating slightly more "dynamic" menus, where the options aren't predefined, much like the `ScrollingMenu`.

 Structure:

```

 .MenuDataHeader:

 	db MENU_BACKUP_TILES ; flags

@@ -138,7 +155,8 @@

 	dw StringPointers

```

-wMenuData2Flags:

+`wMenuData2Flags`:

```

 7: Unused

 6: Unused

@@ -151,8 +169,11 @@

```

 The `; items` entry should be left empty, as it's autogenerated with the `Items` array in `GetMenuIndexSet`.

 The bottom coord (`07` in the example) is autogenerated regardless of what you specify when building the MenuBox in `AutomaticGetMenuBottomCoord`, which also calculates the `bc` passed to MenuBox, which is useless because it's calculated again by MenuBox in `GetMenuBoxDims`.

-[wWhichIndexSet] decides which menu is used through `GetMenuIndexSet`. You can define multiple menus at the Items pointer as such:

+`[wWhichIndexSet]` decides which menu is used through `GetMenuIndexSet`. You can define multiple menus at the Items pointer as such:

```

 Items:

 db entries not including cancel

@@ -162,39 +183,42 @@

 db entry1, entry2, entry3, entry4

 db -1 ; cancel

```

-This is actively used in MainMenu.

-StringPointers isn't handled by DoNthMenu internally. It's handled by different `DisplayFunction`s.

-A custom one could choose to completely ignore it.

+This is actively used in `MainMenu`.

-StringPointers struct handled through `PlaceNthMenuStrings` as DisplayFunction and `MenuJumptable`:

-```

+`StringPointers` isn't handled by `DoNthMenu` internally. It's handled by different `DisplayFunction`s. A custom one could choose to completely ignore it.

+`StringPointers` struct handled through `PlaceNthMenuStrings` as `DisplayFunction` and `MenuJumptable`:

+```asm

 StringPointers:

-dw FunctionToCall, PointerToString ; index 1

-dw FunctionToCall, PointerToString ; index 2

+	dw FunctionToCall, PointerToString ; index 1

+	dw FunctionToCall, PointerToString ; index 2

...

```

-StringPointers struct handled through `PlaceMenuStrings`:

-```

+`StringPointers` struct handled through `PlaceMenuStrings`:

+```asm

 StringPointers:

-db "STRING1@"

-db "STRING2@"

+	db "STRING1@"

+	db "STRING2@"

...

```

-Call state for DisplayFunction:

+Call state for `DisplayFunction`:

```

 [MenuSelection] = Current item. -1 is the CANCEL item.

 de = Cursor position in TileMap

```

-## VerticalMenu

+## `VerticalMenu`

-This is the simplest menu. Like, the most boring. Nothing special. Just normal. ...nooooooormal...

+This is the simplest menu. Like, the most boring. Nothing special. Just normal. …nooooooormal…

 Structure:

-```

+```asm

 .MenuDataHeader:

 	db MENU_SPRITE_ANIMS | MENU_BACKUP_TILES ; flags

 	menu_coords 12, 12, SCREEN_WIDTH - 1, SCREEN_HEIGHT - 1

@@ -208,7 +232,8 @@

 	db "TAKE@"

```

-wMenuData2Flags:

+`wMenuData2Flags`:

```

 7: Leave one tile of spacing between the left textbox border and the text

 6: Don't leave one tile of spacing between the top textbox border and the text

@@ -221,7 +246,8 @@

```

 If bit 4 is set, a string at the end of the items array will be put at an offset from the start coord of the menu box. This string is defined like this:

-```

+```asm

 	db 2 ; # items

 	db "GIVE@"

 	db "TAKE@"

@@ -228,11 +254,13 @@

 	db 2 ; x offset

 	db "TEST@"

```

 This is used in the menu for selecting the character's name.

 ## Misc/Generic

-MenuDataHeader flags (wMenuFlags):

+`MenuDataHeader` flags (`wMenuFlags`):

```

 7: Save a backup of the tiles

 6: Save a backup of the tiles

@@ -244,7 +272,8 @@

 0: Call RestoreTileBackup when exiting the menu. This bit depends on whether bit 6 or 7 are set.

```

-w2DMenuFlags1:

+`w2DMenuFlags1`:

```

 7: Disable checking of wMenuJoypadFilter

 6: Enable sprite animations

@@ -256,7 +285,8 @@

 0: Set bit 7 in w2DMenuFlags2 and exit the loop if bit 4 is disabled and we tried to go too far right

```

-w2DMenuFlags2:

+`w2DMenuFlags2`:

```

 7: ?????

 6: ?????