Add some documentation on the window system

Unifies menus, dboxes, and portrait boxes into a single generic
graphical window system. The central object in this system is the
"window", which can be specialized into menus, text boxes, portraits,
and more.

On top of the previously known specializations, these additions identify
many more window types. The full list (see window.h comments for in-game
examples of the more esoteric types):

- scroll box: formatted text box that scrolls up/down
- dialogue box: scrolling message box, most commonly for character
  dialogue
- portrait box: box with a character portrait (Kaomado) in it
- text box: static text box
- dynamic text box (?): text box with dynamically populated content
- controls chart: for the "Controls" chart on the top screen
- alert box: temporary popup message box in dungeons
- advanced text box: marked-up (often colorful) and segmented text box
- input lock box: screen-lock display in the Sky Jukebox
- team info box: ground mode menu box showing team rank and money
- simple menu/parent menu/team selection menu/playback controls menu:
  simple menus that just have a list of options, possibly leading to
  submenus; the listed variants are all slightly different, but seem to
  share a common underlying data structure
- advanced menu: menu with complex layout and functionality
- collection menu: like an advanced menu, but specifically for
  collections of objects
- options menu: special menu for adjusting game options
- debug menu: probably for the debug mode menu
- jukebox track menu: Sky Jukebox track selection menu
- inventory menu: menu for managing items

The above list of window types should hopefully be exhaustive. They were
tracked down by looking at all callers to the NewWindowScreenCheck
function across all binaries, which also reveal the update function and
the size of the contents structure stored in struct window_params. By
looking at the update function pointer addresses in active windows in
the WINDOW_LIST, and twiddling some data to observe live changes, it's
possible to correlate different update functions with examples, which in
turn allows the general purpose of each window type to be inferred.

All windows share similar APIs for general manipulation (though each
type may have additional specialized methods, which remain mostly
undocumented):
1. A new window is create with the corresponding Create* function, which
   takes a window_params struct specifying generic parameters like the
   window position and size. A new window is added to the global
   WINDOW_LIST with a newly allocated window-type-dependent contents
   structure to hold all specialized data, and a corresponding update
   function to manage the data structure. The function returns a window
   ID (an index into WINDOW_LIST), which is used as a handle for all
   future manipulation.
2. The corresponding Update* function is (presumably periodically?)
   called to update the contents of the active window, if needed. This
   update function operates on the contents structure that was allocated
   when the window was created.
3. Presumably the code managing the window also does other stuff with
   the window, such as reading menu selections? The function
   GetWindowContents retrieves the specialized contents structure for an
   active window given its ID, and is used in many places.
4. There are presumably more functions for generic manipulation, like
   something to close a window, but these remain unknown for now.

As part of unification under the generic window system, some old
terminology has been changed. Among the most important:
- "dialog boxes" are now called "windows"
- "borders" are now called "window frames"
- "normal menus" are now called "simple menus"
- "dboxes" are now called "dialogue boxes"
- `struct dbox_layout` has been renamed to `struct window_params`

headers/data/arm9.h

@@ -12,7 +12,7 @@ extern enum item_id AURA_BOW_ID_LAST;
 extern uint32_t NUMBER_OF_ITEMS;
 extern uint32_t MAX_MONEY_CARRIED;
 extern uint32_t MAX_MONEY_STORED;
-extern struct dialog_box_list* DIALOG_BOX_LIST_PTR;
+extern struct window_list* WINDOW_LIST_PTR;
 extern struct script_var_value_table* SCRIPT_VARS_VALUES_PTR;
 extern uint32_t MONSTER_ID_LIMIT;
 extern uint32_t MAX_RECRUITABLE_TEAM_MEMBERS;

headers/data/ram.h

@@ -32,7 +32,7 @@ extern struct animation_control* CURSOR_16_ANIMATION_CONTROL;
 extern uint16_t ALERT_SPRITE_ID;
 extern struct animation_control* ALERT_ANIMATION_CONTROL;
 extern struct mem_arena* SOUND_MEMORY_ARENA_PTR;
