From 8e9fbbbba67cece1e46614a02a4729d1268940ad Mon Sep 17 00:00:00 2001 From: Allen Webster Date: Sat, 7 Dec 2019 18:53:01 -0800 Subject: [PATCH] Lots of documentation written --- 4ed_api_implementation.cpp | 107 +-- 4ed_api_parser.cpp | 5 +- 4ed_file.cpp | 16 - 4ed_file.h | 1 - 4ed_working_set.cpp | 12 +- custom/4coder_default_framework.cpp | 2 +- custom/4coder_helper.cpp | 13 +- custom/bin/build_one_time.bat | 4 +- custom/generated/command_metadata.h | 12 +- custom/generated/custom_api.cpp | 12 - custom/generated/custom_api.h | 54 +- custom/generated/custom_api_master_list.h | 14 +- docs/4ed_doc_content_types.cpp | 344 +++++++ docs/4ed_doc_content_types.h | 170 ++++ docs/4ed_doc_custom_api.cpp | 822 ++++++++++++++++ docs/4ed_doc_custom_api_buffer.cpp | 1033 +++++++++++++++++++++ docs/4ed_doc_custom_api_global.cpp | 275 ++++++ docs/4ed_doc_custom_api_view.cpp | 1011 ++++++++++++++++++++ project.4coder | 6 +- 19 files changed, 3714 insertions(+), 199 deletions(-) create mode 100644 docs/4ed_doc_content_types.cpp create mode 100644 docs/4ed_doc_content_types.h create mode 100644 docs/4ed_doc_custom_api.cpp create mode 100644 docs/4ed_doc_custom_api_buffer.cpp create mode 100644 docs/4ed_doc_custom_api_global.cpp create mode 100644 docs/4ed_doc_custom_api_view.cpp diff --git a/4ed_api_implementation.cpp b/4ed_api_implementation.cpp index 2e096c08..7cdad734 100644 --- a/4ed_api_implementation.cpp +++ b/4ed_api_implementation.cpp @@ -148,7 +148,7 @@ global_set_setting(Application_Links *app, Global_Setting_ID setting, i64 value) api(custom) function Rect_f32 global_get_screen_rectangle(Application_Links *app){ Models *models = (Models*)app->cmd_context; - return(Rf32(V2(0, 0), V2(layout_get_root_size(&models->layout)))); + return(Rf32(V2f32(0, 0), V2f32(layout_get_root_size(&models->layout)))); } api(custom) function Thread_Context* @@ -156,10 +156,14 @@ get_thread_context(Application_Links *app){ return(app->tctx); } -api(custom) function b32 -create_child_process(Application_Links *app, String_Const_u8 path, String_Const_u8 command, Child_Process_ID *child_process_id_out){ +api(custom) function Child_Process_ID +create_child_process(Application_Links *app, String_Const_u8 path, String_Const_u8 command){ Models *models = (Models*)app->cmd_context; - return(child_process_call(app->tctx, models, path, command, child_process_id_out)); + Child_Process_ID result = 0; + if (!child_process_call(app->tctx, models, path, command, &result)){ + result = 0; + } + return(result); } api(custom) function b32 @@ -628,17 +632,6 @@ buffer_exists(Application_Links *app, Buffer_ID buffer_id){ return(api_check_buffer(file)); } -api(custom) function b32 -buffer_ready(Application_Links *app, Buffer_ID buffer_id){ - Models *models = (Models*)app->cmd_context; - Editing_File *file = imp_get_file(models, buffer_id); - b32 result = false; - if (api_check_buffer(file)){ - result = file_is_ready(file); - } - return(result); -} - api(custom) function Access_Flag buffer_get_access_flags(Application_Links *app, Buffer_ID buffer_id){ Models *models = (Models*)app->cmd_context; @@ -1055,14 +1048,6 @@ buffer_get_file_attributes(Application_Links *app, Buffer_ID buffer_id) return(result); } -api(custom) function File_Attributes -get_file_attributes(Application_Links *app, String_Const_u8 file_name) -{ - Models *models = (Models*)app->cmd_context; - Scratch_Block scratch(app->tctx, Scratch_Share); - return(system_quick_file_attributes(scratch, file_name)); -} - function View* get_view_next__inner(Layout *layout, View *view){ if (view != 0){ @@ -1167,18 +1152,6 @@ get_active_view(Application_Links *app, Access_Flag access) return(result); } -api(custom) function Panel_ID -get_active_panel(Application_Links *app){ - Models *models = (Models*)app->cmd_context; - Panel *panel = layout_get_active_panel(&models->layout); - Assert(panel != 0); - Panel_ID result = 0; - if (api_check_panel(panel)){ - result = panel_get_id(&models->layout, panel); - } - return(result); -} - api(custom) function b32 view_exists(Application_Links *app, View_ID view_id){ Models *models = (Models*)app->cmd_context; @@ -1432,39 +1405,6 @@ panel_get_child(Application_Links *app, Panel_ID panel_id, Side which_child){ return(result); } -api(custom) function Panel_ID -panel_get_max(Application_Links *app, Panel_ID panel_id){ - Models *models = (Models*)app->cmd_context; - Layout *layout = &models->layout; - Panel *panel = imp_get_panel(models, panel_id); - Panel_ID result = 0; - if (api_check_panel(panel)){ - if (panel->kind == PanelKind_Intermediate){ - Panel *child = panel->br_panel; - result = panel_get_id(layout, child); - } - } - return(result); -} - -api(custom) function Rect_i32 -panel_get_margin(Application_Links *app, Panel_ID panel_id){ - Models *models = (Models*)app->cmd_context; - Layout *layout = &models->layout; - Panel *panel = imp_get_panel(models, panel_id); - Rect_i32 result = {}; - if (api_check_panel(panel)){ - if (panel->kind == PanelKind_Final){ - i32 margin = layout->margin; - result.x0 = margin; - result.x1 = margin; - result.y0 = margin; - result.y1 = margin; - } - } - return(result); -} - api(custom) function b32 view_close(Application_Links *app, View_ID view_id) { @@ -2059,14 +1999,15 @@ managed_scope_get_attachment(Application_Links *app, Managed_Scope scope, Manage return(result); } -api(custom) function void* +api(custom) function b32 managed_scope_attachment_erase(Application_Links *app, Managed_Scope scope, Managed_ID id){ Models *models = (Models*)app->cmd_context; Dynamic_Workspace *workspace = get_dynamic_workspace(models, scope); - void *result = 0; + b32 result = false; if (workspace != 0){ Dynamic_Variable_Block *var_block = &workspace->var_block; dynamic_variable_erase(var_block, id); + result = true; } return(result); } @@ -2419,18 +2360,15 @@ clear_all_query_bars(Application_Links *app, View_ID view_id){ } } -api(custom) function b32 +api(custom) function void print_message(Application_Links *app, String_Const_u8 message) { Models *models = (Models*)app->cmd_context; Editing_File *file = models->message_buffer; - b32 result = false; if (file != 0){ output_file_append(app->tctx, models, file, message); file_cursor_to_end(app->tctx, models, file); - result = true; } - return(result); } api(custom) function b32 @@ -2438,12 +2376,6 @@ log_string(Application_Links *app, String_Const_u8 str){ return(log_string(str)); } -api(custom) function i32 -thread_get_id(Application_Links *app){ - Models *models = (Models*)app->cmd_context; - return(system_thread_get_id()); -} - api(custom) function Face_ID get_largest_face_id(Application_Links *app) { @@ -2452,23 +2384,16 @@ get_largest_face_id(Application_Links *app) } api(custom) function b32 -set_global_face(Application_Links *app, Face_ID id, b32 apply_to_all_buffers) +set_global_face(Application_Links *app, Face_ID id) { Models *models = (Models*)app->cmd_context; - - b32 did_change = false; + b32 result = false; Face *face = font_set_face_from_id(&models->font_set, id); if (face != 0){ - if (apply_to_all_buffers){ - global_set_font_and_update_files(models, face); - } - else{ models->global_face_id = face->id; - } - did_change = true; + result = true; } - - return(did_change); + return(result); } api(custom) function History_Record_Index diff --git a/4ed_api_parser.cpp b/4ed_api_parser.cpp index f310d532..b5cb13fc 100644 --- a/4ed_api_parser.cpp +++ b/4ed_api_parser.cpp @@ -67,7 +67,7 @@ api_parse__match_identifier(Token_Iterator *it, String_Const_u8 source, char *le function String_Const_u8 api_parse__type_name_with_stars(Arena *arena, String_Const_u8 type, i32 star_counter){ if (star_counter > 0){ - i32 type_full_size = type.size + star_counter; + i32 type_full_size = (i32)(type.size) + star_counter; u8 *type_buffer = push_array(arena, u8, type_full_size + 1); block_copy(type_buffer, type.str, type.size); block_fill_u8(type_buffer + type.size, star_counter, (u8)'*'); @@ -121,8 +121,7 @@ api_parse_location(Arena *arena, String_Const_u8 source_name, String_Const_u8 so } function void -api_parse_source_add_to_list(Arena *arena, String_Const_u8 source_name, String_Const_u8 source, - API_Definition_List *list){ +api_parse_source_add_to_list(Arena *arena, String_Const_u8 source_name, String_Const_u8 source, API_Definition_List *list){ Token_List token_list = lex_full_input_cpp(arena, source); Token_Iterator token_it = token_iterator(token_iterator(0, &token_list)); diff --git a/4ed_file.cpp b/4ed_file.cpp index 2e900e79..ddb191ac 100644 --- a/4ed_file.cpp +++ b/4ed_file.cpp @@ -84,15 +84,6 @@ file_can_save(Editing_File *file){ return(result); } -internal b32 -file_is_ready(Editing_File *file){ - b32 result = false; - if (file != 0 && file->is_loading == 0){ - result = true; - } - return(result); -} - internal void file_set_unimportant(Editing_File *file, b32 val){ if (val){ @@ -101,13 +92,6 @@ file_set_unimportant(Editing_File *file, b32 val){ file->settings.unimportant = (b8)(val); } -internal void -file_set_to_loading(Editing_File *file){ - block_zero_struct(&file->state); - block_zero_struct(&file->settings); - file->is_loading = true; -} - internal void file_add_dirty_flag(Editing_File *file, Dirty_State state){ if (!file->settings.unimportant){ diff --git a/4ed_file.h b/4ed_file.h index 8b0d9c36..81fdc93c 100644 --- a/4ed_file.h +++ b/4ed_file.h @@ -89,7 +89,6 @@ struct Editing_File{ }; Node touch_node; Node external_mod_node; - b32 is_loading; Buffer_ID id; Editing_File_Settings settings; Editing_File_State state; diff --git a/4ed_working_set.cpp b/4ed_working_set.cpp index cb5adcfd..2a6271e0 100644 --- a/4ed_working_set.cpp +++ b/4ed_working_set.cpp @@ -313,8 +313,7 @@ buffer_name_has_conflict(Working_Set *working_set, String_Const_u8 base_name){ node != used_nodes; node = node->next){ Editing_File *file_ptr = CastFromMember(Editing_File, main_chain_node, node); - if (file_is_ready(file_ptr) && - string_match(base_name, string_from_file_name(&file_ptr->unique_name))){ + if (file_ptr && string_match(base_name, string_from_file_name(&file_ptr->unique_name))){ hit_conflict = true; break; } @@ -405,8 +404,7 @@ buffer_bind_name(Thread_Context *tctx, Models *models, Arena *scratch, Working_S node != used_nodes; node = node->next){ Editing_File *file_ptr = CastFromMember(Editing_File, main_chain_node, node); - if (file_is_ready(file_ptr) && - string_match(base_name, string_from_file_name(&file_ptr->base_name))){ + if (file_ptr != 0 && string_match(base_name, string_from_file_name(&file_ptr->base_name))){ Node_Ptr *new_node = push_array(scratch, Node_Ptr, 1); sll_queue_push(conflict_first, conflict_last, new_node); new_node->file_ptr = file_ptr; @@ -511,11 +509,7 @@ file_get_next(Working_Set *working_set, Editing_File *file){ internal Editing_File* imp_get_file(Models *models, Buffer_ID buffer_id){ Working_Set *working_set = &models->working_set; - Editing_File *file = working_set_get_file(working_set, buffer_id); - if (file != 0 && !file_is_ready(file)){ - file = 0; - } - return(file); + return(working_set_get_file(working_set, buffer_id)); } // BOTTOM diff --git a/custom/4coder_default_framework.cpp b/custom/4coder_default_framework.cpp index 979ba321..c4acc753 100644 --- a/custom/4coder_default_framework.cpp +++ b/custom/4coder_default_framework.cpp @@ -16,7 +16,7 @@ lock_jump_buffer(Application_Links *app, String_Const_u8 name){ locked_buffer = SCu8(locked_buffer_space, name.size); Scratch_Block scratch(app); String_Const_u8 escaped = string_escape(scratch, name); - LogEventF(log_string(app, M), scratch, 0, 0, thread_get_id(app), + LogEventF(log_string(app, M), scratch, 0, 0, system_thread_get_id(), "lock jump buffer [name=\"%.*s\"]", string_expand(escaped)); } } diff --git a/custom/4coder_helper.cpp b/custom/4coder_helper.cpp index 232187ac..af8ad70f 100644 --- a/custom/4coder_helper.cpp +++ b/custom/4coder_helper.cpp @@ -1915,19 +1915,22 @@ push_token_or_word_under_active_cursor(Application_Links *app, Arena *arena){ internal b32 file_exists(Application_Links *app, String_Const_u8 file_name){ - File_Attributes attributes = get_file_attributes(app, file_name); + Scratch_Block scratch(app); + File_Attributes attributes = system_quick_file_attributes(scratch, file_name); return(attributes.last_write_time > 0); } internal b32 file_exists_and_is_file(Application_Links *app, String_Const_u8 file_name){ - File_Attributes attributes = get_file_attributes(app, file_name); + Scratch_Block scratch(app); + File_Attributes attributes = system_quick_file_attributes(scratch, file_name); return(attributes.last_write_time > 0 && !HasFlag(attributes.flags, FileAttribute_IsDirectory)); } internal b32 file_exists_and_is_folder(Application_Links *app, String_Const_u8 file_name){ - File_Attributes attributes = get_file_attributes(app, file_name); + Scratch_Block scratch(app); + File_Attributes attributes = system_quick_file_attributes(scratch, file_name); return(attributes.last_write_time > 0 && HasFlag(attributes.flags, FileAttribute_IsDirectory)); } @@ -2423,8 +2426,8 @@ internal b32 exec_system_command(Application_Links *app, View_ID view, Buffer_Identifier buffer_id, String_Const_u8 path, String_Const_u8 command, Command_Line_Interface_Flag flags){ b32 result = false; - Child_Process_ID child_process_id = 0; - if (create_child_process(app, path, command, &child_process_id)){ + Child_Process_ID child_process_id = create_child_process(app, path, command); + if (child_process_id != 0){ result = true; Buffer_ID buffer_attach_id = buffer_identifier_to_id_create_out_buffer(app, buffer_id); if (buffer_attach_id != 0){ diff --git a/custom/bin/build_one_time.bat b/custom/bin/build_one_time.bat index 05c2262a..e34315bf 100644 --- a/custom/bin/build_one_time.bat +++ b/custom/bin/build_one_time.bat @@ -14,7 +14,7 @@ set custom_root=%cd% set custom_bin=%custom_root%\bin cd %location% -if NOT "%Platform%" == "X64" IF NOT "%Platform%" == "x64" (call "%code_home%\windows_scripts\setup_cl_x64.bat") +if NOT "%Platform%" == "X64" IF NOT "%Platform%" == "x64" (call "%custom_root%\windows_scripts\setup_cl_x64.bat") set target=%1 if "%target%" == "" (echo error: no input file & exit) @@ -35,7 +35,7 @@ set opts=%opts% /I%custom_root% set opts=%opts% %mode% pushd %dst% -call cl /I"%code_home%" %opts% %full_target% /Feone_time +call cl /I"%custom_root%" %opts% %full_target% /Feone_time popd diff --git a/custom/generated/command_metadata.h b/custom/generated/command_metadata.h index ee04ea5e..679feefb 100644 --- a/custom/generated/command_metadata.h +++ b/custom/generated/command_metadata.h @@ -252,12 +252,12 @@ static Command_Metadata fcoder_metacmd_table[226] = { { PROC_LINKS(profile_enable, 0), false, "profile_enable", 14, "Allow 4coder's self profiler to gather new profiling information.", 65, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 211 }, { PROC_LINKS(profile_disable, 0), false, "profile_disable", 15, "Prevent 4coder's self profiler from gathering new profiling information.", 72, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 218 }, { PROC_LINKS(profile_clear, 0), false, "profile_clear", 13, "Clear all profiling information from 4coder's self profiler.", 60, "w:\\4ed\\code\\custom\\4coder_profile.cpp", 37, 225 }, -{ PROC_LINKS(seek_beginning_of_textual_line, 0), false, "seek_beginning_of_textual_line", 30, "Seeks the cursor to the beginning of the line across all text.", 62, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2157 }, -{ PROC_LINKS(seek_end_of_textual_line, 0), false, "seek_end_of_textual_line", 24, "Seeks the cursor to the end of the line across all text.", 56, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2163 }, -{ PROC_LINKS(seek_beginning_of_line, 0), false, "seek_beginning_of_line", 22, "Seeks the cursor to the beginning of the visual line.", 53, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2169 }, -{ PROC_LINKS(seek_end_of_line, 0), false, "seek_end_of_line", 16, "Seeks the cursor to the end of the visual line.", 47, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2175 }, -{ PROC_LINKS(goto_beginning_of_file, 0), false, "goto_beginning_of_file", 22, "Sets the cursor to the beginning of the file.", 45, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2181 }, -{ PROC_LINKS(goto_end_of_file, 0), false, "goto_end_of_file", 16, "Sets the cursor to the end of the file.", 39, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2189 }, +{ PROC_LINKS(seek_beginning_of_textual_line, 0), false, "seek_beginning_of_textual_line", 30, "Seeks the cursor to the beginning of the line across all text.", 62, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2160 }, +{ PROC_LINKS(seek_end_of_textual_line, 0), false, "seek_end_of_textual_line", 24, "Seeks the cursor to the end of the line across all text.", 56, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2166 }, +{ PROC_LINKS(seek_beginning_of_line, 0), false, "seek_beginning_of_line", 22, "Seeks the cursor to the beginning of the visual line.", 53, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2172 }, +{ PROC_LINKS(seek_end_of_line, 0), false, "seek_end_of_line", 16, "Seeks the cursor to the end of the visual line.", 47, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2178 }, +{ PROC_LINKS(goto_beginning_of_file, 0), false, "goto_beginning_of_file", 22, "Sets the cursor to the beginning of the file.", 45, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2184 }, +{ PROC_LINKS(goto_end_of_file, 0), false, "goto_end_of_file", 16, "Sets the cursor to the end of the file.", 39, "w:\\4ed\\code\\custom\\4coder_helper.cpp", 36, 2192 }, { PROC_LINKS(toggle_virtual_whitespace, 0), false, "toggle_virtual_whitespace", 25, "Toggles the current buffer's virtual whitespace status.", 55, "w:\\4ed\\code\\custom\\4coder_code_index.cpp", 40, 957 }, { PROC_LINKS(change_active_panel, 0), false, "change_active_panel", 19, "Change the currently active panel, moving to the panel with the next highest view_id.", 85, "w:\\4ed\\code\\custom\\4coder_default_framework.cpp", 47, 284 }, { PROC_LINKS(change_active_panel_backwards, 0), false, "change_active_panel_backwards", 29, "Change the currently active panel, moving to the panel with the next lowest view_id.", 84, "w:\\4ed\\code\\custom\\4coder_default_framework.cpp", 47, 290 }, diff --git a/custom/generated/custom_api.cpp b/custom/generated/custom_api.cpp index 7bad261e..47e0105b 100644 --- a/custom/generated/custom_api.cpp +++ b/custom/generated/custom_api.cpp @@ -34,7 +34,6 @@ vtable->view_relative_box_of_pos = view_relative_box_of_pos; vtable->view_relative_character_from_pos = view_relative_character_from_pos; vtable->view_pos_from_relative_character = view_pos_from_relative_character; vtable->buffer_exists = buffer_exists; -vtable->buffer_ready = buffer_ready; vtable->buffer_get_access_flags = buffer_get_access_flags; vtable->buffer_get_size = buffer_get_size; vtable->buffer_get_line_count = buffer_get_line_count; @@ -55,12 +54,10 @@ vtable->buffer_save = buffer_save; vtable->buffer_kill = buffer_kill; vtable->buffer_reopen = buffer_reopen; vtable->buffer_get_file_attributes = buffer_get_file_attributes; -vtable->get_file_attributes = get_file_attributes; vtable->get_view_next = get_view_next; vtable->get_view_prev = get_view_prev; vtable->get_this_ctx_view = get_this_ctx_view; vtable->get_active_view = get_active_view; -vtable->get_active_panel = get_active_panel; vtable->view_exists = view_exists; vtable->view_get_buffer = view_get_buffer; vtable->view_get_cursor_pos = view_get_cursor_pos; @@ -78,8 +75,6 @@ vtable->panel_swap_children = panel_swap_children; vtable->panel_get_root = panel_get_root; vtable->panel_get_parent = panel_get_parent; vtable->panel_get_child = panel_get_child; -vtable->panel_get_max = panel_get_max; -vtable->panel_get_margin = panel_get_margin; vtable->view_close = view_close; vtable->view_get_buffer_region = view_get_buffer_region; vtable->view_get_buffer_scroll = view_get_buffer_scroll; @@ -137,7 +132,6 @@ vtable->end_query_bar = end_query_bar; vtable->clear_all_query_bars = clear_all_query_bars; vtable->print_message = print_message; vtable->log_string = log_string; -vtable->thread_get_id = thread_get_id; vtable->get_largest_face_id = get_largest_face_id; vtable->set_global_face = set_global_face; vtable->buffer_history_get_max_record_index = buffer_history_get_max_record_index; @@ -217,7 +211,6 @@ view_relative_box_of_pos = vtable->view_relative_box_of_pos; view_relative_character_from_pos = vtable->view_relative_character_from_pos; view_pos_from_relative_character = vtable->view_pos_from_relative_character; buffer_exists = vtable->buffer_exists; -buffer_ready = vtable->buffer_ready; buffer_get_access_flags = vtable->buffer_get_access_flags; buffer_get_size = vtable->buffer_get_size; buffer_get_line_count = vtable->buffer_get_line_count; @@ -238,12 +231,10 @@ buffer_save = vtable->buffer_save; buffer_kill = vtable->buffer_kill; buffer_reopen = vtable->buffer_reopen; buffer_get_file_attributes = vtable->buffer_get_file_attributes; -get_file_attributes = vtable->get_file_attributes; get_view_next = vtable->get_view_next; get_view_prev = vtable->get_view_prev; get_this_ctx_view = vtable->get_this_ctx_view; get_active_view = vtable->get_active_view; -get_active_panel = vtable->get_active_panel; view_exists = vtable->view_exists; view_get_buffer = vtable->view_get_buffer; view_get_cursor_pos = vtable->view_get_cursor_pos; @@ -261,8 +252,6 @@ panel_swap_children = vtable->panel_swap_children; panel_get_root = vtable->panel_get_root; panel_get_parent = vtable->panel_get_parent; panel_get_child = vtable->panel_get_child; -panel_get_max = vtable->panel_get_max; -panel_get_margin = vtable->panel_get_margin; view_close = vtable->view_close; view_get_buffer_region = vtable->view_get_buffer_region; view_get_buffer_scroll = vtable->view_get_buffer_scroll; @@ -320,7 +309,6 @@ end_query_bar = vtable->end_query_bar; clear_all_query_bars = vtable->clear_all_query_bars; print_message = vtable->print_message; log_string = vtable->log_string; -thread_get_id = vtable->thread_get_id; get_largest_face_id = vtable->get_largest_face_id; set_global_face = vtable->set_global_face; buffer_history_get_max_record_index = vtable->buffer_history_get_max_record_index; diff --git a/custom/generated/custom_api.h b/custom/generated/custom_api.h index 9feacae4..65fb2316 100644 --- a/custom/generated/custom_api.h +++ b/custom/generated/custom_api.h @@ -1,7 +1,7 @@ #define custom_global_set_setting_sig() b32 custom_global_set_setting(Application_Links* app, Global_Setting_ID setting, i64 value) #define custom_global_get_screen_rectangle_sig() Rect_f32 custom_global_get_screen_rectangle(Application_Links* app) #define custom_get_thread_context_sig() Thread_Context* custom_get_thread_context(Application_Links* app) -#define custom_create_child_process_sig() b32 custom_create_child_process(Application_Links* app, String_Const_u8 path, String_Const_u8 command, Child_Process_ID* child_process_id_out) +#define custom_create_child_process_sig() Child_Process_ID custom_create_child_process(Application_Links* app, String_Const_u8 path, String_Const_u8 command) #define custom_child_process_set_target_buffer_sig() b32 custom_child_process_set_target_buffer(Application_Links* app, Child_Process_ID child_process_id, Buffer_ID buffer_id, Child_Process_Set_Target_Flags flags) #define custom_buffer_get_attached_child_process_sig() Child_Process_ID custom_buffer_get_attached_child_process(Application_Links* app, Buffer_ID buffer_id) #define custom_child_process_get_attached_buffer_sig() Buffer_ID custom_child_process_get_attached_buffer(Application_Links* app, Child_Process_ID child_process_id) @@ -32,7 +32,6 @@ #define custom_view_relative_character_from_pos_sig() i64 custom_view_relative_character_from_pos(Application_Links* app, View_ID view_id, i64 base_line, i64 pos) #define custom_view_pos_from_relative_character_sig() i64 custom_view_pos_from_relative_character(Application_Links* app, View_ID view_id, i64 base_line, i64 character) #define custom_buffer_exists_sig() b32 custom_buffer_exists(Application_Links* app, Buffer_ID buffer_id) -#define custom_buffer_ready_sig() b32 custom_buffer_ready(Application_Links* app, Buffer_ID buffer_id) #define custom_buffer_get_access_flags_sig() Access_Flag custom_buffer_get_access_flags(Application_Links* app, Buffer_ID buffer_id) #define custom_buffer_get_size_sig() i64 custom_buffer_get_size(Application_Links* app, Buffer_ID buffer_id) #define custom_buffer_get_line_count_sig() i64 custom_buffer_get_line_count(Application_Links* app, Buffer_ID buffer_id) @@ -53,12 +52,10 @@ #define custom_buffer_kill_sig() Buffer_Kill_Result custom_buffer_kill(Application_Links* app, Buffer_ID buffer_id, Buffer_Kill_Flag flags) #define custom_buffer_reopen_sig() Buffer_Reopen_Result custom_buffer_reopen(Application_Links* app, Buffer_ID buffer_id, Buffer_Reopen_Flag flags) #define custom_buffer_get_file_attributes_sig() File_Attributes custom_buffer_get_file_attributes(Application_Links* app, Buffer_ID buffer_id) -#define custom_get_file_attributes_sig() File_Attributes custom_get_file_attributes(Application_Links* app, String_Const_u8 file_name) #define custom_get_view_next_sig() View_ID custom_get_view_next(Application_Links* app, View_ID view_id, Access_Flag access) #define custom_get_view_prev_sig() View_ID custom_get_view_prev(Application_Links* app, View_ID view_id, Access_Flag access) #define custom_get_this_ctx_view_sig() View_ID custom_get_this_ctx_view(Application_Links* app, Access_Flag access) #define custom_get_active_view_sig() View_ID custom_get_active_view(Application_Links* app, Access_Flag access) -#define custom_get_active_panel_sig() Panel_ID custom_get_active_panel(Application_Links* app) #define custom_view_exists_sig() b32 custom_view_exists(Application_Links* app, View_ID view_id) #define custom_view_get_buffer_sig() Buffer_ID custom_view_get_buffer(Application_Links* app, View_ID view_id, Access_Flag access) #define custom_view_get_cursor_pos_sig() i64 custom_view_get_cursor_pos(Application_Links* app, View_ID view_id) @@ -76,8 +73,6 @@ #define custom_panel_get_root_sig() Panel_ID custom_panel_get_root(Application_Links* app) #define custom_panel_get_parent_sig() Panel_ID custom_panel_get_parent(Application_Links* app, Panel_ID panel_id) #define custom_panel_get_child_sig() Panel_ID custom_panel_get_child(Application_Links* app, Panel_ID panel_id, Side which_child) -#define custom_panel_get_max_sig() Panel_ID custom_panel_get_max(Application_Links* app, Panel_ID panel_id) -#define custom_panel_get_margin_sig() Rect_i32 custom_panel_get_margin(Application_Links* app, Panel_ID panel_id) #define custom_view_close_sig() b32 custom_view_close(Application_Links* app, View_ID view_id) #define custom_view_get_buffer_region_sig() Rect_f32 custom_view_get_buffer_region(Application_Links* app, View_ID view_id) #define custom_view_get_buffer_scroll_sig() Buffer_Scroll custom_view_get_buffer_scroll(Application_Links* app, View_ID view_id) @@ -110,7 +105,7 @@ #define custom_managed_id_declare_sig() Managed_ID custom_managed_id_declare(Application_Links* app, String_Const_u8 group, String_Const_u8 name) #define custom_managed_id_get_sig() Managed_ID custom_managed_id_get(Application_Links* app, String_Const_u8 group, String_Const_u8 name) #define custom_managed_scope_get_attachment_sig() void* custom_managed_scope_get_attachment(Application_Links* app, Managed_Scope scope, Managed_ID id, umem size) -#define custom_managed_scope_attachment_erase_sig() void* custom_managed_scope_attachment_erase(Application_Links* app, Managed_Scope scope, Managed_ID id) +#define custom_managed_scope_attachment_erase_sig() b32 custom_managed_scope_attachment_erase(Application_Links* app, Managed_Scope scope, Managed_ID id) #define custom_alloc_managed_memory_in_scope_sig() Managed_Object custom_alloc_managed_memory_in_scope(Application_Links* app, Managed_Scope scope, i32 item_size, i32 count) #define custom_alloc_buffer_markers_on_buffer_sig() Managed_Object custom_alloc_buffer_markers_on_buffer(Application_Links* app, Buffer_ID buffer_id, i32 count, Managed_Scope* optional_extra_scope) #define custom_managed_object_get_item_size_sig() u32 custom_managed_object_get_item_size(Application_Links* app, Managed_Object object) @@ -133,11 +128,10 @@ #define custom_start_query_bar_sig() b32 custom_start_query_bar(Application_Links* app, Query_Bar* bar, u32 flags) #define custom_end_query_bar_sig() void custom_end_query_bar(Application_Links* app, Query_Bar* bar, u32 flags) #define custom_clear_all_query_bars_sig() void custom_clear_all_query_bars(Application_Links* app, View_ID view_id) -#define custom_print_message_sig() b32 custom_print_message(Application_Links* app, String_Const_u8 message) +#define custom_print_message_sig() void custom_print_message(Application_Links* app, String_Const_u8 message) #define custom_log_string_sig() b32 custom_log_string(Application_Links* app, String_Const_u8 str) -#define custom_thread_get_id_sig() i32 custom_thread_get_id(Application_Links* app) #define custom_get_largest_face_id_sig() Face_ID custom_get_largest_face_id(Application_Links* app) -#define custom_set_global_face_sig() b32 custom_set_global_face(Application_Links* app, Face_ID id, b32 apply_to_all_buffers) +#define custom_set_global_face_sig() b32 custom_set_global_face(Application_Links* app, Face_ID id) #define custom_buffer_history_get_max_record_index_sig() History_Record_Index custom_buffer_history_get_max_record_index(Application_Links* app, Buffer_ID buffer_id) #define custom_buffer_history_get_record_info_sig() Record_Info custom_buffer_history_get_record_info(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index) #define custom_buffer_history_get_group_sub_record_sig() Record_Info custom_buffer_history_get_group_sub_record(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index, i32 sub_index) @@ -180,7 +174,7 @@ typedef b32 custom_global_set_setting_type(Application_Links* app, Global_Setting_ID setting, i64 value); typedef Rect_f32 custom_global_get_screen_rectangle_type(Application_Links* app); typedef Thread_Context* custom_get_thread_context_type(Application_Links* app); -typedef b32 custom_create_child_process_type(Application_Links* app, String_Const_u8 path, String_Const_u8 command, Child_Process_ID* child_process_id_out); +typedef Child_Process_ID custom_create_child_process_type(Application_Links* app, String_Const_u8 path, String_Const_u8 command); typedef b32 custom_child_process_set_target_buffer_type(Application_Links* app, Child_Process_ID child_process_id, Buffer_ID buffer_id, Child_Process_Set_Target_Flags flags); typedef Child_Process_ID custom_buffer_get_attached_child_process_type(Application_Links* app, Buffer_ID buffer_id); typedef Buffer_ID custom_child_process_get_attached_buffer_type(Application_Links* app, Child_Process_ID child_process_id); @@ -211,7 +205,6 @@ typedef Rect_f32 custom_view_relative_box_of_pos_type(Application_Links* app, Vi typedef i64 custom_view_relative_character_from_pos_type(Application_Links* app, View_ID view_id, i64 base_line, i64 pos); typedef i64 custom_view_pos_from_relative_character_type(Application_Links* app, View_ID view_id, i64 base_line, i64 character); typedef b32 custom_buffer_exists_type(Application_Links* app, Buffer_ID buffer_id); -typedef b32 custom_buffer_ready_type(Application_Links* app, Buffer_ID buffer_id); typedef Access_Flag custom_buffer_get_access_flags_type(Application_Links* app, Buffer_ID buffer_id); typedef i64 custom_buffer_get_size_type(Application_Links* app, Buffer_ID buffer_id); typedef i64 custom_buffer_get_line_count_type(Application_Links* app, Buffer_ID buffer_id); @@ -232,12 +225,10 @@ typedef b32 custom_buffer_save_type(Application_Links* app, Buffer_ID buffer_id, typedef Buffer_Kill_Result custom_buffer_kill_type(Application_Links* app, Buffer_ID buffer_id, Buffer_Kill_Flag flags); typedef Buffer_Reopen_Result custom_buffer_reopen_type(Application_Links* app, Buffer_ID buffer_id, Buffer_Reopen_Flag flags); typedef File_Attributes custom_buffer_get_file_attributes_type(Application_Links* app, Buffer_ID buffer_id); -typedef File_Attributes custom_get_file_attributes_type(Application_Links* app, String_Const_u8 file_name); typedef View_ID custom_get_view_next_type(Application_Links* app, View_ID view_id, Access_Flag access); typedef View_ID custom_get_view_prev_type(Application_Links* app, View_ID view_id, Access_Flag access); typedef View_ID custom_get_this_ctx_view_type(Application_Links* app, Access_Flag access); typedef View_ID custom_get_active_view_type(Application_Links* app, Access_Flag access); -typedef Panel_ID custom_get_active_panel_type(Application_Links* app); typedef b32 custom_view_exists_type(Application_Links* app, View_ID view_id); typedef Buffer_ID custom_view_get_buffer_type(Application_Links* app, View_ID view_id, Access_Flag access); typedef i64 custom_view_get_cursor_pos_type(Application_Links* app, View_ID view_id); @@ -255,8 +246,6 @@ typedef b32 custom_panel_swap_children_type(Application_Links* app, Panel_ID pan typedef Panel_ID custom_panel_get_root_type(Application_Links* app); typedef Panel_ID custom_panel_get_parent_type(Application_Links* app, Panel_ID panel_id); typedef Panel_ID custom_panel_get_child_type(Application_Links* app, Panel_ID panel_id, Side which_child); -typedef Panel_ID custom_panel_get_max_type(Application_Links* app, Panel_ID panel_id); -typedef Rect_i32 custom_panel_get_margin_type(Application_Links* app, Panel_ID panel_id); typedef b32 custom_view_close_type(Application_Links* app, View_ID view_id); typedef Rect_f32 custom_view_get_buffer_region_type(Application_Links* app, View_ID view_id); typedef Buffer_Scroll custom_view_get_buffer_scroll_type(Application_Links* app, View_ID view_id); @@ -289,7 +278,7 @@ typedef u64 custom_managed_id_group_highest_id_type(Application_Links* app, Stri typedef Managed_ID custom_managed_id_declare_type(Application_Links* app, String_Const_u8 group, String_Const_u8 name); typedef Managed_ID custom_managed_id_get_type(Application_Links* app, String_Const_u8 group, String_Const_u8 name); typedef void* custom_managed_scope_get_attachment_type(Application_Links* app, Managed_Scope scope, Managed_ID id, umem size); -typedef void* custom_managed_scope_attachment_erase_type(Application_Links* app, Managed_Scope scope, Managed_ID id); +typedef b32 custom_managed_scope_attachment_erase_type(Application_Links* app, Managed_Scope scope, Managed_ID id); typedef Managed_Object custom_alloc_managed_memory_in_scope_type(Application_Links* app, Managed_Scope scope, i32 item_size, i32 count); typedef Managed_Object custom_alloc_buffer_markers_on_buffer_type(Application_Links* app, Buffer_ID buffer_id, i32 count, Managed_Scope* optional_extra_scope); typedef u32 custom_managed_object_get_item_size_type(Application_Links* app, Managed_Object object); @@ -312,11 +301,10 @@ typedef b32 custom_get_active_query_bars_type(Application_Links* app, View_ID vi typedef b32 custom_start_query_bar_type(Application_Links* app, Query_Bar* bar, u32 flags); typedef void custom_end_query_bar_type(Application_Links* app, Query_Bar* bar, u32 flags); typedef void custom_clear_all_query_bars_type(Application_Links* app, View_ID view_id); -typedef b32 custom_print_message_type(Application_Links* app, String_Const_u8 message); +typedef void custom_print_message_type(Application_Links* app, String_Const_u8 message); typedef b32 custom_log_string_type(Application_Links* app, String_Const_u8 str); -typedef i32 custom_thread_get_id_type(Application_Links* app); typedef Face_ID custom_get_largest_face_id_type(Application_Links* app); -typedef b32 custom_set_global_face_type(Application_Links* app, Face_ID id, b32 apply_to_all_buffers); +typedef b32 custom_set_global_face_type(Application_Links* app, Face_ID id); typedef History_Record_Index custom_buffer_history_get_max_record_index_type(Application_Links* app, Buffer_ID buffer_id); typedef Record_Info custom_buffer_history_get_record_info_type(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index); typedef Record_Info custom_buffer_history_get_group_sub_record_type(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index, i32 sub_index); @@ -391,7 +379,6 @@ custom_view_relative_box_of_pos_type *view_relative_box_of_pos; custom_view_relative_character_from_pos_type *view_relative_character_from_pos; custom_view_pos_from_relative_character_type *view_pos_from_relative_character; custom_buffer_exists_type *buffer_exists; -custom_buffer_ready_type *buffer_ready; custom_buffer_get_access_flags_type *buffer_get_access_flags; custom_buffer_get_size_type *buffer_get_size; custom_buffer_get_line_count_type *buffer_get_line_count; @@ -412,12 +399,10 @@ custom_buffer_save_type *buffer_save; custom_buffer_kill_type *buffer_kill; custom_buffer_reopen_type *buffer_reopen; custom_buffer_get_file_attributes_type *buffer_get_file_attributes; -custom_get_file_attributes_type *get_file_attributes; custom_get_view_next_type *get_view_next; custom_get_view_prev_type *get_view_prev; custom_get_this_ctx_view_type *get_this_ctx_view; custom_get_active_view_type *get_active_view; -custom_get_active_panel_type *get_active_panel; custom_view_exists_type *view_exists; custom_view_get_buffer_type *view_get_buffer; custom_view_get_cursor_pos_type *view_get_cursor_pos; @@ -435,8 +420,6 @@ custom_panel_swap_children_type *panel_swap_children; custom_panel_get_root_type *panel_get_root; custom_panel_get_parent_type *panel_get_parent; custom_panel_get_child_type *panel_get_child; -custom_panel_get_max_type *panel_get_max; -custom_panel_get_margin_type *panel_get_margin; custom_view_close_type *view_close; custom_view_get_buffer_region_type *view_get_buffer_region; custom_view_get_buffer_scroll_type *view_get_buffer_scroll; @@ -494,7 +477,6 @@ custom_end_query_bar_type *end_query_bar; custom_clear_all_query_bars_type *clear_all_query_bars; custom_print_message_type *print_message; custom_log_string_type *log_string; -custom_thread_get_id_type *thread_get_id; custom_get_largest_face_id_type *get_largest_face_id; custom_set_global_face_type *set_global_face; custom_buffer_history_get_max_record_index_type *buffer_history_get_max_record_index; @@ -541,7 +523,7 @@ custom_get_core_profile_list_type *get_core_profile_list; internal b32 global_set_setting(Application_Links* app, Global_Setting_ID setting, i64 value); internal Rect_f32 global_get_screen_rectangle(Application_Links* app); internal Thread_Context* get_thread_context(Application_Links* app); -internal b32 create_child_process(Application_Links* app, String_Const_u8 path, String_Const_u8 command, Child_Process_ID* child_process_id_out); +internal Child_Process_ID create_child_process(Application_Links* app, String_Const_u8 path, String_Const_u8 command); internal b32 child_process_set_target_buffer(Application_Links* app, Child_Process_ID child_process_id, Buffer_ID buffer_id, Child_Process_Set_Target_Flags flags); internal Child_Process_ID buffer_get_attached_child_process(Application_Links* app, Buffer_ID buffer_id); internal Buffer_ID child_process_get_attached_buffer(Application_Links* app, Child_Process_ID child_process_id); @@ -572,7 +554,6 @@ internal Rect_f32 view_relative_box_of_pos(Application_Links* app, View_ID view_ internal i64 view_relative_character_from_pos(Application_Links* app, View_ID view_id, i64 base_line, i64 pos); internal i64 view_pos_from_relative_character(Application_Links* app, View_ID view_id, i64 base_line, i64 character); internal b32 buffer_exists(Application_Links* app, Buffer_ID buffer_id); -internal b32 buffer_ready(Application_Links* app, Buffer_ID buffer_id); internal Access_Flag buffer_get_access_flags(Application_Links* app, Buffer_ID buffer_id); internal i64 buffer_get_size(Application_Links* app, Buffer_ID buffer_id); internal i64 buffer_get_line_count(Application_Links* app, Buffer_ID buffer_id); @@ -593,12 +574,10 @@ internal b32 buffer_save(Application_Links* app, Buffer_ID buffer_id, String_Con internal Buffer_Kill_Result buffer_kill(Application_Links* app, Buffer_ID buffer_id, Buffer_Kill_Flag flags); internal Buffer_Reopen_Result buffer_reopen(Application_Links* app, Buffer_ID buffer_id, Buffer_Reopen_Flag flags); internal File_Attributes buffer_get_file_attributes(Application_Links* app, Buffer_ID buffer_id); -internal File_Attributes get_file_attributes(Application_Links* app, String_Const_u8 file_name); internal View_ID get_view_next(Application_Links* app, View_ID view_id, Access_Flag access); internal View_ID get_view_prev(Application_Links* app, View_ID view_id, Access_Flag access); internal View_ID get_this_ctx_view(Application_Links* app, Access_Flag access); internal View_ID get_active_view(Application_Links* app, Access_Flag access); -internal Panel_ID get_active_panel(Application_Links* app); internal b32 view_exists(Application_Links* app, View_ID view_id); internal Buffer_ID view_get_buffer(Application_Links* app, View_ID view_id, Access_Flag access); internal i64 view_get_cursor_pos(Application_Links* app, View_ID view_id); @@ -616,8 +595,6 @@ internal b32 panel_swap_children(Application_Links* app, Panel_ID panel_id); internal Panel_ID panel_get_root(Application_Links* app); internal Panel_ID panel_get_parent(Application_Links* app, Panel_ID panel_id); internal Panel_ID panel_get_child(Application_Links* app, Panel_ID panel_id, Side which_child); -internal Panel_ID panel_get_max(Application_Links* app, Panel_ID panel_id); -internal Rect_i32 panel_get_margin(Application_Links* app, Panel_ID panel_id); internal b32 view_close(Application_Links* app, View_ID view_id); internal Rect_f32 view_get_buffer_region(Application_Links* app, View_ID view_id); internal Buffer_Scroll view_get_buffer_scroll(Application_Links* app, View_ID view_id); @@ -650,7 +627,7 @@ internal u64 managed_id_group_highest_id(Application_Links* app, String_Const_u8 internal Managed_ID managed_id_declare(Application_Links* app, String_Const_u8 group, String_Const_u8 name); internal Managed_ID managed_id_get(Application_Links* app, String_Const_u8 group, String_Const_u8 name); internal void* managed_scope_get_attachment(Application_Links* app, Managed_Scope scope, Managed_ID id, umem size); -internal void* managed_scope_attachment_erase(Application_Links* app, Managed_Scope scope, Managed_ID id); +internal b32 managed_scope_attachment_erase(Application_Links* app, Managed_Scope scope, Managed_ID id); internal Managed_Object alloc_managed_memory_in_scope(Application_Links* app, Managed_Scope scope, i32 item_size, i32 count); internal Managed_Object alloc_buffer_markers_on_buffer(Application_Links* app, Buffer_ID buffer_id, i32 count, Managed_Scope* optional_extra_scope); internal u32 managed_object_get_item_size(Application_Links* app, Managed_Object object); @@ -673,11 +650,10 @@ internal b32 get_active_query_bars(Application_Links* app, View_ID view_id, i32 internal b32 start_query_bar(Application_Links* app, Query_Bar* bar, u32 flags); internal void end_query_bar(Application_Links* app, Query_Bar* bar, u32 flags); internal void clear_all_query_bars(Application_Links* app, View_ID view_id); -internal b32 print_message(Application_Links* app, String_Const_u8 message); +internal void print_message(Application_Links* app, String_Const_u8 message); internal b32 log_string(Application_Links* app, String_Const_u8 str); -internal i32 thread_get_id(Application_Links* app); internal Face_ID get_largest_face_id(Application_Links* app); -internal b32 set_global_face(Application_Links* app, Face_ID id, b32 apply_to_all_buffers); +internal b32 set_global_face(Application_Links* app, Face_ID id); internal History_Record_Index buffer_history_get_max_record_index(Application_Links* app, Buffer_ID buffer_id); internal Record_Info buffer_history_get_record_info(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index); internal Record_Info buffer_history_get_group_sub_record(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index, i32 sub_index); @@ -753,7 +729,6 @@ global custom_view_relative_box_of_pos_type *view_relative_box_of_pos = 0; global custom_view_relative_character_from_pos_type *view_relative_character_from_pos = 0; global custom_view_pos_from_relative_character_type *view_pos_from_relative_character = 0; global custom_buffer_exists_type *buffer_exists = 0; -global custom_buffer_ready_type *buffer_ready = 0; global custom_buffer_get_access_flags_type *buffer_get_access_flags = 0; global custom_buffer_get_size_type *buffer_get_size = 0; global custom_buffer_get_line_count_type *buffer_get_line_count = 0; @@ -774,12 +749,10 @@ global custom_buffer_save_type *buffer_save = 0; global custom_buffer_kill_type *buffer_kill = 0; global custom_buffer_reopen_type *buffer_reopen = 0; global custom_buffer_get_file_attributes_type *buffer_get_file_attributes = 0; -global custom_get_file_attributes_type *get_file_attributes = 0; global custom_get_view_next_type *get_view_next = 0; global custom_get_view_prev_type *get_view_prev = 0; global custom_get_this_ctx_view_type *get_this_ctx_view = 0; global custom_get_active_view_type *get_active_view = 0; -global custom_get_active_panel_type *get_active_panel = 0; global custom_view_exists_type *view_exists = 0; global custom_view_get_buffer_type *view_get_buffer = 0; global custom_view_get_cursor_pos_type *view_get_cursor_pos = 0; @@ -797,8 +770,6 @@ global custom_panel_swap_children_type *panel_swap_children = 0; global custom_panel_get_root_type *panel_get_root = 0; global custom_panel_get_parent_type *panel_get_parent = 0; global custom_panel_get_child_type *panel_get_child = 0; -global custom_panel_get_max_type *panel_get_max = 0; -global custom_panel_get_margin_type *panel_get_margin = 0; global custom_view_close_type *view_close = 0; global custom_view_get_buffer_region_type *view_get_buffer_region = 0; global custom_view_get_buffer_scroll_type *view_get_buffer_scroll = 0; @@ -856,7 +827,6 @@ global custom_end_query_bar_type *end_query_bar = 0; global custom_clear_all_query_bars_type *clear_all_query_bars = 0; global custom_print_message_type *print_message = 0; global custom_log_string_type *log_string = 0; -global custom_thread_get_id_type *thread_get_id = 0; global custom_get_largest_face_id_type *get_largest_face_id = 0; global custom_set_global_face_type *set_global_face = 0; global custom_buffer_history_get_max_record_index_type *buffer_history_get_max_record_index = 0; diff --git a/custom/generated/custom_api_master_list.h b/custom/generated/custom_api_master_list.h index 9769051e..0536ebf9 100644 --- a/custom/generated/custom_api_master_list.h +++ b/custom/generated/custom_api_master_list.h @@ -1,7 +1,7 @@ api(custom) function b32 global_set_setting(Application_Links* app, Global_Setting_ID setting, i64 value); api(custom) function Rect_f32 global_get_screen_rectangle(Application_Links* app); api(custom) function Thread_Context* get_thread_context(Application_Links* app); -api(custom) function b32 create_child_process(Application_Links* app, String_Const_u8 path, String_Const_u8 command, Child_Process_ID* child_process_id_out); +api(custom) function Child_Process_ID create_child_process(Application_Links* app, String_Const_u8 path, String_Const_u8 command); api(custom) function b32 child_process_set_target_buffer(Application_Links* app, Child_Process_ID child_process_id, Buffer_ID buffer_id, Child_Process_Set_Target_Flags flags); api(custom) function Child_Process_ID buffer_get_attached_child_process(Application_Links* app, Buffer_ID buffer_id); api(custom) function Buffer_ID child_process_get_attached_buffer(Application_Links* app, Child_Process_ID child_process_id); @@ -32,7 +32,6 @@ api(custom) function Rect_f32 view_relative_box_of_pos(Application_Links* app, V api(custom) function i64 view_relative_character_from_pos(Application_Links* app, View_ID view_id, i64 base_line, i64 pos); api(custom) function i64 view_pos_from_relative_character(Application_Links* app, View_ID view_id, i64 base_line, i64 character); api(custom) function b32 buffer_exists(Application_Links* app, Buffer_ID buffer_id); -api(custom) function b32 buffer_ready(Application_Links* app, Buffer_ID buffer_id); api(custom) function Access_Flag buffer_get_access_flags(Application_Links* app, Buffer_ID buffer_id); api(custom) function i64 buffer_get_size(Application_Links* app, Buffer_ID buffer_id); api(custom) function i64 buffer_get_line_count(Application_Links* app, Buffer_ID buffer_id); @@ -53,12 +52,10 @@ api(custom) function b32 buffer_save(Application_Links* app, Buffer_ID buffer_id api(custom) function Buffer_Kill_Result buffer_kill(Application_Links* app, Buffer_ID buffer_id, Buffer_Kill_Flag flags); api(custom) function Buffer_Reopen_Result buffer_reopen(Application_Links* app, Buffer_ID buffer_id, Buffer_Reopen_Flag flags); api(custom) function File_Attributes buffer_get_file_attributes(Application_Links* app, Buffer_ID buffer_id); -api(custom) function File_Attributes get_file_attributes(Application_Links* app, String_Const_u8 file_name); api(custom) function View_ID get_view_next(Application_Links* app, View_ID view_id, Access_Flag access); api(custom) function View_ID get_view_prev(Application_Links* app, View_ID view_id, Access_Flag access); api(custom) function View_ID get_this_ctx_view(Application_Links* app, Access_Flag access); api(custom) function View_ID get_active_view(Application_Links* app, Access_Flag access); -api(custom) function Panel_ID get_active_panel(Application_Links* app); api(custom) function b32 view_exists(Application_Links* app, View_ID view_id); api(custom) function Buffer_ID view_get_buffer(Application_Links* app, View_ID view_id, Access_Flag access); api(custom) function i64 view_get_cursor_pos(Application_Links* app, View_ID view_id); @@ -76,8 +73,6 @@ api(custom) function b32 panel_swap_children(Application_Links* app, Panel_ID pa api(custom) function Panel_ID panel_get_root(Application_Links* app); api(custom) function Panel_ID panel_get_parent(Application_Links* app, Panel_ID panel_id); api(custom) function Panel_ID panel_get_child(Application_Links* app, Panel_ID panel_id, Side which_child); -api(custom) function Panel_ID panel_get_max(Application_Links* app, Panel_ID panel_id); -api(custom) function Rect_i32 panel_get_margin(Application_Links* app, Panel_ID panel_id); api(custom) function b32 view_close(Application_Links* app, View_ID view_id); api(custom) function Rect_f32 view_get_buffer_region(Application_Links* app, View_ID view_id); api(custom) function Buffer_Scroll view_get_buffer_scroll(Application_Links* app, View_ID view_id); @@ -110,7 +105,7 @@ api(custom) function u64 managed_id_group_highest_id(Application_Links* app, Str api(custom) function Managed_ID managed_id_declare(Application_Links* app, String_Const_u8 group, String_Const_u8 name); api(custom) function Managed_ID managed_id_get(Application_Links* app, String_Const_u8 group, String_Const_u8 name); api(custom) function void* managed_scope_get_attachment(Application_Links* app, Managed_Scope scope, Managed_ID id, umem size); -api(custom) function void* managed_scope_attachment_erase(Application_Links* app, Managed_Scope scope, Managed_ID id); +api(custom) function b32 managed_scope_attachment_erase(Application_Links* app, Managed_Scope scope, Managed_ID id); api(custom) function Managed_Object alloc_managed_memory_in_scope(Application_Links* app, Managed_Scope scope, i32 item_size, i32 count); api(custom) function Managed_Object alloc_buffer_markers_on_buffer(Application_Links* app, Buffer_ID buffer_id, i32 count, Managed_Scope* optional_extra_scope); api(custom) function u32 managed_object_get_item_size(Application_Links* app, Managed_Object object); @@ -133,11 +128,10 @@ api(custom) function b32 get_active_query_bars(Application_Links* app, View_ID v api(custom) function b32 start_query_bar(Application_Links* app, Query_Bar* bar, u32 flags); api(custom) function void end_query_bar(Application_Links* app, Query_Bar* bar, u32 flags); api(custom) function void clear_all_query_bars(Application_Links* app, View_ID view_id); -api(custom) function b32 print_message(Application_Links* app, String_Const_u8 message); +api(custom) function void print_message(Application_Links* app, String_Const_u8 message); api(custom) function b32 log_string(Application_Links* app, String_Const_u8 str); -api(custom) function i32 thread_get_id(Application_Links* app); api(custom) function Face_ID get_largest_face_id(Application_Links* app); -api(custom) function b32 set_global_face(Application_Links* app, Face_ID id, b32 apply_to_all_buffers); +api(custom) function b32 set_global_face(Application_Links* app, Face_ID id); api(custom) function History_Record_Index buffer_history_get_max_record_index(Application_Links* app, Buffer_ID buffer_id); api(custom) function Record_Info buffer_history_get_record_info(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index); api(custom) function Record_Info buffer_history_get_group_sub_record(Application_Links* app, Buffer_ID buffer_id, History_Record_Index index, i32 sub_index); diff --git a/docs/4ed_doc_content_types.cpp b/docs/4ed_doc_content_types.cpp new file mode 100644 index 00000000..e96b26ad --- /dev/null +++ b/docs/4ed_doc_content_types.cpp @@ -0,0 +1,344 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 04.12.2019 + * + * Definition of information contained in 4coder documentation. + * + */ + +// TOP + +#include + +function Doc_Date +doc_date_now(void){ + time_t t = time(0); + tm *time = localtime(&t); + Doc_Date date = {}; + date.day = time->tm_mday; + date.month = time->tm_mon + 1; + date.year = 1990 + time->tm_year; + return(date); + } + +//////////////////////////////// + +function Doc_Content* +doc_content_push(Arena *arena, Doc_Content_List *list, String_Const_u8 text, Doc_Content_Emphasis emphasis){ + Doc_Content *content = push_array_zero(arena, Doc_Content, 1); + sll_queue_push(list->first, list->last, content); + list->total_size += text.size; + list->node_count += 1; + content->text = text; + content->emphasis = emphasis; + return(content); +} + +function Doc_Content* +doc_content_push(Arena *arena, Doc_Content_List *list, String_Const_u8 text){ + return(doc_content_push(arena, list, text, DocContentEmphasis_Normal)); +} + +function void +doc_code_list_push(Arena *arena, Doc_Code_Sample_List *list, String_Const_u8 contents, Doc_Code_Language language){ + Doc_Code_Sample *sample = push_array_zero(arena, Doc_Code_Sample, 1); + sll_queue_push(list->first, list->last, sample); + list->count += 1; + sample->contents = contents; + sample->language = language; +} + +//////////////////////////////// + +function Doc_Cluster* +new_doc_cluster(Arena *arena, char *title, char *name, Doc_Date *date){ + Doc_Cluster *result = push_array_zero(arena, Doc_Cluster, 1); + result->title = SCu8(title); + result->name = SCu8(name); + result->gen_date = *date; + return(result); +} + +function Doc_Cluster* +new_doc_cluster(Arena *arena, char *title, char *name){ + Doc_Date date = doc_date_now(); + return(new_doc_cluster(arena, title, name, &date)); +} + +function Doc_Page* +new_doc_page(Arena *arena, Doc_Cluster *cluster, char *title, char *name){ + Doc_Page *result = push_array_zero(arena, Doc_Page, 1); + + result->owner = cluster; + sll_queue_push(cluster->first_page, cluster->last_page, result); + cluster->page_count += 1; + + result->title = SCu8(title); + result->name = SCu8(name); + + return(result); +} + +function Doc_Page* +new_doc_page_normal_title(Arena *arena, Doc_Cluster *cluster, char *title, char *name){ + String_Const_u8 full_title = push_u8_stringf(arena, "%s - %.*s", title, string_expand(cluster->title)); + return(new_doc_page(arena, cluster, (char*)full_title.str, name)); +} + +function Doc_Page* +new_doc_page_function(Arena *arena, Doc_Cluster *cluster, char *name){ + String_Const_u8 full_name = push_u8_stringf(arena, "%s function", name); + return(new_doc_page_normal_title(arena, cluster, name, (char*)full_name.str)); +} + +function Doc_Page* +new_doc_page_function(Arena *arena, Doc_Cluster *cluster, String_Const_u8 name){ + name = push_string_copy(arena, name); + char *c_name = (char*)name.str; + return(new_doc_page_function(arena, cluster, c_name)); +} + + function Doc_Block* +new_doc_block(Arena *arena, Doc_Page *page, char *name){ + Doc_Block *result = push_array_zero(arena, Doc_Block, 1); + result->owner = page; + sll_queue_push(page->first_block, page->last_block, result); + page->block_count += 1; + result->name = SCu8(name); + return(result); +} + +function void +new_doc_block_jump(Arena *arena, Doc_Page *page, Doc_Block *block){ + Doc_Block_Ptr *node = push_array_zero(arena, Doc_Block_Ptr, 1); + sll_queue_push(page->quick_jumps.first, page->quick_jumps.last, node); + page->quick_jumps.count += 1; + node->block = block; +} + +function Doc_Paragraph* +new_doc_par(Arena *arena, Doc_Block *block){ + Doc_Paragraph *result = push_array_zero(arena, Doc_Paragraph, 1); + sll_queue_push(block->first_par, block->last_par, result); + block->par_count += 1; + return(result); +} + +function void +new_doc_par_single_code(Arena *arena, Doc_Block *block, String_Const_u8 contents, Doc_Code_Language language){ + Doc_Paragraph *paragraph = new_doc_par(arena, block); + paragraph->kind = DocParagraphKind_Code; + doc_code_list_push(arena, ¶graph->code, contents, language); +} + +//////////////////////////////// + +function void +doc_log(Arena *arena, Doc_Cluster *cluster, String_Const_u8 string){ + Doc_Log *log = push_array_zero(arena, Doc_Log, 1); + sll_queue_push(cluster->first_log, cluster->last_log, log); + log->content = string; +} + +function void +doc_log(Arena *arena, Doc_Cluster *cluster, char *str){ + doc_log(arena, cluster, SCu8(str)); +} + +function void +doc_logfv(Arena *arena, Doc_Cluster *cluster, char *format, va_list args){ + String_Const_u8 str = push_u8_stringfv(arena, format, args); + doc_log(arena, cluster, str); +} + +function void +doc_logf(Arena *arena, Doc_Cluster *cluster, char *format, ...){ + va_list args; + va_start(args, format); + doc_logfv(arena, cluster, format, args); + va_end(args); +} + +#define doc_warning(a,c) doc_log(a),(c), "warning: ") +#define doc_error(a,c) doc_log(a),(c), "error: ") +#define doc_note(a,c) doc_log(a),(c), "note: ") + +#define doc_warningf(a,c,f,...) doc_logf((a),(c), "warning: " f, __VA_ARGS__) +#define doc_errorf(a,c,f,...) doc_logf((a),(c), "error: " f, __VA_ARGS__) +#define doc_notef(a,c,f,...) doc_logf((a),(c), "note: " f, __VA_ARGS__) + +//////////////////////////////// + +function void +doc_text(Arena *arena, Doc_Block *block, char *str){ + Doc_Paragraph *par = block->last_par; + if (par != 0){ + if (par->kind != DocParagraphKind_Text){ + par = 0; + } + } + + if (par == 0){ + par = new_doc_par(arena, block); + par->kind = DocParagraphKind_Text; + } + + doc_content_push(arena, &par->text, SCu8(str)); +} + +function void +doc_paragraph(Arena *arena, Doc_Block *block){ + Doc_Paragraph *par = new_doc_par(arena, block); + par->kind = DocParagraphKind_Text; +} + +//////////////////////////////// + +function Doc_Function +make_doc_function(Arena *arena, Doc_Cluster *cluster, API_Call *call){ + Doc_Function result = {}; + result.call = call; + result.page = new_doc_page_function(arena, cluster, call->name); + result.brief = new_doc_block(arena, result.page, "brief"); + result.sig = new_doc_block(arena, result.page, "Signature"); + new_doc_block_jump(arena, result.page, result.sig); + + String_Const_u8 opener = push_u8_stringf(arena, "%.*s %.*s(", + string_expand(call->return_type), + string_expand(call->name)); + + u8 *buffer = push_array(arena, u8, opener.size); + for (umem i = 0; i < opener.size; i += 1){ + buffer[i] = ' '; + } + String_Const_u8 indent = SCu8(buffer, opener.size); + + List_String_Const_u8 list = {}; + string_list_push(arena, &list, opener); + for (API_Param *node = call->params.first; + node != 0; + node = node->next){ + string_list_pushf(arena, &list, "%.*s %.*s", + string_expand(node->type_name), + string_expand(node->name)); + if (node->next != 0){ + string_list_pushf(arena, &list, ",\n%.*s", + string_expand(indent)); + } + } + string_list_push(arena, &list, string_u8_litexpr(");")); + + String_Const_u8 contents = string_list_flatten(arena, list); + new_doc_par_single_code(arena, result.sig, contents, DocCodeLanguage_Cpp); + + return(result); +} + +function b32 +begin_doc_call(Arena *arena, Doc_Cluster *cluster, API_Definition *api_def, char *name, Doc_Function *func){ + API_Call *call = api_get_call(api_def, SCu8(name)); + b32 result = (call != 0); + if (result){ + *func = make_doc_function(arena, cluster, call); + } + else{ + doc_warningf(arena, cluster, "dead call documentation %s", name); + } + return(result); +} + +function Doc_Block* +doc_function_brief(Arena *arena, Doc_Function *func, char *text){ + if (text != 0){ + doc_text(arena, func->brief, text); + } + return(func->brief); +} + +function Doc_Block* +doc_function_begin_params(Arena *arena, Doc_Function *func){ + func->params = new_doc_block(arena, func->page, "Parameters"); + new_doc_block_jump(arena, func->page, func->params); + return(func->params); +} + +function void +doc_function_param(Arena *arena, Doc_Function *func, char *name){ + String_Const_u8 name_str = SCu8(name); + + API_Call *call = func->call; + API_Param *param = 0; + for (API_Param *node = call->params.first; + node != 0; + node = node->next){ + if (string_match(name_str, node->name)){ + param = node; + break; + } + } + + if (param == 0){ + doc_errorf(arena, func->page->owner, "documentation for non-existant parameter %s in call %.*s", name, string_expand(call->name)); + return; + } + + API_Param *iter = func->param_iter; + if (iter != 0){ + for (iter = iter->next; + iter != 0 && iter != param; + iter = iter->next); + if (iter == 0){ + doc_warningf(arena, func->page->owner, "parameters out of order in documentation for call %.*s", string_expand(call->name)); + } + } + func->param_iter = param; + + // parameter header + Doc_Paragraph *par = new_doc_par(arena, func->params); + par->kind = DocParagraphKind_Text; + doc_content_push(arena, &par->text, name_str, DocContentEmphasis_SmallHeader); + + // empty paragraph to start filling after + par = new_doc_par(arena, func->params); + par->kind = DocParagraphKind_Text; +} + +function Doc_Block* +doc_function_return(Arena *arena, Doc_Function *func){ + func->ret = new_doc_block(arena, func->page, "Return"); + new_doc_block_jump(arena, func->page, func->ret); + return(func->ret); +} + +function Doc_Block* +doc_function_details(Arena *arena, Doc_Function *func){ + func->det = new_doc_block(arena, func->page, "Details"); + new_doc_block_jump(arena, func->page, func->det); + return(func->det); +} + +function Doc_Block* +doc_function_examples(Arena *arena, Doc_Function *func){ + func->examples = new_doc_block(arena, func->page, "Examples"); + new_doc_block_jump(arena, func->page, func->examples); + return(func->examples); +} + +function Doc_Block* +doc_function_begin_related(Arena *arena, Doc_Function *func){ + func->rel = new_doc_block(arena, func->page, "Related"); + new_doc_block_jump(arena, func->page, func->rel); + return(func->rel); +} + +function void +doc_function_add_related(Arena *arena, Doc_Block *rel, char *name){ + Doc_Paragraph *par = new_doc_par(arena, rel); + par->kind = DocParagraphKind_Text; + Doc_Content *content = doc_content_push(arena, &par->text, SCu8(name)); + content->page_link = SCu8(name); +} + +// BOTTOM + diff --git a/docs/4ed_doc_content_types.h b/docs/4ed_doc_content_types.h new file mode 100644 index 00000000..17e0a809 --- /dev/null +++ b/docs/4ed_doc_content_types.h @@ -0,0 +1,170 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 04.12.2019 + * + * Definition of information contained in 4coder documentation. + * + */ + +// TOP + +#if !defined(FRED_DOC_CONTENT_TYPES_H) +#define FRED_DOC_CONTENT_TYPES_H + +typedef i32 Doc_Month; +enum{ + None, + January, + February, + March, + April, + May, + June, + July, + August, + September, + October, + November, + December, +}; + +struct Doc_Date{ + i32 day; + Doc_Month month; + i32 year; +}; + +typedef i32 Doc_Content_Emphasis; +enum{ + DocContentEmphasis_Normal, + DocContentEmphasis_SmallHeader, + DocContentEmphasis_Heavy, + DocContentEmphasis_Stylish, + DocContentEmphasis_Code, +}; +struct Doc_Content{ + Doc_Content *next; + String_Const_u8 text; + String_Const_u8 page_link; + String_Const_u8 block_link; + Doc_Content_Emphasis emphasis; +}; +struct Doc_Content_List{ + Doc_Content *first; + Doc_Content *last; + umem total_size; + i32 node_count; +}; + +typedef i32 Doc_Code_Language; +enum{ + DocCodeLanguage_None, + DocCodeLanguage_Cpp, + DocCodeLanguage_Bat, +}; +struct Doc_Code_Sample{ + Doc_Code_Sample *next; + String_Const_u8 contents; + Doc_Code_Language language; +}; +struct Doc_Code_Sample_List{ + Doc_Code_Sample *first; + Doc_Code_Sample *last; + i32 count; +}; + +typedef i32 Doc_Paragraph_Kind; +enum{ + DocParagraphKind_Text, + DocParagraphKind_Code, + DocParagraphKind_Table, +}; +struct Doc_Paragraph{ + Doc_Paragraph *next; + Doc_Paragraph_Kind kind; + union{ + Doc_Content_List text; + Doc_Code_Sample_List code; + struct{ + Vec2_i32 dim; + Doc_Content_List *vals; + } table; + }; +}; + +struct Doc_Block{ + Doc_Block *next; + + struct Doc_Page *owner; + + String_Const_u8 name; + + Doc_Paragraph *first_par; + Doc_Paragraph *last_par; + i32 par_count; +}; + +struct Doc_Block_Ptr{ + Doc_Block_Ptr *next; + Doc_Block *block; +}; + +struct Doc_Block_List{ + Doc_Block_Ptr *first; + Doc_Block_Ptr *last; + i32 count; +}; + +struct Doc_Page{ + Doc_Page *next; + + struct Doc_Cluster *owner; + + String_Const_u8 title; + String_Const_u8 name; + + Doc_Block *first_block; + Doc_Block *last_block; + i32 block_count; + + Doc_Block_List quick_jumps; +}; + +struct Doc_Log{ + Doc_Log *next; + String_Const_u8 content; +}; + +struct Doc_Cluster{ + String_Const_u8 title; + String_Const_u8 name; + Doc_Date gen_date; + + Doc_Page *first_page; + Doc_Page *last_page; + i32 page_count; + + Doc_Log *first_log; + Doc_Log *last_log; +}; + +//////////////////////////////// + +struct Doc_Function{ + API_Call *call; + API_Param *param_iter; + Doc_Page *page; + Doc_Block *brief; + Doc_Block *sig; + Doc_Block *params; + Doc_Block *ret; + Doc_Block *det; + Doc_Block *examples; + Doc_Block *rel; +}; + +#endif + +// BOTTOM + diff --git a/docs/4ed_doc_custom_api.cpp b/docs/4ed_doc_custom_api.cpp new file mode 100644 index 00000000..c6cb7441 --- /dev/null +++ b/docs/4ed_doc_custom_api.cpp @@ -0,0 +1,822 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 04.12.2019 + * + * Documentation of the custom layer's primary api. + * + */ + +// TOP + +#include "4coder_base_types.h" +#include "4coder_token.h" +#include "generated/lexer_cpp.h" +#include "../4ed_api_definition.h" +#include "4ed_doc_content_types.h" + +#include "4coder_base_types.cpp" +#include "4coder_stringf.cpp" +#include "4coder_malloc_allocator.cpp" +#include "4coder_token.cpp" +#include "generated/lexer_cpp.cpp" +#include "../4ed_api_definition.cpp" +#include "../4ed_api_parser.cpp" +#include "4ed_doc_content_types.cpp" +#include "4coder_file.cpp" + +function void +doc_custom_app_ptr(Arena *arena, Doc_Function *func){ + doc_function_param(arena, func, "app"); + doc_text(arena, func->params, "the standard custom layer context pointer"); +} + +//////////////////////////////// + +#include "4ed_doc_custom_api_global.cpp" +#include "4ed_doc_custom_api_buffer.cpp" +#include "4ed_doc_custom_api_view.cpp" + +//////////////////////////////// + +function Doc_Cluster* +doc_custom_api(Arena *arena, API_Definition *api_def){ + Doc_Cluster *cluster = new_doc_cluster(arena, "Custom Layer Boundary API", "custom api"); + + Doc_Function func = {}; + + doc_custom_api__global(arena, api_def, cluster); + doc_custom_api__buffer(arena, api_def, cluster); + doc_custom_api__view(arena, api_def, cluster); + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "create_user_managed_scope", &func)){ + doc_function_brief(arena, &func, "Create a managed scope that is not tied to anything in the core and that the user can destroy"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the new managed scope's id"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "destroy_user_managed_scope", &func)){ + doc_function_brief(arena, &func, "Destroy a managed scope that was previously created by the user"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the managed scope to destroy"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the scope exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_global_managed_scope", &func)){ + doc_function_brief(arena, &func, "Get the id of the 'global' managed scope"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the global managed scope"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The global managed scope has a lifetime tied to the instance of 4coder itself. It is unique in that it does not combine with other scopes to create unique intersection scopes. To put it another way, all scopes are automatically implicitly dependent on the global scope, so adding it to the list of scopes in a 'multiple dependencies' scope has no effect on the result."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_managed_scope_with_multiple_dependencies", &func)){ + doc_function_brief(arena, &func, "Get a scope that has a lifetime dependent on all of the dependent scopes and is unique up to set isomorphisms of the 'hard' dependencies"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scopes"); + doc_text(arena, params, "a pointer at the base of an array of scope ids specifying the set of dependencies to use in querying or constructing the resulting scope"); + + doc_function_param(arena, &func, "count"); + doc_text(arena, params, "the number of scope ids in the scopes array"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the scope id of the scope with multiple dependencies on success, when all the scopes in input array exist, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The behavior of this call can be confusing so here are some rules of thumb for how it works, assuming all input scopes are valid:"); + doc_paragraph(arena, det); + doc_text(arena, det, "1. When there is only one scope in the parameters, that scope is the result. {A} -> A;"); + doc_paragraph(arena, det); + doc_text(arena, det, "2. When there are two or more parameters that are the same scope, the result is the that scope again. {A, A, ...} -> A;"); + doc_paragraph(arena, det); + doc_text(arena, det, "3. When any scope in the parameters is the special global scope, it is as if it is not there. {A, G} -> A"); + doc_paragraph(arena, det); + doc_text(arena, det, "4. When two scopes are constructed from the same set of parameters, they are the same, regardless of parameter order. {A, B} -> C; {B, A} -> C;"); + doc_paragraph(arena, det); + doc_text(arena, det, "5. When any of the scopes in the parameters was itself returned by this call, it is as if the parameters from it's constructor are substituted for it. {A, B} -> C; {C, D} -> E; {A, B, D} -> E;"); + doc_paragraph(arena, det); + doc_text(arena, det, "6. When the parameter set is empty the result is the global scope. {} -> G"); + doc_paragraph(arena, det); + doc_text(arena, det, "For a set-theoretic definition one can think of scopes as being keyed by a set of 'atoms'. Getting the key for a scope with multiple dependencies is defined by the operation of union of sets of atoms. The global scope is keyed by the empty set. A scope continues to exist as long all the atoms in it's key set exist."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_clear_contents", &func)){ + doc_function_brief(arena, &func, "Clear everything allocated inside a given scope without destroying the scope itself"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to clear"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the scope exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_clear_self_all_dependent_scopes", &func)){ + doc_function_brief(arena, &func, "Clear everything allocated inside an atomic scope and all of it's dependent scopes without destroying any of them"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the scope exists and is atomic, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "A scope is atomic when it uniquely tied to a specified entity or when it is directly created by the user. By the set-theoretic definition of scopes, a scope is atomic when it's key contains only one atom."); + doc_paragraph(arena, det); + doc_text(arena, det, "A scope is atomic specifically whenever it satisfies any of these conditions:"); + doc_paragraph(arena, det); + doc_text(arena, det, "1. It is a scope tied to a buffer and returned by buffer_get_managed_scope"); + doc_paragraph(arena, det); + doc_text(arena, det, "2. It is a scope tied to a view and returned by view_get_managed_scope"); + doc_paragraph(arena, det); + doc_text(arena, det, "3. It was created by a call to create_user_managed_scope"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_allocator", &func)){ + doc_function_brief(arena, &func, "Get the base allocator for a managed scope"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a pointer to the base allocator for the managed scope if it exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Anything allocated by this base allocator exists only as long as the managed scope exists. All of the allocations in the managed scope are freed by a bulk free operation when the managed scopes life time ends."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_id_group_highest_id", &func)){ + doc_function_brief(arena, &func, "Get the highest id issued for a particular group of managed ids"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "group"); + doc_text(arena, params, "a name identifying a managed id group"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the highest id returned by managed_id_declare for the given group, zero if the group has never been used to declare an id"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_id_declare", &func)){ + doc_function_brief(arena, &func, "Get a unique id for a given name within a particular group"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "group"); + doc_text(arena, params, "a name identifying a managed id group"); + + doc_function_param(arena, &func, "name"); + doc_text(arena, params, "a name identifying a managed id"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id assigned to the given (group, name) pair"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When this is called for the first time for a given group, the first id returned is 1, subsequent calls with new names for an existing group return the next highest id, calls for (group, name) pairs that have already been assigned an id return the same id again. The upshot of this is that managed ids can be used to essentially create run-time allocated co-operative enums, where the group names the enum, and the names are the elements of the enum."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_id_get", &func)){ + doc_function_brief(arena, &func, "Like managed_id_declare except never returns new ids, only ids that have already been declared."); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "group"); + doc_text(arena, params, "a name identifying a managed id group"); + + doc_function_param(arena, &func, "name"); + doc_text(arena, params, "a name identifying a managed id"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id assigned to the given (group, name) pair"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "managed_id_declare"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, ""); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_get_attachment", &func)){ + doc_function_brief(arena, &func, "Get an attachment contained to a managed scope, allocating it if necessary"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of a scope to query"); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the attachment to query"); + + doc_function_param(arena, &func, "size"); + doc_text(arena, params, "the expected size for the attachment, used to allocate memory when the attachment did not previously exist, used to check that the attachment is at least as large as expected if it already exists"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a pointer to the base of the attachment when the scope exists and no error ocurred in checking the size of the attachment, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Attachments are allocated on a scopes base allocator, and thus are only valid for as long as the scope itself is valid. Whe in doubt, re-query for an attachment and recheck that the pointer returned is non-zero, as often calls between one usage and another can have an effect on the location or existence of an attachment."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_scope_attachment_erase", &func)){ + doc_function_brief(arena, &func, "Free an attachment on a managed scope"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "scope"); + doc_text(arena, params, "the id of the scope to modify"); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the attachment to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the scope exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "alloc_buffer_markers_on_buffer", &func)){ + doc_function_brief(arena, &func, "Allocate buffer markers inside a managed scope and attach them to a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the buffer on which them markers will be attached"); + + doc_function_param(arena, &func, "count"); + doc_text(arena, params, "the number of markers to allocate"); + + doc_function_param(arena, &func, "optional_extra_scope"); + doc_text(arena, params, "either a null pointer, or a pointer to a managed scope"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the buffer exists, and the optional_extra_scope is valid, a new managed object id, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "By default, markers are allocated in the scope of the buffer they are attached to, this is how their lifetime is tied to the lifetime of the buffer. When an additional scope is supplied, it is combined with the buffer's scope via the same joining operation used in get_managed_scope_with_multiple_dependencies and the markers are allocated in that scope instead."); + doc_paragraph(arena, det); + doc_text(arena, det, "Markers are updated by edits to the buffer to which they are attached, so that they the same position in the buffer even as text is shifted around by edit operations. This can be used, for instance, to track the locations of compilation errors even as some compilation errors have already been fixed and shifted the position of later errors."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "get_managed_scope_with_multiple_dependencies"); + doc_function_add_related(arena, rel, "Marker"); + } + + //////////////////////////////// + + // TODO(allen): Remove alloc_managed_memory_in_scope + if (begin_doc_call(arena, cluster, api_def, "alloc_managed_memory_in_scope", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_item_size", &func)){ + doc_function_brief(arena, &func, "Get the size of the items in a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the managed object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the number of bytes in each item of the managed object, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the size of the items in the array."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_item_count", &func)){ + doc_function_brief(arena, &func, "Get the number of the items in a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the managed object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the number of items in the managed object, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the number of items in the array."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_pointer", &func)){ + doc_function_brief(arena, &func, "Get a pointer to he base of a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the managed object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, a pointer to the base of the memory allocated for the object, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Managed objects are essentially arrays with special management inside the core, such as markers. This call returns a pointer to base of the array. Careful! This pointer is a pointer to memory tied to a managed scope, so it can lose validity if the scope closes, and modifications to the memory at this pointer will be reflected throughout all systems relying on it."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_type", &func)){ + doc_function_brief(arena, &func, "Get a type code indicating what sort data is represented by a managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the object to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the type code of the object, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_get_containing_scope", &func)){ + doc_function_brief(arena, &func, "Get the id of the scope that contains a particular managed object"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of a managed object"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the object exists, the id of the managed scope that contains the object, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "managed_object_free", &func)){ + doc_function_brief(arena, &func, "Destroy a managed object, free it's memory back to the scope containing it, and detach it from whatever associations it has in the core"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "object"); + doc_text(arena, params, "the id of the object to free"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the object exists, otherwise zero"); + } + + //////////////////////////////// + + // TODO(allen): remove managed_object_store_data + if (begin_doc_call(arena, cluster, api_def, "managed_object_store_data", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove managed_object_load_data + if (begin_doc_call(arena, cluster, api_def, "managed_object_load_data", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_next_input", &func)){ + doc_function_brief(arena, &func, "In a view context, yield control to the core until new input is sent to this view, then return that input"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "get_properties"); + doc_text(arena, params, "flags for properties of an event that should be allowed to be returned from this call"); + + doc_function_param(arena, &func, "abort_properties"); + doc_text(arena, params, "flags for properties of an event that should be converted into abort events before returning from this call"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the next input that is sent to this view context, or cleared to zero if this is not a view context thread"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "This works as a blocking call on it's thread, blocking until the core has more input. However it only works in view context threads. View context threads are created by the core whenever a view is created, and has the primary responsibility of dispatching user input and other events. The base of view context threads is determined by HookID_ViewEventHandler."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "User_Input"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_current_input_sequence_number", &func)){ + doc_function_brief(arena, &func, "In a view context, get the sequence number for the input that has been most recently sent to the view"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the sequence number of the most recent input sent to the view, or zero if this is not a view context thread"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "get_next_input"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_current_input", &func)){ + doc_function_brief(arena, &func, "In a view context, get the input that has been most recently sent to the view"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the most recent input sent to the view; cleared to zero if this is not called from a view context thread, or if no inputs have been sent to this view context thread yet"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "get_next_input"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_current_input", &func)){ + doc_function_brief(arena, &func, "Modify the memory of the event that was most recently sent to the calling view context memory"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "input"); + doc_text(arena, params, "a pointer to the input struct to copy over the existing input struct in the core"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "This call only has the effect of altering the result of future calls to get_current_input until the next time input is sent to the calling view context thread. There is no effect when called from threads that are not view contexts."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "leave_current_input_unhandled", &func)){ + doc_function_brief(arena, &func, "Notifies the core that the input currently being handled by a view context thread should be treated as if it were not handled"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When events are handled, future handlers for them are skipped. This is especially important because text input is passed as a seperate event after key stroke events, and if a key stroke event is marked as handled, then the text event that would have been generated by the key stroke is skipped."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_custom_hook", &func)){ + doc_function_brief(arena, &func, "Modify the a global hook binding"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "hook_id"); + doc_text(arena, params, "the id of the hook to be modified"); + + doc_function_param(arena, &func, "func_ptr"); + doc_text(arena, params, "a pointer to the hook function, the function pointer must have a specific signature to match the hook_id's expected signature, but this call does not do the type checking for this, so watch out for that"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Hook_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_custom_hook_memory_size", &func)){ + doc_function_brief(arena, &func, "Set the memory size for the extra memory used to store the state of certain hooks"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "hook_id"); + doc_text(arena, params, "the id of the hook to be modified"); + + doc_function_param(arena, &func, "size"); + doc_text(arena, params, "the size in bytes of the memory set aside for the state of the specified hook"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the hook id is valid and accepts extra memory size, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "view_current_context_hook_memory"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_mouse_state", &func)){ + doc_function_brief(arena, &func, "Get the state of the mouse as of this frame"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the current mouse state struct"); + } + + //////////////////////////////// + + // TODO(allen): remove get_active_query_bars + if (begin_doc_call(arena, cluster, api_def, "get_active_query_bars", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove start_query_bar + if (begin_doc_call(arena, cluster, api_def, "start_query_bar", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove end_query_bar + if (begin_doc_call(arena, cluster, api_def, "end_query_bar", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): remove clear_all_query_bars + if (begin_doc_call(arena, cluster, api_def, "clear_all_query_bars", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "print_message", &func)){ + doc_function_brief(arena, &func, "Print a message to the *messages* buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "message"); + doc_text(arena, params, "the string to write to the *messages* buffer"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "log_string", &func)){ + doc_function_brief(arena, &func, "Write a string to the *log* buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "str"); + doc_text(arena, params, "the string to write to the log"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the string was written to the log, each thread can individually have logging disabled, in which case zero is returned"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_largest_face_id", &func)){ + doc_function_brief(arena, &func, "Get the largest face id that is currently assigned to a face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the largest face id that is currently assigned to a face"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "set_global_face", &func)){ + doc_function_brief(arena, &func, "Change the global default face"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "id"); + doc_text(arena, params, "the id of the new global default face"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the face exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "", &func)){ + doc_function_brief(arena, &func, ""); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, ""); + doc_text(arena, params, ""); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, ""); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, ""); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, ""); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "", &func)){ + doc_function_brief(arena, &func, ""); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, ""); + doc_text(arena, params, ""); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, ""); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, ""); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, ""); + } + + return(cluster); +} + +#include +int main(void){ + Arena arena = make_arena_malloc(); + + String_Const_u8 me = string_u8_litexpr(__FILE__); + String_Const_u8 docs_folder = string_remove_last_folder(me); + String_Const_u8 root = string_remove_last_folder(docs_folder); + String_Const_u8 file_name = push_u8_stringf(&arena, "%.*scustom/generated/custom_api_master_list.h", + string_expand(root)); + + FILE *file = fopen((char*)file_name.str, "rb"); + if (file == 0){ + printf("could not load %s\n", file_name.str); + return(1); + } + + printf("documenting %s\n", file_name.str); + String_Const_u8 text = file_load_all(&arena, file); + fclose(file); + + API_Definition_List def_list = {}; + api_parse_source_add_to_list(&arena, file_name, text, &def_list); + + API_Definition *api_def = api_get_api(&def_list, string_u8_litexpr("custom")); + Doc_Cluster *cluster = doc_custom_api(&arena, api_def); + + for (Doc_Log *node = cluster->first_log; + node != 0; + node = node->next){ + printf("%.*s\n", string_expand(node->content)); + } + + return(0); +} + +// BOTTOM + diff --git a/docs/4ed_doc_custom_api_buffer.cpp b/docs/4ed_doc_custom_api_buffer.cpp new file mode 100644 index 00000000..1450d9d6 --- /dev/null +++ b/docs/4ed_doc_custom_api_buffer.cpp @@ -0,0 +1,1033 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 07.12.2019 + * + * Documentation of the custom layer's primary api : buffer-related calls + * + */ + +// TOP + +function void +doc_custom_api__buffer(Arena *arena, API_Definition *api_def, Doc_Cluster *cluster){ + Doc_Function func = {}; + + if (begin_doc_call(arena, cluster, api_def, "get_buffer_count", &func)){ + doc_function_brief(arena, &func, "Retrieve the number of buffers loaded in the core"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the number of buffers loaded in the core"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_buffer_next", &func)){ + doc_function_brief(arena, &func, "Iterate to the next buffer loaded in the core"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to iterate from, or zero to get the first buffer"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements used to filter on the buffers that are returned"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the next buffer, or zero if there is no next buffer"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_buffer_by_name", &func)){ + doc_function_brief(arena, &func, "Retrieve a buffer querying by name"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "name"); + doc_text(arena, params, "the name to query against buffer names"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements used to determine whether or not to return a match"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the buffer who's name agrees with name if it exists and it has the required access state, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_buffer_by_file_name", &func)){ + doc_function_brief(arena, &func, "Retrieve a buffer querying by file name"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "file_name"); + doc_text(arena, params, "the name to query against buffer file names"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements used to determine whether or not to return a match"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the buffer who's attached file name agrees with file_name if it exists and it has the required access state, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_read_range", &func)){ + doc_function_brief(arena, &func, "Read a range of text out of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to be read"); + + doc_function_param(arena, &func, "range"); + doc_text(arena, params, "byte range in the buffer that will be read - the range is left inclusive right exclusive, for example the range [10,20) reads ten bytes, with the first byte read being the one with index 10."); + + doc_function_param(arena, &func, "out"); + doc_text(arena, params, "the buffer that will get the copy of the new text which should have at least range.max - range.min available bytes"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer exists and the range is completely contained within the buffer's contents, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_replace_range", &func)){ + doc_function_brief(arena, &func, "Replace a range of text with a specific string"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + doc_function_param(arena, &func, "range"); + doc_text(arena, params, "the range of bytes to replace - the range is left inclusive right exclusive, for example the range [10,20) replaces ten bytes and the byte at index 20 remains in the buffer, possibly shifted if the string is not ten bytes"); + + doc_function_param(arena, &func, "string"); + doc_text(arena, params, "the new text to be placed in the given range"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer eixsts and the range is contained within the buffer, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "This operation is used to implement inserts by setting the range to be empty, [x,x) inserts the string at x, and it implements deletion by setting the string to be empty."); + + doc_paragraph(arena, det); + + doc_text(arena, det, "All modifications made by this call are simultaneously saved onto the buffer's history if is enabled."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_batch_edit", &func)){ + doc_function_brief(arena, &func, "Replace a sorted sequence of ranges with specific strings"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + doc_function_param(arena, &func, "batch"); + doc_text(arena, params, "the first batch edit in a linked list of edits to apply in one atomic modification"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer exists and the batch is correctly sorted and contained within the buffer, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The ranges of the batch edit should all refer to the range they would have edited in the original state of the buffer. Put another way, the user should make no assumption about what order the individual edist are applied, and instead should treat the operation as applying all replacements atomically."); + + doc_paragraph(arena, det); + + doc_text(arena, det, "All modifications made by this call are saved into the history as a single edit record, thus undoing this edit reversed the entire batch."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "buffer_replace_range"); + doc_function_add_related(arena, rel, "Batch_Edit"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_seek_string", &func)){ + doc_function_brief(arena, &func, "Scan a buffer from a point to the first occurence of a string"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer"); + doc_text(arena, params, "the id of the buffer who's contents to seek"); + + doc_function_param(arena, &func, "needle"); + doc_text(arena, params, "the string to match against the contents of the buffer"); + + doc_function_param(arena, &func, "direction"); + doc_text(arena, params, "the scan direction of the scan from the start point"); + + doc_function_param(arena, &func, "start_pos"); + doc_text(arena, params, "the start point of the scan"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a single string match containing the range of the match and 'match type' flags on success, when the buffer exists and a match is found, otherwise cleared to zero; one can easily determine whether there was a match by the buffer member of the result"); + + doc_paragraph(arena, ret); + + doc_text(arena, ret, "The returned range is left inclusive right exclusive, so that range.max - range.min is the size of the match, and range.min is the first index of the matching string."); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The match is never permitted to be found at start_pos, thus to search the whole buffer from the beginning start_pos should be -1 and to search backward from the end start_pos should be the size of the buffer."); + + doc_paragraph(arena, ret); + + doc_text(arena, ret, "Non-case sensitive matches are reported, but if the match that was found is case sensitive the StringMatch_CaseSensitive flag is set on the result."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Scan_Direction"); + doc_function_add_related(arena, rel, "String_Match"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_seek_character_class", &func)){ + doc_function_brief(arena, &func, "Scan a buffer from a point to the first character in a specified set of characters"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer"); + doc_text(arena, params, "the id of the buffer who's contents to seek"); + + doc_function_param(arena, &func, "predicate"); + doc_text(arena, params, "specifies the set of bytes that will end the scan"); + + doc_function_param(arena, &func, "direction"); + doc_text(arena, params, "the scan direction of the scan from the start point"); + + doc_function_param(arena, &func, "start_pos"); + doc_text(arena, params, "the start point of the scan"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a single string match containing a range of a single character on success, when the buffer exists and a match is found, otherwise a cleared to zero; one can easily determine whether there was a match by the buffer member of the result"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Character_Predicate"); + doc_function_add_related(arena, rel, "String_Match"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_line_y_difference", &func)){ + doc_function_brief(arena, &func, "Compute the signed vertical pixel distance between the top of two lines"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's layout will be measured"); + + doc_function_param(arena, &func, "width"); + doc_text(arena, params, "the width parameter of the layout, passed to layout rules as a recommended wrap point"); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the face parameter of the layout, passed to layout rules as a recommended face"); + + doc_function_param(arena, &func, "line_a"); + doc_text(arena, params, "the line number of the line 'A' in the subtraction top(A) - top(B)"); + + doc_function_param(arena, &func, "line_b"); + doc_text(arena, params, "the line number of the line 'B' in the subtraction top(A) - top(B)"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the signed distance between the lines in pixels on success, when the buffer exists and contains both given line numbers"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_line_shift_y", &func)){ + doc_function_brief(arena, &func, "Compute a new line number and pixel shift relative to a given line number and pixel shift, guaranteeing that the new line number is the one closest to containing the new point"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's layout will be measured"); + + doc_function_param(arena, &func, "width"); + doc_text(arena, params, "the width parameter of the layout, passed to layout rules as a recommended wrap point"); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the face parameter of the layout, passed to layout rules as a recommended face"); + + doc_function_param(arena, &func, "line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "y_shift"); + doc_text(arena, params, "the y shift, in pixels, from the top of the specified line to be measured"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the best match line number and the remaining y shift that is not accounted for by the change in line number on success, when the buffer exists and contains the line, cleared to zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Line_Shift_Vertical"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_pos_at_relative_xy", &func)){ + doc_function_brief(arena, &func, "Compute a byte position at a particular point relative to the top left corner of a particular line"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's layout will be measured"); + + doc_function_param(arena, &func, "width"); + doc_text(arena, params, "the width parameter of the layout, passed to layout rules as a recommended wrap point"); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the face parameter of the layout, passed to layout rules as a recommended face"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "relative_xy"); + doc_text(arena, params, "the point, in pixels, interpreted relative to the line's top left corner, that will serve as the query point"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the byte index associated as the first byte of a character in the layout that is the closest to containing the query point on success, when the buffer exists and contains the line, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_relative_box_of_pos", &func)){ + doc_function_brief(arena, &func, "Compute the box of a character that spans a particular byte position, relative to the top left corner of a given line"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's layout will be measured"); + + doc_function_param(arena, &func, "width"); + doc_text(arena, params, "the width parameter of the layout, passed to layout rules as a recommended wrap point"); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the face parameter of the layout, passed to layout rules as a recommended face"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "pos"); + doc_text(arena, params, "the absolute byte index of the position to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the rectangle of a character in the layout that is closest to including the given query position in it's span, with coordinates set relative to the top left corner of the base line, on success, when the buffer exists and contains the base line and query position, cleared to zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_relative_character_from_pos", &func)){ + doc_function_brief(arena, &func, "Compute a character index relative to a particular lines first character"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's layout will be measured"); + + doc_function_param(arena, &func, "width"); + doc_text(arena, params, "the width parameter of the layout, passed to layout rules as a recommended wrap point"); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the face parameter of the layout, passed to layout rules as a recommended face"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "pos"); + doc_text(arena, params, "the absolute byte index of the position to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the relative index, based at the first character of the base line, of the character that is closest to spanning the query position on success, when the buffer exists and contains the base line and query position, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_pos_from_relative_character", &func)){ + doc_function_brief(arena, &func, "Compute the byte position associated with the start of a particular character specified relative to the first character of a particular line"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's layout will be measured"); + + doc_function_param(arena, &func, "width"); + doc_text(arena, params, "the width parameter of the layout, passed to layout rules as a recommended wrap point"); + + doc_function_param(arena, &func, "face_id"); + doc_text(arena, params, "the face parameter of the layout, passed to layout rules as a recommended face"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "relative_character"); + doc_text(arena, params, "the relative character index of the query character, based at the first character of base line"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the byte index associated with the start of the character specified by the the base_line and relative_character parameters on success, when the buffer exists and contains the base line, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_exists", &func)){ + doc_function_brief(arena, &func, "Check that a buffer id represents a real buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the buffer id to check"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the buffer exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_access_flags", &func)){ + doc_function_brief(arena, &func, "Retrieve the access flags of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the access flag fied of the buffer on success, when the buffer exists, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Access_Flag"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_size", &func)){ + doc_function_brief(arena, &func, "Retrieve the size of a buffer in bytes"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the size in bytes of the buffer on success, when the buffer exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_line_count", &func)){ + doc_function_brief(arena, &func, "Retrieve the line count of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the number of lines in the buffer on success, when the buffer exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "push_buffer_base_name", &func)){ + doc_function_brief(arena, &func, "Get a copy of the base name of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "arena"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the name assigned to the buffer when it was created on success, when the buffer exists, otherwise an empty string"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "push_buffer_unique_name", &func)){ + doc_function_brief(arena, &func, "Get a copy of the unique name of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "out"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the name assigned to the buffer by resolving duplicate names on success, when the buffer exists, otherwise an empty string"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "push_buffer_file_name", &func)){ + doc_function_brief(arena, &func, "Get a copy of the file name of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "arena"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the name of the file attached to the buffer when it was created, when the buffer exists and has an attached file, otherwise an empty string"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_dirty_state", &func)){ + doc_function_brief(arena, &func, "Retrieve the dirty state flags of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the dirty state flags of the buffer on success, when it exists, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Dirty_State"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_set_dirty_state", &func)){ + doc_function_brief(arena, &func, "Set the dirty state of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to be modified"); + + doc_function_param(arena, &func, "dirty_state"); + doc_text(arena, params, "the new value for the buffer's dirty state"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer exists, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Dirty_State"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_layout", &func)){ + doc_function_brief(arena, &func, "Retrieve the layout rule of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a pointer to the function specifying the buffer's layout rule on success, when the buffer exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_setting", &func)){ + doc_function_brief(arena, &func, "Retrieve a core setting of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + doc_function_param(arena, &func, "setting"); + doc_text(arena, params, "the id of the setting to query"); + + doc_function_param(arena, &func, "value_out"); + doc_text(arena, params, "the output destination of the setting's value"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer and setting exist, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Setting_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_set_setting", &func)){ + doc_function_brief(arena, &func, "Retrieve a core setting of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + doc_function_param(arena, &func, "setting"); + doc_text(arena, params, "the id of the setting to modify"); + + doc_function_param(arena, &func, "value"); + doc_text(arena, params, "the new value of the specified setting"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer and setting exist, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Setting_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_managed_scope", &func)){ + doc_function_brief(arena, &func, "Retrieve the managed scope tied to the lifetime of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the managed scope tied to the buffer on success, when the buffer exists, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Managed_Scope"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_send_end_signal", &func)){ + doc_function_brief(arena, &func, "Cause the buffer to reset it's lifetime"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to receive the signal"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the buffer exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When a buffer's end signal is sent, it's managed scope is cleared, as if it had been destroyed and recreated, and the buffer end hook is run on the buffer. The upshot of this is that it is as if the buffer were closed and re-opened except that it still has the same id."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "create_buffer", &func)){ + doc_function_brief(arena, &func, "Create a new buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "file_name"); + doc_text(arena, params, "if there exists a file with the given name, and no buffer for that file, a new buffer is created, attached to the file, and named after the file; if no such file exists, or the buffer is forbidden from attaching to a file by the flags, then this is the name of a newly created detached buffer"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags controlling behavior of the buffer creation"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "if a buffer matching the file name already exists, it's id is returned, otherwise if a new buffer can be created according to the flags, a buffer is created and it's id is returned, if no matching buffer exists and no buffer can be created from it, zero is returned"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Create_Flag"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_save", &func)){ + doc_function_brief(arena, &func, "Save the contents of a buffer to a file"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer who's contents to write to disk"); + + doc_function_param(arena, &func, "file_name"); + doc_text(arena, params, "the name of the file to be written, if empty and the buffer has an attached file, that is used instead, using this does not alter the attachment of the buffer either way"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags controlling the behavior of the save"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the buffer exists and the file was successfully written, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Save_Flag"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_kill", &func)){ + doc_function_brief(arena, &func, "Close a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to close"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags controlling the buffer closing behavior"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a code indicating the result of the attempt to kill a buffer, if the buffer does not exist this will be a failure, if the buffer exists but has unsaved changes, this will indicate as much unless flag was used to override the dirty state check, if the buffer is successfully closed that will be indicated by the code"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When a buffer's dirty state includes unsaved changes, this call will not close the buffer unless it is forced to by the flags."); + doc_paragraph(arena, det); + doc_text(arena, det, "Certain buffers critical to the operation of the core cannot be closed, and attempts to close them will always result in failure to close."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Kill_Result"); + doc_function_add_related(arena, rel, "Buffer_Kill_Flag"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_reopen", &func)){ + doc_function_brief(arena, &func, "Reload the content of a buffer from the the attached file"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to reload"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags controlling the behavior of the reload"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the buffer exists and has an attached file that can be read, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Reopen_Flag"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_file_attributes", &func)){ + doc_function_brief(arena, &func, "Get file attributes of a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the file attributes of the buffer as set by the last time it synced with it's attached file on disk when the buffer exists, cleared to zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "File_Attributes"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_compute_cursor", &func)){ + doc_function_brief(arena, &func, "Compute a buffer cursor from a buffer and a seek target"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer"); + doc_text(arena, params, "the id of the buffer to query"); + + doc_function_param(arena, &func, "seek"); + doc_text(arena, params, "the seek target to use in a query for full cursor information"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the full cursor information for the position specified by the seek, if the buffer exists, otherwise cleared to zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Seek"); + doc_function_add_related(arena, rel, "Buffer_Cursor"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_history_get_max_record_index", &func)){ + doc_function_brief(arena, &func, "Get the largest record index in the buffer history"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "if the buffer exists and has history enabled, the maximum index of the records in the history, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_history_get_record_info", &func)){ + doc_function_brief(arena, &func, "Get record information out of a buffer's history"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + doc_function_param(arena, &func, "index"); + doc_text(arena, params, "the index of the record to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the buffer exists and index is within the history index range, the record information at the given index, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Record_Info"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_history_get_group_sub_record", &func)){ + doc_function_brief(arena, &func, "Get a sub-record of a group record from a buffer history"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + doc_function_param(arena, &func, "index"); + doc_text(arena, params, "the index of the record to query"); + + doc_function_param(arena, &func, "sub_index"); + doc_text(arena, params, "the sub-index of the record to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the buffer exists, it's history contains a group record at the given index, and the group record contains a record at the sub-index, the record information contained there, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Record_Info"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_history_get_current_state_index", &func)){ + doc_function_brief(arena, &func, "Get the current state index of the history"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "if the buffer exists and has history enabled, the current state index, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The current state index indicates how far backward the user has undone. If the index is the most recent record, then nothing has been undone. This way undo-redo operations do not have to modify the history stack, and instead just move the current state index through the stack. Normal modifications to the buffer cause the history to discard everything after the current state index, before putting the new record on top of the stack."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_history_set_current_state_index", &func)){ + doc_function_brief(arena, &func, "Modify the current state index and update the buffer contents to reflect the contents of the buffer as it was at that index."); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to modify"); + + doc_function_param(arena, &func, "index"); + doc_text(arena, params, "the new current state index value"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the buffer exists, has history enabled, and contains a record at the given index, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "This call simultaneously changes the state index and modifies the buffer to reflect undoing the necessary records from the top of the stack, or redoing them if the state index is being moved forward."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "", &func)){ + doc_function_brief(arena, &func, ""); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, ""); + doc_text(arena, params, ""); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, ""); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, ""); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, ""); + } +} + +// BOTTOM + diff --git a/docs/4ed_doc_custom_api_global.cpp b/docs/4ed_doc_custom_api_global.cpp new file mode 100644 index 00000000..5ec02b5b --- /dev/null +++ b/docs/4ed_doc_custom_api_global.cpp @@ -0,0 +1,275 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 07.12.2019 + * + * Documentation of the custom layer's primary api : global-related calls + * + */ + +// TOP + +function void +doc_custom_api__global(Arena *arena, API_Definition *api_def, Doc_Cluster *cluster){ + Doc_Function func = {}; + + if (begin_doc_call(arena, cluster, api_def, "global_set_setting", &func)){ + doc_function_brief(arena, &func, "Modify a core setting"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "setting"); + doc_text(arena, params, "the id of the setting to set"); + + doc_function_param(arena, &func, "value"); + doc_text(arena, params, "the new value for the setting"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero when the setting is valid and updated without error, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Global_Setting_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "global_get_screen_rectangle", &func)){ + doc_function_brief(arena, &func, "Get the rectangle the represents the renderable region in pixels"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "an f32 rectangle based as (0, 0) that represents the entire renderable region in pixels"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_thread_context", &func)){ + doc_function_brief(arena, &func, "Get the current thread's context"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the pointer to the current thread's context"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "create_child_process", &func)){ + doc_function_brief(arena, &func, "Create a child process of the 4coder process"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "path"); + doc_text(arena, params, "the active path set for the new child process"); + + doc_function_param(arena, &func, "command"); + doc_text(arena, params, "the command that defines the action of the child process - this string is passed to the OS's default command line handler"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success a non-zero id for the new child process which is unique across the entire 4coder session, zero on failure"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "child_process_set_target_buffer", &func)){ + doc_function_brief(arena, &func, "Create a link between a child process and a buffer, so that output from the child process is written to the buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "child_process_id"); + doc_text(arena, params, "the id of the child process who's output will be linked"); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer that will receive the output"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags setting the behavior when the child process or buffer already have a link"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success when the two entities exist and the link is created non-zero, otherwise zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Each child process and each buffer may only be a part of one link at a time. So when either is already linked a decision needs to be made to either destroy that link or not create the new link. This decision is controlled by the flags."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Child_Process_Set_Target_Flags"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "buffer_get_attached_child_process", &func)){ + doc_function_brief(arena, &func, "Retrieve the child process linked to a buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "if the given buffer exists and has an attached child process it's id is returned, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "child_process_get_attached_buffer", &func)){ + doc_function_brief(arena, &func, "Retrieve the buffer linked to a child process"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "child_process_id"); + doc_text(arena, params, "the id of the child process"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "if the given child process exists and has an attached buffer it's id is returned, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "child_process_get_state", &func)){ + doc_function_brief(arena, &func, "Get the state of a child process"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "child_process_id"); + doc_text(arena, params, "the id of the child process"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the state fields of the child process"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Process_State"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "clipboard_post", &func)){ + doc_function_brief(arena, &func, "Post a string to 4coder internal clipboard and the system clipboard"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "clipboard_id"); + doc_text(arena, params, "the id of the clipboard to receive the post - currently an ignored parameter and should be set to zero"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the state fields of the child process"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "clipboard_count", &func)){ + doc_function_brief(arena, &func, "Retrieve the number of strings on the clipboard's history"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "clipboard_id"); + doc_text(arena, params, "the id of the clipboard to query - currently an ignored parameter and should be set to zero"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the number of strings on the clipboard's history"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "push_clipboard_index", &func)){ + doc_function_brief(arena, &func, "Get a copy of a string from the clipboard history by index"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "arena"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + doc_function_param(arena, &func, "clipboard_id"); + doc_text(arena, params, "the id of the clipboard to query - currently an ignored parameter and should be set to zero"); + + doc_function_param(arena, &func, "item_index"); + doc_text(arena, params, "the index in the clipboard history to query, 0 always the most recent string in the history"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the clipboard contains a string at the given index, a copy of the string is returned, otherwise an empty string is returned"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "push_clipboard_index", &func)){ + doc_function_brief(arena, &func, "Get a copy of a string from the clipboard history by index"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "arena"); + doc_text(arena, params, "the arena on which the returned string will be allocated"); + + doc_function_param(arena, &func, "clipboard_id"); + doc_text(arena, params, "the id of the clipboard to query - currently an ignored parameter and should be set to zero"); + + doc_function_param(arena, &func, "item_index"); + doc_text(arena, params, "the index in the clipboard history to query, 0 always the most recent string in the history"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the clipboard contains a string at the given index, a copy of the string is returned, otherwise an empty string is returned"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "enqueue_virtual_event", &func)){ + doc_function_brief(arena, &func, "Push an event to the core to be processed as if it were a real event"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "event"); + doc_text(arena, params, "a pointer to an event struct that contains the information that will be in the virtual event"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "on success, when the event specified is validly formed, non-zero is returned, otherwise zero is returned"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "All virtual events are triggered after all directly enqueued commands, before the next real event, and before the current frame renders."); + } +} + +// BOTTOM + diff --git a/docs/4ed_doc_custom_api_view.cpp b/docs/4ed_doc_custom_api_view.cpp new file mode 100644 index 00000000..7df6112e --- /dev/null +++ b/docs/4ed_doc_custom_api_view.cpp @@ -0,0 +1,1011 @@ +/* + * Mr. 4th Dimention - Allen Webster + * + * 07.12.2019 + * + * Documentation of the custom layer's primary api : view-related calls + * + */ + +// TOP + +function void +doc_custom_api__view(Arena *arena, API_Definition *api_def, Doc_Cluster *cluster){ + Doc_Function func = {}; + + if (begin_doc_call(arena, cluster, api_def, "view_line_y_difference", &func)){ + doc_function_brief(arena, &func, "Compute the signed vertical pixel distance between the top of two lines"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's layout will be measured"); + + doc_function_param(arena, &func, "line_a"); + doc_text(arena, params, "the line number of the line 'A' in the subtraction top(A) - top(B)"); + + doc_function_param(arena, &func, "line_b"); + doc_text(arena, params, "the line number of the line 'B' in the subtraction top(A) - top(B)"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the signed distance between the lines in pixels on success, when the view exists and contains both given line numbers"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + doc_paragraph(arena, det); + doc_text(arena, det, "Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_line_shift_y", &func)){ + doc_function_brief(arena, &func, "Compute a new line number and pixel shift relative to a given line number and pixel shift, guaranteeing that the new line number is the one closest to containing the new point"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's layout will be measured"); + + doc_function_param(arena, &func, "line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "y_shift"); + doc_text(arena, params, "the y shift, in pixels, from the top of the specified line to be measured"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the best match line number and the remaining y shift that is not accounted for by the change in line number on success, when the view exists and contains the line, cleared to zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + doc_paragraph(arena, det); + doc_text(arena, det, "Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Line_Shift_Vertical"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_pos_at_relative_xy", &func)){ + doc_function_brief(arena, &func, "Compute a byte position at a particular point relative to the top left corner of a particular line"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's layout will be measured"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "relative_xy"); + doc_text(arena, params, "the point, in pixels, interpreted relative to the line's top left corner, that will serve as the query point"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the byte index associated as the first byte of a character in the layout that is the closest to containing the query point on success, when the view exists and contains the line, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + doc_paragraph(arena, det); + doc_text(arena, det, "Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_relative_box_of_pos", &func)){ + doc_function_brief(arena, &func, "Compute the box of a character that spans a particular byte position, relative to the top left corner of a given line"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's layout will be measured"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "pos"); + doc_text(arena, params, "the absolute byte index of the position to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the rectangle of a character in the layout that is closest to including the given query position in it's span, with coordinates set relative to the top left corner of the base line, on success, when the view exists and contains the base line and query position, cleared to zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + doc_paragraph(arena, det); + doc_text(arena, det, "Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_relative_character_from_pos", &func)){ + doc_function_brief(arena, &func, "Compute a character index relative to a particular lines first character"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's layout will be measured"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "pos"); + doc_text(arena, params, "the absolute byte index of the position to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the relative index, based at the first character of the base line, of the character that is closest to spanning the query position on success, when the view exists and contains the base line and query position, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + doc_paragraph(arena, det); + doc_text(arena, det, "Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_pos_from_relative_character", &func)){ + doc_function_brief(arena, &func, "Compute the byte position associated with the start of a particular character specified relative to the first character of a particular line"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's layout will be measured"); + + doc_function_param(arena, &func, "base_line"); + doc_text(arena, params, "the line number of the line that serves as the relative starting point of the measurement"); + + doc_function_param(arena, &func, "character"); + doc_text(arena, params, "the relative character index of the query character, based at the first character of base line"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the byte index associated with the start of the character specified by the the base_line and relative_character parameters on success, when the view exists and contains the base line, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Line numbers are 1 based."); + doc_paragraph(arena, det); + doc_text(arena, det, "Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_view_next", &func)){ + doc_function_brief(arena, &func, "Iterate to the next view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to iterate from, or zero to get the first view"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements used to filter on the views that are returned"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the next view, or zero if there is no next view"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_view_prev", &func)){ + doc_function_brief(arena, &func, "Iterate to the previous view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to iterate from, or zero to get the first view"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements used to filter on the views that are returned"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the previous view, or zero if there is no previous view"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_this_ctx_view", &func)){ + doc_function_brief(arena, &func, "Get the view attached to the thread context"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements that the view must satisfy"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the view attached to this thread, if the calling thread is a view context, and if it can satisfy the access requirements, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "get_active_view", &func)){ + doc_function_brief(arena, &func, "Get the id of the active view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements that the view must satisfy"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the active view, if it can satisfy the access requirements, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_exists", &func)){ + doc_function_brief(arena, &func, "Check that a view id represents a real view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_buffer", &func)){ + doc_function_brief(arena, &func, "Get the buffer attached to a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "required access flags for the buffer, in this call the flag Access_Visible indicates whether the view is currently displaying it's buffer, by adding it to the access flags you can require that the buffer is visible"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the buffer if the view exists and the buffer satisfies the access requirements, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_cursor_pos", &func)){ + doc_function_brief(arena, &func, "Get the position of the core tracked cursor on a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the position of the view's cursor in bytes, if the view exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_mark_pos", &func)){ + doc_function_brief(arena, &func, "Get the position of the core tracked mark on a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the position of the view's mark in bytes, if the view exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_preferred_x", &func)){ + doc_function_brief(arena, &func, "Get the x coordinate of the core tracked preferred x on a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the preferred x of the view in pixels from the left edge of buffer layout space, if the view exists, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_set_preferred_x", &func)){ + doc_function_brief(arena, &func, "Set the preferred x on a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "x"); + doc_text(arena, params, "the new preferred x coordinate"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "the preferred x is used to keep a cursor aligned as closely as possible to a particular x-coordinate durring vertical movements"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_screen_rect", &func)){ + doc_function_brief(arena, &func, "Get the rectangle on screen covered by a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the rectangle covered by the view in pixels relative to the screen rectangle's top left corner, if the view exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_panel", &func)){ + doc_function_brief(arena, &func, "Get the id of a panel associated with a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the panel associated with the view, if the view exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Associations between panels and views are not 'stable'. They often change whenever the layout of panels is adjusted. The results of this query should only be taken as correct for as long as no panels or views are opened or closed."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_get_view", &func)){ + doc_function_brief(arena, &func, "Get the id of a view associated with a panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to query"); + + doc_function_param(arena, &func, "access"); + doc_text(arena, params, "the type of access requirements that the view must satisfy"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the view associated with the panel, if the panel exists and is a 'leaf' panel in the panel layout, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Associations between panels and views are not 'stable'. They often change whenever the layout of panels is adjusted. The results of this query should only be taken as correct for as long as no panels or views are opened or closed."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_is_split", &func)){ + doc_function_brief(arena, &func, "Check if a panel is an internal split panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the panel exists and is an internal panel in the panel layout tree"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The panel layout tree is a binary tree with internal panels having exactly two children and a split rule, and leaf panels having an associated view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_is_leaf", &func)){ + doc_function_brief(arena, &func, "Check if a panel is a leaf panel with an associated view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the panel exists and is a leaf panel in the panel layout tree"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "The panel layout tree is a binary tree with internal panels having exactly two children and a split rule, and leaf panels having an associated view."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_split", &func)){ + doc_function_brief(arena, &func, "Introduce a split at a given panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to split"); + + doc_function_param(arena, &func, "split_dim"); + doc_text(arena, params, "the dimension along which the split is placed - x splits split the horizontal axis with a vertical divider - y splits split the vertical axis with a horizontal divider"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the panel exists and splitting it is possible, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "New splits are created as 50/50 proportional splits."); + doc_paragraph(arena, det); + doc_text(arena, det, "The only limit on splits is the number of views, which is 16. When a leaf panel is split, the view it was associated with is placed in the 'min' child of the split and a panel with a new view is placed in the 'max' child of the split. When an internal panel is split, it's 'min' child adopts the old children and split settings of the panel and the 'max' child gets a panel with a new view."); + doc_paragraph(arena, det); + doc_text(arena, det, "In either case, a successful split puts a new leaf panel in the 'max' child, puts the old contents of the panel into the 'min' child. The id of the panel that was split becomes the id of the parent of the split. View panel associations are modified by a split."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_set_split", &func)){ + doc_function_brief(arena, &func, "Set the split properties of a split panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to modify"); + + doc_function_param(arena, &func, "kind"); + doc_text(arena, params, "the kind of split rule used to determine the position of the split"); + + doc_function_param(arena, &func, "t"); + doc_text(arena, params, "the value parameter of the split rule"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the panel exists and is a split panel, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, ""); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_swap_children", &func)){ + doc_function_brief(arena, &func, "Swap the min and max children of a split panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the panel exists and is a split panel"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_get_root", &func)){ + doc_function_brief(arena, &func, "Get the root panel of the panel layout"); + + // params + doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the root panel"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_get_parent", &func)){ + doc_function_brief(arena, &func, "Get the parent panel of a panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the panel that is the parent of the given panel, if the given panel exists and is not root, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "panel_get_child", &func)){ + doc_function_brief(arena, &func, "Get one of the children of a split panel"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "panel_id"); + doc_text(arena, params, "the id of the panel to query"); + + doc_function_param(arena, &func, "which_child"); + doc_text(arena, params, "the selector for which of the children to acquire, 'min' children are the children on the top or left, and 'max' children are the children on the bottom or right, depending on the dimension of the split"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the requested child of the given panel, if the given panel exists and is a split, otherwise zero"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_close", &func)){ + doc_function_brief(arena, &func, "Close a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to close"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "When the view is closed, it's associated panel is also closed and the layout is adjusted to compensate, possibly changing the associations of of panels and views."); + } + + //////////////////////////////// + + // TODO(allen): get rid of view_get_buffer_region + if (begin_doc_call(arena, cluster, api_def, "view_get_buffer_region", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + // TODO(allen): get rid of view_get_buffer_region + if (begin_doc_call(arena, cluster, api_def, "view_get_buffer_scroll", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_set_active", &func)){ + doc_function_brief(arena, &func, "Set the active view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to set as active"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_enqueue_command_function", &func)){ + doc_function_brief(arena, &func, "Push an command to the core to be processed in the context of a particular view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view who's context thread will be sent the command"); + + doc_function_param(arena, &func, "custom_func"); + doc_text(arena, params, "the function pointer to the command to be processed by the view"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Directly enqueued commands are triggered in the order they were enqueued before any additional events, virtual o real, are processed, and before the current frame renders."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_setting", &func)){ + doc_function_brief(arena, &func, "Retrieve a core setting of a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + doc_function_param(arena, &func, "setting"); + doc_text(arena, params, "the id of the setting to query"); + + doc_function_param(arena, &func, "value_out"); + doc_text(arena, params, "the output destination of the setting's value"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the view and setting exist, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "View_Setting_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_set_setting", &func)){ + doc_function_brief(arena, &func, "Retrieve a core setting of a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "setting"); + doc_text(arena, params, "the id of the setting to modify"); + + doc_function_param(arena, &func, "value"); + doc_text(arena, params, "the new value of the specified setting"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the view and setting exist, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "View_Setting_ID"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_get_managed_scope", &func)){ + doc_function_brief(arena, &func, "Retrieve the managed scope tied to the lifetime of a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the id of the managed scope tied to the view on success, when the view exists, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Managed_Scope"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_compute_cursor", &func)){ + doc_function_brief(arena, &func, "Compute a view cursor from a view and a seek target"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + doc_function_param(arena, &func, "seek"); + doc_text(arena, params, "the seek target to use in a query for full cursor information"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the full cursor information for the position specified by the seek, if the view exists, otherwise cleared to zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Equivalent to calling the buffer related function with the same name using view to derive the buffer parameter."); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Seek"); + doc_function_add_related(arena, rel, "Buffer_Cursor"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_set_cursor", &func)){ + doc_function_brief(arena, &func, "Set a view's internal cursor position"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "seek"); + doc_text(arena, params, "the seek target to use to derive the new position"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Seek"); + } + + //////////////////////////////// + + // TODO(allen): remove view_set_buffer_scroll + if (begin_doc_call(arena, cluster, api_def, "view_set_buffer_scroll", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_set_mark", &func)){ + doc_function_brief(arena, &func, "Set a view's internal mark position"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "seek"); + doc_text(arena, params, "the seek target to use to derive the new position"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Buffer_Seek"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_quit_ui", &func)){ + doc_function_brief(arena, &func, "Try to force a view to exit a UI loop and return to the default buffer display behavior"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "A view is considered to be in a UI loop when it's context details have set their 'hides_buffer' field to true. This call attemps to get the view to a state with this field set to false by sending abort events repeatedly. This can fail due to buggy or non-compliant implementations of views. It can either fail because the UI loop refuses to respond to the abort after repeated attempts to close it, or because the view shuts down completely rather than returning to a buffer viewing state. The core ensures that if this happens to the final view, a new root panel and empty view will be initialized."); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_set_buffer", &func)){ + doc_function_brief(arena, &func, "Set a view's associated buffer"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "buffer_id"); + doc_text(arena, params, "the id of the buffer to associate to this view"); + + doc_function_param(arena, &func, "flags"); + doc_text(arena, params, "flags controlling the behavior of the view as it changes to the new buffer"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view and buffer both exist, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "Set_Buffer_Flag"); + } + + //////////////////////////////// + + // TODO(allen): remove view_post_fade + if (begin_doc_call(arena, cluster, api_def, "view_post_fade", &func)){ + doc_function_brief(arena, &func, "Plans to deprecate - do not rely on this call!"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_push_context", &func)){ + doc_function_brief(arena, &func, "Push a view's stack of context details with a pointer to the new values for the context"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "ctx"); + doc_text(arena, params, "the new field values of the view context details to be copied onto the top of the stack"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, otherwise zero"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "View_Context"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_pop_context", &func)){ + doc_function_brief(arena, &func, "Pop a view's stack of context details"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero on success, when the view exists and the details stack has more than one entry, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "View_Context"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_alter_context", &func)){ + doc_function_brief(arena, &func, "Modify the context details at the top of a view's context details stack"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to modify"); + + doc_function_param(arena, &func, "ctx"); + doc_text(arena, params, "the new field values of the view context details to be copied onto the top of the stack"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "non-zero if the view exists, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "View_Context"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_current_context", &func)){ + doc_function_brief(arena, &func, "Get the current context details at the top of a view's context details stack"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of thew view to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "a copy of the context details for the given view if it exists, zero otherwise"); + + // related + Doc_Block *rel = doc_function_begin_related(arena, &func); + doc_function_add_related(arena, rel, "View_Context"); + } + + //////////////////////////////// + + if (begin_doc_call(arena, cluster, api_def, "view_current_context_hook_memory", &func)){ + doc_function_brief(arena, &func, "Get the memory allocated for a specific hook tied to the current details context of a view"); + + // params + Doc_Block *params = doc_function_begin_params(arena, &func); + doc_custom_app_ptr(arena, &func); + + doc_function_param(arena, &func, "view_id"); + doc_text(arena, params, "the id of the view to query"); + + doc_function_param(arena, &func, "hook_id"); + doc_text(arena, params, "the id of the hook to query"); + + // return + Doc_Block *ret = doc_function_return(arena, &func); + doc_text(arena, ret, "the data struct pointing to the memory set aside for the context on success, when the view and hook exit and have associated memory for the hook, otherwise cleared to zero"); + + // details + Doc_Block *det = doc_function_details(arena, &func); + doc_text(arena, det, "Some hooks controlled by the view context details stack have their own requirements for unique, stable, context memory, which needs a variable sized allocation. The size of the memory available to such hooks is determined by the context details, and each instance of the context on the stack gets it's own allocation for these hooks. For example, smooth scrolling rules often require some state that wants to be locally tied to the scrolling for a particular UI loop."); + } +} + +// BOTTOM + diff --git a/project.4coder b/project.4coder index a60f2f9f..c9cea3ad 100644 --- a/project.4coder +++ b/project.4coder @@ -43,6 +43,10 @@ command_list = { .out = "*run*", .footer_panel = false, .save_dirty_files = false, .cmd = { { "pushd ..\\build & one_time", .os = "win" }, }, }, + { .name = "build custom api docs", + .out = "*compilation*", .footer_panel = true, .save_dirty_files = true, + .cmd = { { "custom\\bin\\build_one_time docs\\4ed_doc_custom_api.cpp ..\\build", .os = "win" }, }, }, + { .name = "build C++ lexer generator", .out = "*compilation*", .footer_panel = true, .save_dirty_files = true, .cmd = { { "custom\\bin\\build_one_time custom\\languages\\4coder_cpp_lexer_gen.cpp ..\\build", .os = "win" }, }, }, @@ -81,7 +85,7 @@ command_list = { }; fkey_command[1] = "build x64"; -fkey_command[2] = "build keycode generator"; +fkey_command[2] = "build custom api docs"; fkey_command[4] = "run one time"; fkey_command[5] = "build C++ lexer generator"; fkey_command[6] = "build token tester";