-extern struct dialog_box_list DIALOG_BOX_LIST;
+extern struct window_list WINDOW_LIST;
 extern struct move LAST_NEW_MOVE;
 extern struct script_var_value_table SCRIPT_VARS_VALUES;
 extern uint8_t BAG_LEVEL;

headers/functions/arm9.h

@@ -456,7 +456,7 @@ void InitRender3dData(void);
 void GeomSwapBuffers(void);
 void InitRender3dElement64(struct render_3d_element_64* element64);
 void Render3d64Texture0x7(struct render_3d_element_64* element64);
-void Render3d64Border(struct render_3d_element_64* element64);
+void Render3d64WindowFrame(struct render_3d_element_64* element64);
 void EnqueueRender3d64Tiling(struct render_3d_element_64* element64);
 void Render3d64Tiling(struct render_3d_element_64* element64);
 void Render3d64Quadrilateral(struct render_3d_element_64* element64);
@@ -510,39 +510,88 @@ void CopyNStringFromMessageId(char* buf, int string_id, int buf_len);
 void LoadTblTalk(void);
 int GetTalkLine(int personality_idx, int group_id, int restrictions);
 bool IsAOrBPressed(void);
-int NewDialogBox(struct dialog_box_hdr* hdr, uint8_t param_2);
+int NewWindowScreenCheck(struct window_params* params, uint8_t param_2);
+int NewWindow(struct window_params* params, uint8_t param_2);
 void SetScreenWindowsColor(int palette_idx, bool upper_screen);
 void SetBothScreensWindowsColor(int palette_idx);
-undefined* GetDialogBoxField0xC(int dbox_id);
+void* GetWindowContents(int window_id);
 void LoadCursors(void);
-void InitDialogBoxTrailer(struct dialog_box_trailer* trailer);
+void InitWindowTrailer(struct window_trailer* trailer);
 void LoadAlert(void);
 void PrintClearMark(int mark_id, int x, int y, undefined param_4);
-int CreateNormalMenu(struct dbox_layout* layout, struct menu_flags menu_flags,
-                     struct menu_additional_info* menu_additional_info,
-                     struct normal_menu_option* menu_options, int option_id);
-void FreeNormalMenu(int menu_id);
-bool IsNormalMenuActive(int menu_id);
-int GetNormalMenuResult(int menu_id);
-int CreateAdvancedMenu(struct dbox_layout* layout, struct menu_flags menu_flags,
+int CreateParentMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                     undefined4 param_4);
+void UpdateParentMenu(struct window* window);
+int CreateSimpleMenuWrapper(struct window_params* params, struct menu_flags menu_flags,
+                            struct menu_additional_info* menu_additional_info,
+                            struct simple_menu_option* menu_options, int option_id);
+int CreateSimpleMenu(struct window_params* params, struct menu_flags menu_flags,
+                     struct menu_additional_info* menu_additional_info, char* param_3,
+                     int option_id);
+void FreeSimpleMenu(int window_id);
+bool IsSimpleMenuActive(int window_id);
+int GetSimpleMenuResult(int window_id);
+void UpdateSimpleMenu(struct window* window);
+int CreateAdvancedMenu(struct window_params* params, struct menu_flags menu_flags,
                        struct menu_additional_info* menu_additional_info,
                        advanced_menu_entry_fn_t* entry_fn, int n_options, int n_opt_per_page);
-void FreeAdvancedMenu(int menu_id);
-bool IsAdvancedMenuActive(int menu_id);
-int GetAdvancedMenuCurrentOption(int menu_id);
-int GetAdvancedMenuResult(int menu_id);
-int CreateDBox(struct dbox_layout* layout);
-void FreeDBox(int dbox_id);
-bool IsDBoxActive(int dbox_id);
-void ShowMessageInDBox(int dbox_id, struct preprocessor_flags flags, int string_id,
-                       struct preprocessor_args* args);
-void ShowStringInDBox(int dbox_id, struct preprocessor_flags flags, char* string,
-                      struct preprocessor_args* args);
-void ShowDBox(int dbox_id);
-int CreatePortraitBox(undefined param_1, undefined4 param_2, int param_3);
-void FreePortraitBox(int dbox_id);
-void ShowPortraitBox(int dbox_id, struct portrait_box* portrait);
-void HidePortraitBox(int dbox_id);
+void FreeAdvancedMenu(int window_id);
+bool IsAdvancedMenuActive(int window_id);
+int GetAdvancedMenuCurrentOption(int window_id);
+int GetAdvancedMenuResult(int window_id);
+void UpdateAdvancedMenu(struct window* window);
+int CreateCollectionMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                         undefined* param_4, undefined4 param_5, int param_6, int param_7);
+void UpdateCollectionMenu(struct window* window);
+int CreateOptionsMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                      undefined* param_4, int param_5, undefined4* param_6);
+void UpdateOptionsMenu(struct window* window);
+int CreateDebugMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                    uint16_t param_4, int param_5, undefined* param_6);
+void UpdateDebugMenu(struct window* window);
+int CreateScrollBox1(struct window_params* params, uint32_t param_2, undefined* param_3,
+                     uint16_t param_4, undefined* param_5, uint16_t param_6, undefined* param_7);
+int CreateScrollBox2(struct window_params* params, uint32_t param_2, undefined* param_3,
+                     int param_4, uint16_t* param_5, undefined* param_6, uint16_t* param_7,
+                     undefined* param_8);
+void UpdateScrollBox(struct window* window);
+int CreateDialogueBox(struct window_params* params);
+void FreeDialogueBox(int window_id);
+bool IsDialogueBoxActive(int window_id);
+void ShowMessageInDialogueBox(int window_id, struct preprocessor_flags flags, int string_id,
+                              struct preprocessor_args* args);
+void ShowStringInDialogueBox(int window_id, struct preprocessor_flags flags, char* string,
+                             struct preprocessor_args* args);
+void ShowDialogueBox(int window_id);
+void UpdateDialogueBox(struct window* window);
+int CreatePortraitBox(enum screen screen, uint32_t palette_idx, bool framed);
+void FreePortraitBox(int window_id);
+void ShowPortraitBox(int window_id, struct portrait_box* portrait);
+void HidePortraitBox(int window_id);
+void UpdatePortraitBox(struct window* window);
+int CreateTextBox1(struct window_params* params, undefined4 param_2);
+int CreateTextBox2(struct window_params* params, undefined4 param_2, undefined4 param_3);
+struct text_box* CreateTextBoxInternal(struct window_params* params);
+void UpdateTextBox(struct window* window);
+int CreateDynamicTextBox(struct window_params* params, uint32_t param_2, undefined* param_3,
+                         uint32_t id);
+void UpdateDynamicTextBox(struct window* window);
+int CreateControlsChart(struct window_params* params, undefined4 param_2, undefined* param_3,
+                        uint16_t param_4);
+void UpdateControlsChart(struct window* window);
+int CreateAlertBox(struct window_params* params);
+void UpdateAlertBox(struct window* window);
+int CreateAdvancedTextBox1(struct window_params* params, uint32_t param_2, undefined* param_3,
+                           undefined4 param_4, undefined4 param_5);
+int CreateAdvancedTextBox2(struct window_params* params, uint32_t param_2, undefined* param_3,
+                           undefined4 param_4, undefined4 param_5, undefined4 param_6);
+struct advanced_text_box* CreateAdvancedTextBoxInternal(struct window_params* params,
+                                                        uint32_t param_2, undefined* param_3,
+                                                        undefined4 param_4, int param_5);
+void UpdateAdvancedTextBox(struct window* window);
+int CreateTeamSelectionMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                            undefined* param_4, int param_5, int param_6);
+void UpdateTeamSelectionMenu(struct window* window);
 bool IsMenuOptionActive(undefined* param_1);
 void PlayMenuOptionSound(undefined* param_1, int index);
 int ShowKeyboard(int message_id, char* buffer1, int param_3, char* buffer2);

headers/functions/functions.h

@@ -4,6 +4,7 @@
 #include "arm9.h"
 #include "arm7.h"
 #include "overlay01.h"
+#include "overlay09.h"
 #include "overlay10.h"
 #include "overlay11.h"
 #include "overlay13.h"

headers/functions/overlay09.h

@@ -0,0 +1,14 @@
+#ifndef HEADERS_FUNCTIONS_OVERLAY09_H_
+#define HEADERS_FUNCTIONS_OVERLAY09_H_
+
+int CreateJukeboxTrackMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                           undefined* param_4, int param_5);
+void UpdateJukeboxTrackMenu(struct window* window);
+int CreatePlaybackControlsMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                               undefined4 param_4, undefined* param_5, undefined* param_6);
+void UpdatePlaybackControlsMenu(struct window* window);
+int CreateInputLockBox(struct window_params* params, uint32_t param_2, undefined* param_3,
+                       undefined4 param_4, uint16_t param_5);
+void UpdateInputLockBox(struct window* window);
+
+#endif

headers/functions/overlay10.h

@@ -1,6 +1,10 @@
 #ifndef HEADERS_FUNCTIONS_OVERLAY10_H_
 #define HEADERS_FUNCTIONS_OVERLAY10_H_
 
+int CreateInventoryMenu(struct window_params* params, uint32_t param_2, undefined* param_3,
+                        undefined* param_4, undefined4 param_5, int param_6, int param_7,
+                        uint8_t param_8);
+void UpdateInventoryMenu(struct window* window);
 int GetEffectAnimationField0x19(int anim_id);
 bool AnimationHasMoreFrames(int param_1);
 struct effect_animation* GetEffectAnimation(int anim_id);
@@ -10,6 +14,8 @@ int16_t GetTrapAnimation(enum trap_id trap_id);
 int16_t GetItemAnimation1(enum item_id item_id);
 int16_t GetItemAnimation2(enum item_id item_id);
 int GetMoveAnimationSpeed(enum move_id move_id);
+void ProcessTeamStatsLvHp(int idx);
+void ProcessTeamStatsNameGender(int idx);
 bool IsBackgroundTileset(int tileset_id);
 void InitTilesetBuffer(void* buffer, int tileset_id, uint32_t malloc_flags);
 int MainGame(int end_cond);

headers/functions/overlay11.h

@@ -48,6 +48,8 @@ void ChangeActorAnimation(undefined param_1, uint16_t setanimation_param);
 void InitPartnerFollowData(void);
 void GetDirectionLiveActor(struct live_actor* actor, struct direction_id_8* target);
 void SetDirectionLiveActor(struct live_actor* actor, struct direction_id_8 direction);
+int CreateTeamInfoBox(void);
+void UpdateTeamInfoBox(struct window* window);
 void GetExclusiveItemRequirements(undefined param_1, undefined param_2);
 bool GetDungeonMapPos(struct uvec2* out_pos, enum dungeon_id dungeon);
 void WorldMapSetMode(uint32_t world_map_mode);

headers/functions/overlay29.h

@@ -283,9 +283,9 @@ bool IsProtectedFromNegativeStatus(struct entity* user, struct entity* target, b
 void AddExpSpecial(struct entity* attacker, struct entity* defender, int base_exp);
 void EnemyEvolution(struct entity* entity);
 void LevelUpItemEffect(struct entity* user, struct entity* target, int levels, bool message,
-                       bool dialog);
+                       bool dialogue);
 bool TryDecreaseLevel(struct entity* user, struct entity* target, int n_levels);
-bool LevelUp(struct entity* user, struct entity* target, bool message, bool dialog);
+bool LevelUp(struct entity* user, struct entity* target, bool message, bool dialogue);
 void GetMonsterMoves(struct move_id_16* out_moves, enum monster_id monster_id, int level);
 void EvolveMonster(struct entity* user, struct entity* target, enum monster_id new_monster_id);
 uint8_t GetSleepAnimationId(struct entity* entity);