> home

Custom Layer Boundary API Index

  • alloc_buffer_markers_on_buffer
  • alloc_managed_memory_in_scope
  • animate_in_n_milliseconds
  • buffer_batch_edit
  • buffer_clear_layout_cache
  • buffer_compute_cursor
  • buffer_exists
  • buffer_find_all_matches
  • buffer_get_access_flags
  • buffer_get_attached_child_process
  • buffer_get_dirty_state
  • buffer_get_file_attributes
  • buffer_get_layout
  • buffer_get_line_count
  • buffer_get_managed_scope
  • buffer_get_setting
  • buffer_get_size
  • buffer_history_clear_after_current_state
  • buffer_history_get_current_state_index
  • buffer_history_get_group_sub_record
  • buffer_history_get_max_record_index
  • buffer_history_get_record_info
  • buffer_history_merge_record_range
  • buffer_history_set_current_state_index
  • buffer_kill
  • buffer_line_shift_y
  • buffer_line_y_difference
  • buffer_padded_box_of_pos
  • buffer_pos_at_relative_xy
  • buffer_pos_from_relative_character
  • buffer_read_range
  • buffer_relative_box_of_pos
  • buffer_relative_character_from_pos
  • buffer_reopen
  • buffer_replace_range
  • buffer_save
  • buffer_seek_character_class
  • buffer_seek_string
  • buffer_send_end_signal
  • buffer_set_dirty_state
  • buffer_set_face
  • buffer_set_layout
  • buffer_set_setting
  • child_process_get_attached_buffer
  • child_process_get_state
  • child_process_set_target_buffer
  • clear_all_query_bars
  • create_buffer
  • create_child_process
  • create_user_managed_scope
  • destroy_user_managed_scope
  • draw_rectangle
  • draw_rectangle_outline
  • draw_set_clip
  • draw_string_oriented
  • draw_text_layout
  • end_query_bar
  • enqueue_virtual_event
  • get_active_query_bars
  • get_active_view
  • get_buffer_by_file_name
  • get_buffer_by_name
  • get_buffer_count
  • get_buffer_next
  • get_core_profile_list
  • get_current_input
  • get_current_input_sequence_number
  • get_custom_hook
  • get_custom_layer_boundary_docs
  • get_face_advance_map
  • get_face_description
  • get_face_id
  • get_face_metrics
  • get_global_managed_scope
  • get_largest_face_id
  • get_managed_scope_with_multiple_dependencies
  • get_mouse_state
  • get_string_advance
  • get_this_ctx_view
  • get_thread_context
  • get_view_next
  • get_view_prev
  • global_get_screen_rectangle
  • global_history_edit_group_begin
  • global_history_edit_group_end
  • global_set_setting
  • hard_exit
  • leave_current_input_unhandled
  • log_string
  • managed_id_declare
  • managed_id_get
  • managed_id_group_highest_id
  • managed_object_free
  • managed_object_get_containing_scope
  • managed_object_get_item_count
  • managed_object_get_item_size
  • managed_object_get_pointer
  • managed_object_get_type
  • managed_object_load_data
  • managed_object_store_data
  • managed_scope_allocator
  • managed_scope_attachment_erase
  • managed_scope_clear_contents
  • managed_scope_clear_self_all_dependent_scopes
  • managed_scope_get_attachment
  • open_color_picker
  • paint_text_color
  • panel_get_child
  • panel_get_parent
  • panel_get_root
  • panel_get_view
  • panel_is_leaf
  • panel_is_split
  • panel_set_split
  • panel_split
  • panel_swap_children
  • print_message
  • push_buffer_base_name
  • push_buffer_file_name
  • push_buffer_unique_name
  • push_hot_directory
  • send_exit_signal
  • set_current_input
  • set_custom_hook
  • set_custom_hook_memory_size
  • set_global_face
  • set_hot_directory
  • set_window_title
  • start_query_bar
  • text_layout_character_on_screen
  • text_layout_create
  • text_layout_free
  • text_layout_get_buffer
  • text_layout_get_visible_range
  • text_layout_line_on_screen
  • text_layout_region
  • try_create_new_face
  • try_modify_face
  • try_release_face
  • view_alter_context
  • view_close
  • view_compute_cursor
  • view_current_context
  • view_current_context_hook_memory
  • view_enqueue_command_function
  • view_exists
  • view_get_buffer
  • view_get_buffer_region
  • view_get_buffer_scroll
  • view_get_cursor_pos
  • view_get_managed_scope
  • view_get_mark_pos
  • view_get_panel
  • view_get_preferred_x
  • view_get_screen_rect
  • view_get_setting
  • view_line_shift_y
  • view_line_y_difference
  • view_padded_box_of_pos
  • view_pop_context
  • view_pos_at_relative_xy
  • view_pos_from_relative_character
  • view_push_context
  • view_quit_ui
  • view_relative_box_of_pos
  • view_relative_character_from_pos
  • view_set_active
  • view_set_buffer
  • view_set_buffer_scroll
  • view_set_cursor
  • view_set_mark
  • view_set_preferred_x
  • view_set_setting
> home > Custom Layer Boundary API

alloc_buffer_markers_on_buffer

September 8th 2024
Allocate buffer markers inside a managed scope and attach them to a buffer

Signature

C++
Managed_Object
alloc_buffer_markers_on_buffer(Application_Links* app,
                               Buffer_ID buffer_id,
                               i32 count,
                               Managed_Scope* optional_extra_scope);

Parameters

app

the standard custom layer context pointer

buffer_id

the buffer on which them markers will be attached

count

the number of markers to allocate

optional_extra_scope

either a null pointer, or a pointer to a managed scope

Return

on success, when the buffer exists, and the optional_extra_scope is valid, a new managed object id, otherwise zero

Details

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.
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

get_managed_scope_with_multiple_dependencies
Marker
Standalone Page
> home > Custom Layer Boundary API

alloc_managed_memory_in_scope

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
Managed_Object
alloc_managed_memory_in_scope(Application_Links* app,
                              Managed_Scope scope,
                              i32 item_size,
                              i32 count);
Standalone Page
> home > Custom Layer Boundary API

animate_in_n_milliseconds

September 8th 2024
Set a wakeup timer to run a 4coder update tick and render

Signature

C++
void
animate_in_n_milliseconds(Application_Links* app,
                          u32 n);

Parameters

app

the standard custom layer context pointer

n

the number of milliseconds roughly approximating how long to wait until sending a wakeup signal, the wakeup is always delayed by a minimum of a 16 milliseconds

Details

Without an animate timer set, 4coder only wakes up when events are sent to it. When there is an animation timer, 4coder wakes up when the animation timer triggers a timer event.
Standalone Page
> home > Custom Layer Boundary API

buffer_batch_edit

September 8th 2024
Replace a sorted sequence of ranges with specific strings

Signature

C++
b32
buffer_batch_edit(Application_Links* app,
                  Buffer_ID buffer_id,
                  Batch_Edit* batch);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

batch

the first batch edit in a linked list of edits to apply in one atomic modification

Return

non-zero on success, when the buffer exists and the batch is correctly sorted and contained within the buffer, zero otherwise

Details

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.
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

buffer_replace_range
Batch_Edit
Standalone Page
> home > Custom Layer Boundary API

buffer_clear_layout_cache

September 8th 2024
Clear all the layout information cached in the buffer

Signature

C++
b32
buffer_clear_layout_cache(Application_Links* app,
                          Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to be modified
Standalone Page
> home > Custom Layer Boundary API

buffer_compute_cursor

September 8th 2024
Compute a buffer cursor from a buffer and a seek target

Signature

C++
Buffer_Cursor
buffer_compute_cursor(Application_Links* app,
                      Buffer_ID buffer,
                      Buffer_Seek seek);

Parameters

app

the standard custom layer context pointer

buffer

the id of the buffer to query

seek

the seek target to use in a query for full cursor information

Return

the full cursor information for the position specified by the seek, if the buffer exists, otherwise cleared to zero

Related

Buffer_Seek
Buffer_Cursor
Standalone Page
> home > Custom Layer Boundary API

buffer_exists

September 8th 2024
Check that a buffer id represents a real buffer

Signature

C++
b32
buffer_exists(Application_Links* app,
              Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the buffer id to check

Return

non-zero if the buffer exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

buffer_find_all_matches

September 8th 2024
Find all matches for a search pattern in a buffer

Signature

C++
String_Match_List
buffer_find_all_matches(Application_Links* app,
                        Arena* arena,
                        Buffer_ID buffer,
                        i32 string_id,
                        Range_i64 range,
                        String_Const_u8 needle,
                        Character_Predicate* predicate,
                        Scan_Direction direction);

Parameters

app

the standard custom layer context pointer

arena

the arena on which the returned string will be allocated

buffer

the id of the buffer to search

string_id

the id to store into the resulting string matches

range

the range in byte positions where all matches must be contained

needle

the string to search for in the buffer range

predicate

a character predicate used to check the left and right side of the match to add left sloppy and right sloppy match flags.

direction

the direction of the scan through the buffer range determining the order of the generated matches

Return

a linked list of matches to the search pattern
Standalone Page
> home > Custom Layer Boundary API

buffer_get_access_flags

September 8th 2024
Retrieve the access flags of a buffer

Signature

C++
Access_Flag
buffer_get_access_flags(Application_Links* app,
                        Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

the access flag fied of the buffer on success, when the buffer exists, otherwise zero

Related

Access_Flag
Standalone Page
> home > Custom Layer Boundary API

buffer_get_attached_child_process

September 8th 2024
Retrieve the child process linked to a buffer

Signature

C++
Child_Process_ID
buffer_get_attached_child_process(Application_Links* app,
                                  Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer

Return

if the given buffer exists and has an attached child process it's id is returned, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_get_dirty_state

September 8th 2024
Retrieve the dirty state flags of a buffer

Signature

C++
Dirty_State
buffer_get_dirty_state(Application_Links* app,
                       Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

the dirty state flags of the buffer on success, when it exists, otherwise zero

Related

Dirty_State
Standalone Page
> home > Custom Layer Boundary API

buffer_get_file_attributes

September 8th 2024
Get file attributes of a buffer

Signature

C++
File_Attributes
buffer_get_file_attributes(Application_Links* app,
                           Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

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

File_Attributes
Standalone Page
> home > Custom Layer Boundary API

buffer_get_layout

September 8th 2024
Retrieve the layout rule of a buffer

Signature

C++
Layout_Function*
buffer_get_layout(Application_Links* app,
                  Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

a pointer to the function specifying the buffer's layout rule on success, when the buffer exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

buffer_get_line_count

September 8th 2024
Retrieve the line count of a buffer

Signature

C++
i64
buffer_get_line_count(Application_Links* app,
                      Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

the number of lines in the buffer on success, when the buffer exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_get_managed_scope

September 8th 2024
Retrieve the managed scope tied to the lifetime of a buffer

Signature

C++
Managed_Scope
buffer_get_managed_scope(Application_Links* app,
                         Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

the id of the managed scope tied to the buffer on success, when the buffer exists, zero otherwise

Related

Managed_Scope
Standalone Page
> home > Custom Layer Boundary API

buffer_get_setting

September 8th 2024
Retrieve a core setting of a buffer

Signature

C++
b32
buffer_get_setting(Application_Links* app,
                   Buffer_ID buffer_id,
                   Buffer_Setting_ID setting,
                   i64* value_out);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

setting

the id of the setting to query

value_out

the output destination of the setting's value

Return

non-zero on success, when the buffer and setting exist, zero otherwise

Related

Buffer_Setting_ID
Standalone Page
> home > Custom Layer Boundary API

buffer_get_size

September 8th 2024
Retrieve the size of a buffer in bytes

Signature

C++
i64
buffer_get_size(Application_Links* app,
                Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

the size in bytes of the buffer on success, when the buffer exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_history_clear_after_current_state

September 8th 2024
Forget the portion of the buffer history on the redo side

Signature

C++
b32
buffer_history_clear_after_current_state(Application_Links* app,
                                         Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

Return

non-zero on success, when the buffer exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_history_get_current_state_index

September 8th 2024
Get the current state index of the history

Signature

C++
History_Record_Index
buffer_history_get_current_state_index(Application_Links* app,
                                       Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

if the buffer exists and has history enabled, the current state index, otherwise zero

Details

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.
Standalone Page
> home > Custom Layer Boundary API

buffer_history_get_group_sub_record

September 8th 2024
Get a sub-record of a group record from a buffer history

Signature

C++
Record_Info
buffer_history_get_group_sub_record(Application_Links* app,
                                    Buffer_ID buffer_id,
                                    History_Record_Index index,
                                    i32 sub_index);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

index

the index of the record to query

sub_index

the sub-index of the record to query

Return

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

Record_Info
Standalone Page
> home > Custom Layer Boundary API

buffer_history_get_max_record_index

September 8th 2024
Get the largest record index in the buffer history

Signature

C++
History_Record_Index
buffer_history_get_max_record_index(Application_Links* app,
                                    Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

Return

if the buffer exists and has history enabled, the maximum index of the records in the history, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_history_get_record_info

September 8th 2024
Get record information out of a buffer's history

Signature

C++
Record_Info
buffer_history_get_record_info(Application_Links* app,
                               Buffer_ID buffer_id,
                               History_Record_Index index);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query

index

the index of the record to query

Return

on success, when the buffer exists and index is within the history index range, the record information at the given index, otherwise zero

Related

Record_Info
Standalone Page
> home > Custom Layer Boundary API

buffer_history_merge_record_range

September 8th 2024
Merge a range of records into a single group record

Signature

C++
b32
buffer_history_merge_record_range(Application_Links* app,
                                  Buffer_ID buffer_id,
                                  History_Record_Index first_index,
                                  History_Record_Index last_index,
                                  Record_Merge_Flag flags);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

first_index

the first index in the range to merge

last_index

the last index in the range to merge, forming an inclusive-inclusive range

flags

flags controlling the behavior of the operation

Return

non-zero on success, when the buffer exists, and the index range is contained within the buffer history, otherwise zero

Details

Group records contain all the same information that the range of individual records previously contained. A group is treated as a single unit in undo-redo operations.
Standalone Page
> home > Custom Layer Boundary API

buffer_history_set_current_state_index

September 8th 2024
Modify the current state index and update the buffer contents to reflect the contents of the buffer as it was at that index.

Signature

C++
b32
buffer_history_set_current_state_index(Application_Links* app,
                                       Buffer_ID buffer_id,
                                       History_Record_Index index);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

index

the new current state index value

Return

non-zero if the buffer exists, has history enabled, and contains a record at the given index, otherwise zero

Details

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.
Standalone Page
> home > Custom Layer Boundary API

buffer_kill

September 8th 2024
Close a buffer

Signature

C++
Buffer_Kill_Result
buffer_kill(Application_Links* app,
            Buffer_ID buffer_id,
            Buffer_Kill_Flag flags);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to close

flags

flags controlling the buffer closing behavior

Return

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

When a buffer's dirty state includes unsaved changes, this call will not close the buffer unless it is forced to by the flags.
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

Buffer_Kill_Result
Buffer_Kill_Flag
Standalone Page
> home > Custom Layer Boundary API

buffer_line_shift_y

September 8th 2024
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

Signature

C++
Line_Shift_Vertical
buffer_line_shift_y(Application_Links* app,
                    Buffer_ID buffer_id,
                    f32 width,
                    Face_ID face_id,
                    i64 line,
                    f32 y_shift);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

line

the line number of the line that serves as the relative starting point of the measurement

y_shift

the y shift, in pixels, from the top of the specified line to be measured

Return

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

Line numbers are 1 based.

Related

Line_Shift_Vertical
Standalone Page
> home > Custom Layer Boundary API

buffer_line_y_difference

September 8th 2024
Compute the signed vertical pixel distance between the top of two lines

Signature

C++
f32
buffer_line_y_difference(Application_Links* app,
                         Buffer_ID buffer_id,
                         f32 width,
                         Face_ID face_id,
                         i64 line_a,
                         i64 line_b);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

line_a

the line number of the line 'A' in the subtraction top(A) - top(B)

line_b

the line number of the line 'B' in the subtraction top(A) - top(B)

Return

the signed distance between the lines in pixels on success, when the buffer exists and contains both given line numbers

Details

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

buffer_padded_box_of_pos

September 8th 2024
Compute the rectangle around a character at a particular byte position, relative to the top left corner of a given line

Signature

C++
Rect_f32
buffer_padded_box_of_pos(Application_Links* app,
                         Buffer_ID buffer_id,
                         f32 width,
                         Face_ID face_id,
                         i64 base_line,
                         i64 pos);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

base_line

the line number of the line that serves as the relative starting point of the measurement

pos

the absolute byte index of the position to query

Return

the rectangle around 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

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

buffer_pos_at_relative_xy

September 8th 2024
Compute a byte position at a particular point relative to the top left corner of a particular line

Signature

C++
i64
buffer_pos_at_relative_xy(Application_Links* app,
                          Buffer_ID buffer_id,
                          f32 width,
                          Face_ID face_id,
                          i64 base_line,
                          Vec2_f32 relative_xy);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

base_line

the line number of the line that serves as the relative starting point of the measurement

relative_xy

the point, in pixels, interpreted relative to the line's top left corner, that will serve as the query point

Return

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

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

buffer_pos_from_relative_character

September 8th 2024
Compute the byte position associated with the start of a particular character specified relative to the first character of a particular line

Signature

C++
i64
buffer_pos_from_relative_character(Application_Links* app,
                                   Buffer_ID buffer_id,
                                   f32 width,
                                   Face_ID face_id,
                                   i64 base_line,
                                   i64 relative_character);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

base_line

the line number of the line that serves as the relative starting point of the measurement

relative_character

the relative character index of the query character, based at the first character of base line

Return

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

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

buffer_read_range

September 8th 2024
Read a range of text out of a buffer

Signature

C++
b32
buffer_read_range(Application_Links* app,
                  Buffer_ID buffer_id,
                  Range_i64 range,
                  u8* out);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to be read

range

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.

out

the buffer that will get the copy of the new text which should have at least range.max - range.min available bytes

Return

non-zero on success, when the buffer exists and the range is completely contained within the buffer's contents, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_relative_box_of_pos

September 8th 2024
Compute the box of a character that spans a particular byte position, relative to the top left corner of a given line

Signature

C++
Rect_f32
buffer_relative_box_of_pos(Application_Links* app,
                           Buffer_ID buffer_id,
                           f32 width,
                           Face_ID face_id,
                           i64 base_line,
                           i64 pos);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

base_line

the line number of the line that serves as the relative starting point of the measurement

pos

the absolute byte index of the position to query

Return

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

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

buffer_relative_character_from_pos

September 8th 2024
Compute a character index relative to a particular lines first character

Signature

C++
i64
buffer_relative_character_from_pos(Application_Links* app,
                                   Buffer_ID buffer_id,
                                   f32 width,
                                   Face_ID face_id,
                                   i64 base_line,
                                   i64 pos);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's layout will be measured

width

the width parameter of the layout, passed to layout rules as a recommended wrap point

face_id

the face parameter of the layout, passed to layout rules as a recommended face

base_line

the line number of the line that serves as the relative starting point of the measurement

pos

the absolute byte index of the position to query

Return

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

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

buffer_reopen

September 8th 2024
Reload the content of a buffer from the the attached file

Signature

C++
Buffer_Reopen_Result
buffer_reopen(Application_Links* app,
              Buffer_ID buffer_id,
              Buffer_Reopen_Flag flags);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to reload

flags

flags controlling the behavior of the reload

Return

non-zero if the buffer exists and has an attached file that can be read, zero otherwise

Related

Buffer_Reopen_Flag
Standalone Page
> home > Custom Layer Boundary API

buffer_replace_range

September 8th 2024
Replace a range of text with a specific string

Signature

C++
b32
buffer_replace_range(Application_Links* app,
                     Buffer_ID buffer_id,
                     Range_i64 range,
                     String_Const_u8 string);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

range

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

string

the new text to be placed in the given range

Return

non-zero on success, when the buffer eixsts and the range is contained within the buffer, zero otherwise

Details

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.
All modifications made by this call are simultaneously saved onto the buffer's history if is enabled.
Standalone Page
> home > Custom Layer Boundary API

buffer_save

September 8th 2024
Save the contents of a buffer to a file

Signature

C++
b32
buffer_save(Application_Links* app,
            Buffer_ID buffer_id,
            String_Const_u8 file_name,
            Buffer_Save_Flag flags);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer who's contents to write to disk

file_name

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

flags

flags controlling the behavior of the save

Return

non-zero when the buffer exists and the file was successfully written, zero otherwise

Related

Buffer_Save_Flag
Standalone Page
> home > Custom Layer Boundary API

buffer_seek_character_class

September 8th 2024
Scan a buffer from a point to the first character in a specified set of characters

Signature

C++
String_Match
buffer_seek_character_class(Application_Links* app,
                            Buffer_ID buffer,
                            Character_Predicate* predicate,
                            Scan_Direction direction,
                            i64 start_pos);

Parameters

app

the standard custom layer context pointer

buffer

the id of the buffer who's contents to seek

predicate

specifies the set of bytes that will end the scan

direction

the scan direction of the scan from the start point

start_pos

the start point of the scan

Return

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

Character_Predicate
String_Match
Standalone Page
> home > Custom Layer Boundary API

buffer_seek_string

September 8th 2024
Scan a buffer from a point to the first occurence of a string

Signature

C++
String_Match
buffer_seek_string(Application_Links* app,
                   Buffer_ID buffer,
                   String_Const_u8 needle,
                   Scan_Direction direction,
                   i64 start_pos);

Parameters

app

the standard custom layer context pointer

buffer

the id of the buffer who's contents to seek

needle

the string to match against the contents of the buffer

direction

the scan direction of the scan from the start point

start_pos

the start point of the scan

Return

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
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.
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.

Details

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.

Related

Scan_Direction
String_Match
Standalone Page
> home > Custom Layer Boundary API

buffer_send_end_signal

September 8th 2024
Cause the buffer to reset it's lifetime

Signature

C++
b32
buffer_send_end_signal(Application_Links* app,
                       Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to receive the signal

Return

non-zero on success, when the buffer exists, zero otherwise

Details

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.
Standalone Page
> home > Custom Layer Boundary API

buffer_set_dirty_state

September 8th 2024
Set the dirty state of a buffer

Signature

C++
b32
buffer_set_dirty_state(Application_Links* app,
                       Buffer_ID buffer_id,
                       Dirty_State dirty_state);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to be modified

dirty_state

the new value for the buffer's dirty state

Return

non-zero on success, when the buffer exists, otherwise zero

Related

Dirty_State
Standalone Page
> home > Custom Layer Boundary API

buffer_set_face

September 8th 2024
Change the face of a buffer

Signature

C++
b32
buffer_set_face(Application_Links* app,
                Buffer_ID buffer_id,
                Face_ID id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

id

the id of the face to set on the buffer

Return

non-zero on success, when the buffer and face exist, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_set_layout

September 8th 2024
Set the layout function of a buffer

Signature

C++
b32
buffer_set_layout(Application_Links* app,
                  Buffer_ID buffer_id,
                  Layout_Function* layout_func);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to be modified

layout_func

the new layout function for the buffer's layout

Return

non-zero on success, when the buffer exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

buffer_set_setting

September 8th 2024
Retrieve a core setting of a buffer

Signature

C++
b32
buffer_set_setting(Application_Links* app,
                   Buffer_ID buffer_id,
                   Buffer_Setting_ID setting,
                   i64 value);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to modify

setting

the id of the setting to modify

value

the new value of the specified setting

Return

non-zero on success, when the buffer and setting exist, zero otherwise

Related

Buffer_Setting_ID
Standalone Page
> home > Custom Layer Boundary API

child_process_get_attached_buffer

September 8th 2024
Retrieve the buffer linked to a child process

Signature

C++
Buffer_ID
child_process_get_attached_buffer(Application_Links* app,
                                  Child_Process_ID child_process_id);

Parameters

app

the standard custom layer context pointer

child_process_id

the id of the child process

Return

if the given child process exists and has an attached buffer it's id is returned, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

child_process_get_state

September 8th 2024
Get the state of a child process

Signature

C++
Process_State
child_process_get_state(Application_Links* app,
                        Child_Process_ID child_process_id);

Parameters

app

the standard custom layer context pointer

child_process_id

the id of the child process

Return

the state fields of the child process

Related

Process_State
Standalone Page
> home > Custom Layer Boundary API

child_process_set_target_buffer

September 8th 2024
Create a link between a child process and a buffer, so that output from the child process is written to the buffer

Signature

C++
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);

Parameters

app

the standard custom layer context pointer

child_process_id

the id of the child process who's output will be linked

buffer_id

the id of the buffer that will receive the output

flags

flags setting the behavior when the child process or buffer already have a link

Return

on success when the two entities exist and the link is created non-zero, otherwise zero

Details

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

Child_Process_Set_Target_Flags
Standalone Page
> home > Custom Layer Boundary API

clear_all_query_bars

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
void
clear_all_query_bars(Application_Links* app,
                     View_ID view_id);
Standalone Page
> home > Custom Layer Boundary API

create_buffer

September 8th 2024
Create a new buffer

Signature

C++
Buffer_ID
create_buffer(Application_Links* app,
              String_Const_u8 file_name,
              Buffer_Create_Flag flags);

Parameters

app

the standard custom layer context pointer

file_name

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

flags

flags controlling behavior of the buffer creation

Return

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

Buffer_Create_Flag
Standalone Page
> home > Custom Layer Boundary API

create_child_process

September 8th 2024
Create a child process of the 4coder process

Signature

C++
Child_Process_ID
create_child_process(Application_Links* app,
                     String_Const_u8 path,
                     String_Const_u8 command);

Parameters

app

the standard custom layer context pointer

path

the active path set for the new child process

command

the command that defines the action of the child process - this string is passed to the OS's default command line handler

Return

on success a non-zero id for the new child process which is unique across the entire 4coder session, zero on failure
Standalone Page
> home > Custom Layer Boundary API

create_user_managed_scope

September 8th 2024
Create a managed scope that is not tied to anything in the core and that the user can destroy

Signature

C++
Managed_Scope
create_user_managed_scope(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the new managed scope's id
Standalone Page
> home > Custom Layer Boundary API

destroy_user_managed_scope

September 8th 2024
Destroy a managed scope that was previously created by the user

Signature

C++
b32
destroy_user_managed_scope(Application_Links* app,
                           Managed_Scope scope);

Parameters

app

the standard custom layer context pointer

scope

the id of the managed scope to destroy

Return

non-zero if the scope exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

draw_rectangle

September 8th 2024
Directly render a rectangle

Signature

C++
void
draw_rectangle(Application_Links* app,
               Rect_f32 rect,
               f32 roundness,
               ARGB_Color color);

Parameters

app

the standard custom layer context pointer

rect

the rectangle coordinates, in pixels relative to the top left corner of the screen

roundness

the roundness of the pixels, set as a radius of a circular curve measured in pixels

color

the color of the rectangle

Details

As a render function, this only takes effect during a call to the render hook.
Standalone Page
> home > Custom Layer Boundary API

draw_rectangle_outline

September 8th 2024
Directly render a rectangle outline

Signature

C++
void
draw_rectangle_outline(Application_Links* app,
                       Rect_f32 rect,
                       f32 roundness,
                       f32 thickness,
                       ARGB_Color color);

Parameters

app

the standard custom layer context pointer

rect

the rectangle coordinates, in pixels relative to the top left corner of the screen

roundness

the roundness of the pixels, set as a radius of a circular curve measured in pixels

thickness

the thickness, in pixels, of the rectangle outline

color

the color of the rectangle

Details

As a render function, this only takes effect during a call to the render hook.
Standalone Page
> home > Custom Layer Boundary API

draw_set_clip

September 8th 2024
Set the clip rectangle for future render functions

Signature

C++
Rect_f32
draw_set_clip(Application_Links* app,
              Rect_f32 new_clip);

Parameters

app

the standard custom layer context pointer

new_clip

the new rectangular coordinates of the clip rectangle, in pixels relative to the top left corner of the screen

Return

the previous value of clip rectangle

Details

As a render function, this only takes effect during a call to the render hook.
Standalone Page
> home > Custom Layer Boundary API

draw_string_oriented

September 8th 2024
Directly render text

Signature

C++
Vec2_f32
draw_string_oriented(Application_Links* app,
                     Face_ID font_id,
                     ARGB_Color color,
                     String_Const_u8 str,
                     Vec2_f32 point,
                     u32 flags,
                     Vec2_f32 delta);

Parameters

app

the standard custom layer context pointer

font_id

the id of the face to use rendering the text

color

the color of the text

str

the text to be rendered

point

the position of the text, in pixels relative to the screen's top left corner

flags

flags determining the orientation of the string to render

delta

a unit vector specifying the direction along which the text advances

Return

the new point after advancing the point while laying out the text

Details

As a render function, this only takes effect during a call to the render hook.
Standalone Page
> home > Custom Layer Boundary API

draw_text_layout

September 8th 2024
Directly render a text layout object

Signature

C++
void
draw_text_layout(Application_Links* app,
                 Text_Layout_ID layout_id,
                 ARGB_Color special_color,
                 ARGB_Color ghost_color);

Parameters

app

the standard custom layer context pointer

layout_id

the id of the text layout object

special_color

the color to use for characters with the special character flag

ghost_color

the color to use for characters with the ghost character flag
Standalone Page
> home > Custom Layer Boundary API

end_query_bar

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
void
end_query_bar(Application_Links* app,
              Query_Bar* bar,
              u32 flags);
Standalone Page
> home > Custom Layer Boundary API

enqueue_virtual_event

September 8th 2024
Push an event to the core to be processed as if it were a real event

Signature

C++
b32
enqueue_virtual_event(Application_Links* app,
                      Input_Event* event);

Parameters

app

the standard custom layer context pointer

event

a pointer to an event struct that contains the information that will be in the virtual event

Return

on success, when the event specified is validly formed, non-zero is returned, otherwise zero is returned

Details

All virtual events are triggered after all directly enqueued commands, before the next real event, and before the current frame renders.
Standalone Page
> home > Custom Layer Boundary API

get_active_query_bars

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
b32
get_active_query_bars(Application_Links* app,
                      View_ID view_id,
                      i32 max_result_count,
                      Query_Bar_Ptr_Array* array_out);
Standalone Page
> home > Custom Layer Boundary API

get_active_view

September 8th 2024
Get the id of the active view

Signature

C++
View_ID
get_active_view(Application_Links* app,
                Access_Flag access);

Parameters

app

the standard custom layer context pointer

access

the type of access requirements that the view must satisfy

Return

the id of the active view, if it can satisfy the access requirements, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

get_buffer_by_file_name

September 8th 2024
Retrieve a buffer querying by file name

Signature

C++
Buffer_ID
get_buffer_by_file_name(Application_Links* app,
                        String_Const_u8 file_name,
                        Access_Flag access);

Parameters

app

the standard custom layer context pointer

file_name

the name to query against buffer file names

access

the type of access requirements used to determine whether or not to return a match

Return

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
Standalone Page
> home > Custom Layer Boundary API

get_buffer_by_name

September 8th 2024
Retrieve a buffer querying by name

Signature

C++
Buffer_ID
get_buffer_by_name(Application_Links* app,
                   String_Const_u8 name,
                   Access_Flag access);

Parameters

app

the standard custom layer context pointer

name

the name to query against buffer names

access

the type of access requirements used to determine whether or not to return a match

Return

the id of the buffer who's name agrees with name if it exists and it has the required access state, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

get_buffer_count

September 8th 2024
Retrieve the number of buffers loaded in the core

Signature

C++
i32
get_buffer_count(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the number of buffers loaded in the core
Standalone Page
> home > Custom Layer Boundary API

get_buffer_next

September 8th 2024
Iterate to the next buffer loaded in the core

Signature

C++
Buffer_ID
get_buffer_next(Application_Links* app,
                Buffer_ID buffer_id,
                Access_Flag access);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to iterate from, or zero to get the first buffer

access

the type of access requirements used to filter on the buffers that are returned

Return

the id of the next buffer, or zero if there is no next buffer
Standalone Page
> home > Custom Layer Boundary API

get_core_profile_list

September 8th 2024
Potentially going to be deprecated - do not rely on this call!

Signature

C++
Profile_Global_List*
get_core_profile_list(Application_Links* app);
Standalone Page
> home > Custom Layer Boundary API

get_current_input

September 8th 2024
In a view context, get the input that has been most recently sent to the view

Signature

C++
User_Input
get_current_input(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

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

get_next_input
Standalone Page
> home > Custom Layer Boundary API

get_current_input_sequence_number

September 8th 2024
In a view context, get the sequence number for the input that has been most recently sent to the view

Signature

C++
i64
get_current_input_sequence_number(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the sequence number of the most recent input sent to the view, or zero if this is not a view context thread

Related

get_next_input
Standalone Page
> home > Custom Layer Boundary API

get_custom_hook

September 8th 2024
Get back a global hook binding

Signature

C++
Void_Func*
get_custom_hook(Application_Links* app,
                Hook_ID hook_id);

Parameters

app

the standard custom layer context pointer

hook_id

the id of the hook to be modified

Return

when the hook id is valid the function pointer to the current hook function, otherwise zero

Related

Hook_ID
Standalone Page
> home > Custom Layer Boundary API

get_custom_layer_boundary_docs

September 8th 2024
Construct the documentation content for the custom layer boundary API

Signature

C++
Doc_Cluster*
get_custom_layer_boundary_docs(Application_Links* app,
                               Arena* arena);

Parameters

app

the standard custom layer context pointer

arena

the arena on which the documentation content will be allocated

Return

a pointer to the newly constructed documentation content
Standalone Page
> home > Custom Layer Boundary API

get_face_advance_map

September 8th 2024
Get the advance map of a face

Signature

C++
Face_Advance_Map
get_face_advance_map(Application_Links* app,
                     Face_ID face_id);

Parameters

app

the standard custom layer context pointer

face_id

the id of the face to query

Return

the advance map of the given face on success, when the face exists, otherwise cleared to zero

Related

Face_Advance_Map
Standalone Page
> home > Custom Layer Boundary API

get_face_description

September 8th 2024
Get the description of a face

Signature

C++
Face_Description
get_face_description(Application_Links* app,
                     Face_ID face_id);

Parameters

app

the standard custom layer context pointer

face_id

the id of the face to query

Return

the description of the given face on success, when the face exists, otherwise cleared to zero

Details

A face description contains the parameters to initializing a face.

Related

Face_Description
Standalone Page
> home > Custom Layer Boundary API

get_face_id

September 8th 2024
Get the id of a face attached to a buffer, or of the global face

Signature

C++
Face_ID
get_face_id(Application_Links* app,
            Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to query, or zero to query for the global face

Return

the id of the queried face, if the buffer exists or if the query is for the global face, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

get_face_metrics

September 8th 2024
Get the metrics of a face

Signature

C++
Face_Metrics
get_face_metrics(Application_Links* app,
                 Face_ID face_id);

Parameters

app

the standard custom layer context pointer

face_id

the id of the face to query

Return

the metrics of the given face on success, when the face exists, otherwise cleared to zero

Related

Face_Metrics
Standalone Page
> home > Custom Layer Boundary API

get_global_managed_scope

September 8th 2024
Get the id of the 'global' managed scope

Signature

C++
Managed_Scope
get_global_managed_scope(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the id of the global managed scope

Details

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.
Standalone Page
> home > Custom Layer Boundary API

get_largest_face_id

September 8th 2024
Get the largest face id that is currently assigned to a face

Signature

C++
Face_ID
get_largest_face_id(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the largest face id that is currently assigned to a face
Standalone Page
> home > Custom Layer Boundary API

get_managed_scope_with_multiple_dependencies

September 8th 2024
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

Signature

C++
Managed_Scope
get_managed_scope_with_multiple_dependencies(Application_Links* app,
                                             Managed_Scope* scopes,
                                             i32 count);

Parameters

app

the standard custom layer context pointer

scopes

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

count

the number of scope ids in the scopes array

Return

the scope id of the scope with multiple dependencies on success, when all the scopes in input array exist, zero otherwise

Details

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:
1. When there is only one scope in the parameters, that scope is the result. {A} -> A;
2. When there are two or more parameters that are the same scope, the result is that scope again. {A, A, ..., A} -> A;
3. When any scope in the parameters is the special global scope, it is as if it is not there. {A, G} -> A
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;
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;
6. When the parameter set is empty the result is the global scope. {} -> G
For a set-theoretic definition one can think of scopes as being keyed by sets of 'atoms'. Getting the key for a scope with multiple dependencies is defined by the operation of union of sets. The global scope is keyed by the empty set. A scope continues to exist for as long all of the atoms in it's key set exist.
Standalone Page
> home > Custom Layer Boundary API

get_mouse_state

September 8th 2024
Get the state of the mouse as of this frame

Signature

C++
Mouse_State
get_mouse_state(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the current mouse state struct
Standalone Page
> home > Custom Layer Boundary API

get_string_advance

September 8th 2024
Compute the total advance of a string rendered in a particular font

Signature

C++
f32
get_string_advance(Application_Links* app,
                   Face_ID font_id,
                   String_Const_u8 str);

Parameters

app

the standard custom layer context pointer

font_id

the id of the face to use rendering the text

str

the text to be rendered

Return

the total advance of the string
Standalone Page
> home > Custom Layer Boundary API

get_this_ctx_view

September 8th 2024
Get the view attached to the thread context

Signature

C++
View_ID
get_this_ctx_view(Application_Links* app,
                  Access_Flag access);

Parameters

app

the standard custom layer context pointer

access

the type of access requirements that the view must satisfy

Return

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
Standalone Page
> home > Custom Layer Boundary API

get_thread_context

September 8th 2024
Get the current thread's context

Signature

C++
Thread_Context*
get_thread_context(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the pointer to the current thread's context
Standalone Page
> home > Custom Layer Boundary API

get_view_next

September 8th 2024
Iterate to the next view

Signature

C++
View_ID
get_view_next(Application_Links* app,
              View_ID view_id,
              Access_Flag access);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to iterate from, or zero to get the first view

access

the type of access requirements used to filter on the views that are returned

Return

the id of the next view, or zero if there is no next view
Standalone Page
> home > Custom Layer Boundary API

get_view_prev

September 8th 2024
Iterate to the previous view

Signature

C++
View_ID
get_view_prev(Application_Links* app,
              View_ID view_id,
              Access_Flag access);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to iterate from, or zero to get the first view

access

the type of access requirements used to filter on the views that are returned

Return

the id of the previous view, or zero if there is no previous view
Standalone Page
> home > Custom Layer Boundary API

global_get_screen_rectangle

September 8th 2024
Get the rectangle the represents the renderable region in pixels

Signature

C++
Rect_f32
global_get_screen_rectangle(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

an f32 rectangle based as (0, 0) that represents the entire renderable region in pixels
Standalone Page
> home > Custom Layer Boundary API

global_history_edit_group_begin

September 8th 2024
Begin an edit group to merge all edits across all buffers

Signature

C++
void
global_history_edit_group_begin(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Details

When inside a global history edit group, all edits are merged into group edits, and the global edit number counter is frozen. Groups are formed by a nest counter, so that each call to global_history_edit_group_begin must be matched by a call to global_history_edit_group_end.
Standalone Page
> home > Custom Layer Boundary API

global_history_edit_group_end

September 8th 2024
End an edit group to merge all edits across all buffers

Signature

C++
void
global_history_edit_group_end(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Details

When inside a global history edit group, all edits are merged into group edits, and the global edit number counter is frozen. Groups are formed by a nest counter, so that each call to global_history_edit_group_begin must be matched by a call to global_history_edit_group_end.
Standalone Page
> home > Custom Layer Boundary API

global_set_setting

September 8th 2024
Modify a core setting

Signature

C++
b32
global_set_setting(Application_Links* app,
                   Global_Setting_ID setting,
                   i64 value);

Parameters

app

the standard custom layer context pointer

setting

the id of the setting to set

value

the new value for the setting

Return

non-zero when the setting is valid and updated without error, zero otherwise

Related

Global_Setting_ID
Standalone Page
> home > Custom Layer Boundary API

hard_exit

September 8th 2024
Exits 4coder at the end of the frame, no matter what; for instance, call from the exit signal handler to actual exit 4coder.

Signature

C++
void
hard_exit(Application_Links* app);

Parameters

app

the standard custom layer context pointer
Standalone Page
> home > Custom Layer Boundary API

leave_current_input_unhandled

September 8th 2024
Notifies the core that the input currently being handled by a view context thread should be treated as if it were not handled

Signature

C++
void
leave_current_input_unhandled(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Details

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.
Standalone Page
> home > Custom Layer Boundary API

log_string

September 8th 2024
Write a string to the *log* buffer

Signature

C++
b32
log_string(Application_Links* app,
           String_Const_u8 str);

Parameters

app

the standard custom layer context pointer

str

the string to write to the log

Return

non-zero when the string was written to the log, each thread can individually have logging disabled, in which case zero is returned
Standalone Page
> home > Custom Layer Boundary API

managed_id_declare

September 8th 2024
Get a unique id for a given name within a particular group

Signature

C++
Managed_ID
managed_id_declare(Application_Links* app,
                   String_Const_u8 group,
                   String_Const_u8 name);

Parameters

app

the standard custom layer context pointer

group

a name identifying a managed id group

name

a name identifying a managed id

Return

the id assigned to the given (group, name) pair

Details

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.
Standalone Page
> home > Custom Layer Boundary API

managed_id_get

September 8th 2024
Like managed_id_declare except never returns new ids, only ids that have already been declared.

Signature

C++
Managed_ID
managed_id_get(Application_Links* app,
               String_Const_u8 group,
               String_Const_u8 name);

Parameters

app

the standard custom layer context pointer

group

a name identifying a managed id group

name

a name identifying a managed id

Return

the id assigned to the given (group, name) pair

Details

managed_id_declare

Related

Standalone Page
> home > Custom Layer Boundary API

managed_id_group_highest_id

September 8th 2024
Get the highest id issued for a particular group of managed ids

Signature

C++
u64
managed_id_group_highest_id(Application_Links* app,
                            String_Const_u8 group);

Parameters

app

the standard custom layer context pointer

group

a name identifying a managed id group

Return

the highest id returned by managed_id_declare for the given group, zero if the group has never been used to declare an id
Standalone Page
> home > Custom Layer Boundary API

managed_object_free

September 8th 2024
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

Signature

C++
b32
managed_object_free(Application_Links* app,
                    Managed_Object object);

Parameters

app

the standard custom layer context pointer

object

the id of the object to free

Return

non-zero when the object exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

managed_object_get_containing_scope

September 8th 2024
Get the id of the scope that contains a particular managed object

Signature

C++
Managed_Scope
managed_object_get_containing_scope(Application_Links* app,
                                    Managed_Object object);

Parameters

app

the standard custom layer context pointer

object

the id of a managed object

Return

on success, when the object exists, the id of the managed scope that contains the object, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

managed_object_get_item_count

September 8th 2024
Get the number of the items in a managed object

Signature

C++
u32
managed_object_get_item_count(Application_Links* app,
                              Managed_Object object);

Parameters

app

the standard custom layer context pointer

object

the id of the managed object to query

Return

on success, when the object exists, the number of items in the managed object, otherwise zero

Details

Managed objects are essentially arrays with special management inside the core, such as markers. This call returns the number of items in the array.
Standalone Page
> home > Custom Layer Boundary API

managed_object_get_item_size

September 8th 2024
Get the size of the items in a managed object

Signature

C++
u32
managed_object_get_item_size(Application_Links* app,
                             Managed_Object object);

Parameters

app

the standard custom layer context pointer

object

the id of the managed object to query

Return

on success, when the object exists, the number of bytes in each item of the managed object, otherwise zero

Details

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.
Standalone Page
> home > Custom Layer Boundary API

managed_object_get_pointer

September 8th 2024
Get a pointer to he base of a managed object

Signature

C++
void*
managed_object_get_pointer(Application_Links* app,
                           Managed_Object object);

Parameters

app

the standard custom layer context pointer

object

the id of the managed object to query

Return

on success, when the object exists, a pointer to the base of the memory allocated for the object, otherwise zero

Details

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.
Standalone Page
> home > Custom Layer Boundary API

managed_object_get_type

September 8th 2024
Get a type code indicating what sort data is represented by a managed object

Signature

C++
Managed_Object_Type
managed_object_get_type(Application_Links* app,
                        Managed_Object object);

Parameters

app

the standard custom layer context pointer

object

the id of the object to query

Return

on success, when the object exists, the type code of the object, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

managed_object_load_data

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
b32
managed_object_load_data(Application_Links* app,
                         Managed_Object object,
                         u32 first_index,
                         u32 count,
                         void* mem_out);
Standalone Page
> home > Custom Layer Boundary API

managed_object_store_data

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
b32
managed_object_store_data(Application_Links* app,
                          Managed_Object object,
                          u32 first_index,
                          u32 count,
                          void* mem);
Standalone Page
> home > Custom Layer Boundary API

managed_scope_allocator

September 8th 2024
Get the base allocator for a managed scope

Signature

C++
Base_Allocator*
managed_scope_allocator(Application_Links* app,
                        Managed_Scope scope);

Parameters

app

the standard custom layer context pointer

scope

the id of the scope to query

Return

a pointer to the base allocator for the managed scope if it exists, zero otherwise

Details

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.
Standalone Page
> home > Custom Layer Boundary API

managed_scope_attachment_erase

September 8th 2024
Free an attachment on a managed scope

Signature

C++
b32
managed_scope_attachment_erase(Application_Links* app,
                               Managed_Scope scope,
                               Managed_ID id);

Parameters

app

the standard custom layer context pointer

scope

the id of the scope to modify

id

the id of the attachment to modify

Return

non-zero when the scope exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

managed_scope_clear_contents

September 8th 2024
Clear everything allocated inside a given scope without destroying the scope itself

Signature

C++
b32
managed_scope_clear_contents(Application_Links* app,
                             Managed_Scope scope);

Parameters

app

the standard custom layer context pointer

scope

the id of the scope to clear

Return

non-zero if the scope exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

managed_scope_clear_self_all_dependent_scopes

September 8th 2024
Clear everything allocated inside an atomic scope and all of it's dependent scopes without destroying any of them

Signature

C++
b32
managed_scope_clear_self_all_dependent_scopes(Application_Links* app,
                                              Managed_Scope scope);

Parameters

app

the standard custom layer context pointer

scope

the id of the scope to modify

Return

non-zero if the scope exists and is atomic, zero otherwise

Details

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.
A scope is atomic specifically whenever it satisfies any of these conditions:
1. It is a scope tied to a buffer and returned by buffer_get_managed_scope
2. It is a scope tied to a view and returned by view_get_managed_scope
3. It was created by a call to create_user_managed_scope
Standalone Page
> home > Custom Layer Boundary API

managed_scope_get_attachment

September 8th 2024
Get an attachment contained to a managed scope, allocating it if necessary

Signature

C++
void*
managed_scope_get_attachment(Application_Links* app,
                             Managed_Scope scope,
                             Managed_ID id,
                             u64 size);

Parameters

app

the standard custom layer context pointer

scope

the id of a scope to query

id

the id of the attachment to query

size

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

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

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.
Standalone Page
> home > Custom Layer Boundary API

open_color_picker

September 8th 2024
Potentially going to be deprecated - do not rely on this call!

Signature

C++
void
open_color_picker(Application_Links* app,
                  Color_Picker* picker);
Standalone Page
> home > Custom Layer Boundary API

paint_text_color

September 8th 2024
Set the color of a range of characters in a text layout

Signature

C++
void
paint_text_color(Application_Links* app,
                 Text_Layout_ID layout_id,
                 Range_i64 range,
                 ARGB_Color color);

Parameters

app

the standard custom layer context pointer

layout_id

the id of the text layout object

range

the range in byte positions to modify

color

the new color of the text in the range
Standalone Page
> home > Custom Layer Boundary API

panel_get_child

September 8th 2024
Get one of the children of a split panel

Signature

C++
Panel_ID
panel_get_child(Application_Links* app,
                Panel_ID panel_id,
                Side which_child);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to query

which_child

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

the id of the requested child of the given panel, if the given panel exists and is a split, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

panel_get_parent

September 8th 2024
Get the parent panel of a panel

Signature

C++
Panel_ID
panel_get_parent(Application_Links* app,
                 Panel_ID panel_id);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to query

Return

the id of the panel that is the parent of the given panel, if the given panel exists and is not root, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

panel_get_root

September 8th 2024
Get the root panel of the panel layout

Signature

C++
Panel_ID
panel_get_root(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Return

the id of the root panel
Standalone Page
> home > Custom Layer Boundary API

panel_get_view

September 8th 2024
Get the id of a view associated with a panel

Signature

C++
View_ID
panel_get_view(Application_Links* app,
               Panel_ID panel_id,
               Access_Flag access);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to query

access

the type of access requirements that the view must satisfy

Return

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

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.
Standalone Page
> home > Custom Layer Boundary API

panel_is_leaf

September 8th 2024
Check if a panel is a leaf panel with an associated view

Signature

C++
b32
panel_is_leaf(Application_Links* app,
              Panel_ID panel_id);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to query

Return

non-zero if the panel exists and is a leaf panel in the panel layout tree

Details

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.
Standalone Page
> home > Custom Layer Boundary API

panel_is_split

September 8th 2024
Check if a panel is an internal split panel

Signature

C++
b32
panel_is_split(Application_Links* app,
               Panel_ID panel_id);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to query

Return

non-zero if the panel exists and is an internal panel in the panel layout tree

Details

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.
Standalone Page
> home > Custom Layer Boundary API

panel_set_split

September 8th 2024
Set the split properties of a split panel

Signature

C++
b32
panel_set_split(Application_Links* app,
                Panel_ID panel_id,
                Panel_Split_Kind kind,
                f32 t);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to modify

kind

the kind of split rule used to determine the position of the split

t

the value parameter of the split rule

Return

non-zero if the panel exists and is a split panel, zero otherwise

Details

Standalone Page
> home > Custom Layer Boundary API

panel_split

September 8th 2024
Introduce a split at a given panel

Signature

C++
b32
panel_split(Application_Links* app,
            Panel_ID panel_id,
            Dimension split_dim);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to split

split_dim

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

non-zero on success, when the panel exists and splitting it is possible, zero otherwise

Details

New splits are created as 50/50 proportional splits.
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.
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.
Standalone Page
> home > Custom Layer Boundary API

panel_swap_children

September 8th 2024
Swap the min and max children of a split panel

Signature

C++
b32
panel_swap_children(Application_Links* app,
                    Panel_ID panel_id);

Parameters

app

the standard custom layer context pointer

panel_id

the id of the panel to modify

Return

non-zero if the panel exists and is a split panel
Standalone Page
> home > Custom Layer Boundary API

print_message

September 8th 2024
Print a message to the *messages* buffer

Signature

C++
void
print_message(Application_Links* app,
              String_Const_u8 message);

Parameters

app

the standard custom layer context pointer

message

the string to write to the *messages* buffer
Standalone Page
> home > Custom Layer Boundary API

push_buffer_base_name

September 8th 2024
Get a copy of the base name of a buffer

Signature

C++
String_Const_u8
push_buffer_base_name(Application_Links* app,
                      Arena* arena,
                      Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

arena

the arena on which the returned string will be allocated

buffer_id

the id of the buffer to query

Return

the name assigned to the buffer when it was created on success, when the buffer exists, otherwise an empty string
Standalone Page
> home > Custom Layer Boundary API

push_buffer_file_name

September 8th 2024
Get a copy of the file name of a buffer

Signature

C++
String_Const_u8
push_buffer_file_name(Application_Links* app,
                      Arena* arena,
                      Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

arena

the arena on which the returned string will be allocated

buffer_id

the id of the buffer to query

Return

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
Standalone Page
> home > Custom Layer Boundary API

push_buffer_unique_name

September 8th 2024
Get a copy of the unique name of a buffer

Signature

C++
String_Const_u8
push_buffer_unique_name(Application_Links* app,
                        Arena* out,
                        Buffer_ID buffer_id);

Parameters

app

the standard custom layer context pointer

out

the arena on which the returned string will be allocated

buffer_id

the id of the buffer to query

Return

the name assigned to the buffer by resolving duplicate names on success, when the buffer exists, otherwise an empty string
Standalone Page
> home > Custom Layer Boundary API

push_hot_directory

September 8th 2024
Get a copy of the hot directory

Signature

C++
String_Const_u8
push_hot_directory(Application_Links* app,
                   Arena* arena);

Parameters

app

the standard custom layer context pointer

arena

the arena on which the returned string will be allocated

Return

a copy of the hot directory
Standalone Page
> home > Custom Layer Boundary API

send_exit_signal

September 8th 2024
Send the signal to the core to try to shutdown

Signature

C++
void
send_exit_signal(Application_Links* app);

Parameters

app

the standard custom layer context pointer

Details

The exit signal does not automatically close 4coder, first the exit hook is called, which can cancel the exit. If it does not cancel the exit, then 4coder closes.
Standalone Page
> home > Custom Layer Boundary API

set_current_input

September 8th 2024
Modify the memory of the event that was most recently sent to the calling view context memory

Signature

C++
void
set_current_input(Application_Links* app,
                  User_Input* input);

Parameters

app

the standard custom layer context pointer

input

a pointer to the input struct to copy over the existing input struct in the core

Details

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.
Standalone Page
> home > Custom Layer Boundary API

set_custom_hook

September 8th 2024
Modify a global hook binding

Signature

C++
void
set_custom_hook(Application_Links* app,
                Hook_ID hook_id,
                Void_Func* func_ptr);

Parameters

app

the standard custom layer context pointer

hook_id

the id of the hook to be modified

func_ptr

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

Hook_ID
Standalone Page
> home > Custom Layer Boundary API

set_custom_hook_memory_size

September 8th 2024
Set the memory size for the extra memory used to store the state of certain hooks

Signature

C++
b32
set_custom_hook_memory_size(Application_Links* app,
                            Hook_ID hook_id,
                            u64 size);

Parameters

app

the standard custom layer context pointer

hook_id

the id of the hook to be modified

size

the size in bytes of the memory set aside for the state of the specified hook

Return

non-zero when the hook id is valid and accepts extra memory size, otherwise zero

Related

view_current_context_hook_memory
Standalone Page
> home > Custom Layer Boundary API

set_global_face

September 8th 2024
Change the global default face

Signature

C++
b32
set_global_face(Application_Links* app,
                Face_ID id);

Parameters

app

the standard custom layer context pointer

id

the id of the new global default face

Return

non-zero on success, when the face exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

set_hot_directory

September 8th 2024
Set the hot directory

Signature

C++
void
set_hot_directory(Application_Links* app,
                  String_Const_u8 string);

Parameters

app

the standard custom layer context pointer

string

the new value of the hot directory
Standalone Page
> home > Custom Layer Boundary API

set_window_title

September 8th 2024
Set the title of the 4coder window

Signature

C++
void
set_window_title(Application_Links* app,
                 String_Const_u8 title);

Parameters

app

the standard custom layer context pointer

title

the new title of the window
Standalone Page
> home > Custom Layer Boundary API

start_query_bar

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
b32
start_query_bar(Application_Links* app,
                Query_Bar* bar,
                u32 flags);
Standalone Page
> home > Custom Layer Boundary API

text_layout_character_on_screen

September 8th 2024
Get the rectangle covered by a character in the layout

Signature

C++
Rect_f32
text_layout_character_on_screen(Application_Links* app,
                                Text_Layout_ID layout_id,
                                i64 pos);

Parameters

app

the standard custom layer context pointer

layout_id

the id of the text layout object

pos

the byte position to query

Return

on success, when the object exists and the position is visible in the layout, the rectangle in pixels covered by the character, cleared to zero otherwise
Standalone Page
> home > Custom Layer Boundary API

text_layout_create

September 8th 2024
Create a text layout object

Signature

C++
Text_Layout_ID
text_layout_create(Application_Links* app,
                   Buffer_ID buffer_id,
                   Rect_f32 rect,
                   Buffer_Point buffer_point);

Parameters

app

the standard custom layer context pointer

buffer_id

the id of the buffer to read for layout

rect

the region on the screen where the layout will be placed

buffer_point

the point in the buffer that will be placed in the top left corner of the rectangle

Return

the id of the new text layout object, when the buffer exists and contains the buffer point, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

text_layout_free

September 8th 2024
Release the resources associated with a text layout object

Signature

C++
b32
text_layout_free(Application_Links* app,
                 Text_Layout_ID text_layout_id);

Parameters

app

the standard custom layer context pointer

text_layout_id

the id of the text layout object

Return

non-zero on success, when the text layout object exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

text_layout_get_buffer

September 8th 2024
Get the buffer of a layout object

Signature

C++
Buffer_ID
text_layout_get_buffer(Application_Links* app,
                       Text_Layout_ID text_layout_id);

Parameters

app

the standard custom layer context pointer

text_layout_id

the id of the text layout object

Return

on success, when the text layout object exists, the id of the buffer used to create the object, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

text_layout_get_visible_range

September 8th 2024
Get the range in byte positions within the buffer that are visible in a text layout

Signature

C++
Range_i64
text_layout_get_visible_range(Application_Links* app,
                              Text_Layout_ID text_layout_id);

Parameters

app

the standard custom layer context pointer

text_layout_id

the id of the text layout object

Return

on success, when the text layout object exists, the range of positions in the buffer that are visible in the object, otherwise cleared to zero
Standalone Page
> home > Custom Layer Boundary API

text_layout_line_on_screen

September 8th 2024
Get the range of the y-axis spanned by a line layout

Signature

C++
Range_f32
text_layout_line_on_screen(Application_Links* app,
                           Text_Layout_ID layout_id,
                           i64 line_number);

Parameters

app

the standard custom layer context pointer

layout_id

the id of the text layout object

line_number

the line number of the line to query

Return

on success, when the object exists and the line is visible in the layout, the range in pixels from the top to the bottom of a particular line, cleared to zero otherwise
Standalone Page
> home > Custom Layer Boundary API

text_layout_region

September 8th 2024
Get the on screen rectangular region of a layout object

Signature

C++
Rect_f32
text_layout_region(Application_Links* app,
                   Text_Layout_ID text_layout_id);

Parameters

app

the standard custom layer context pointer

text_layout_id

the id of the text layout object

Return

on success, when the text layout object exists, the rectangular region used to create the object, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

try_create_new_face

September 8th 2024
Attempt to create a new face given a face description

Signature

C++
Face_ID
try_create_new_face(Application_Links* app,
                    Face_Description* description);

Parameters

app

the standard custom layer context pointer

description

the description of the new face

Return

the id of the new face on success, when it is possible to instantiate the face, otherwise zero

Related

Face_Description
Standalone Page
> home > Custom Layer Boundary API

try_modify_face

September 8th 2024
Attempt to modify a face given a face description

Signature

C++
b32
try_modify_face(Application_Links* app,
                Face_ID id,
                Face_Description* description);

Parameters

app

the standard custom layer context pointer

id

the id of the face to modify

description

the description to use to reinstantiate the face

Return

non-zero on success, when the face already exists and the new instantiation is possible, otherwise zero

Related

Face_Description
Standalone Page
> home > Custom Layer Boundary API

try_release_face

September 8th 2024
Attempt to release the resources tied up in a face

Signature

C++
b32
try_release_face(Application_Links* app,
                 Face_ID id,
                 Face_ID replacement_id);

Parameters

app

the standard custom layer context pointer

id

the id of the face to release

replacement_id

the id of the new face to replace existing usages of the released face

Return

non-zero on success, when the face exists and the replacement also exists and is a different face, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

view_alter_context

September 8th 2024
Modify the context details at the top of a view's context details stack

Signature

C++
b32
view_alter_context(Application_Links* app,
                   View_ID view_id,
                   View_Context* ctx);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

ctx

the new field values of the view context details to be copied onto the top of the stack

Return

non-zero if the view exists, zero otherwise

Related

View_Context
Standalone Page
> home > Custom Layer Boundary API

view_close

September 8th 2024
Close a view

Signature

C++
b32
view_close(Application_Links* app,
           View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to close

Return

non-zero if the view exists, zero otherwise

Details

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.
Standalone Page
> home > Custom Layer Boundary API

view_compute_cursor

September 8th 2024
Compute a view cursor from a view and a seek target

Signature

C++
Buffer_Cursor
view_compute_cursor(Application_Links* app,
                    View_ID view_id,
                    Buffer_Seek seek);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

seek

the seek target to use in a query for full cursor information

Return

the full cursor information for the position specified by the seek, if the view exists, otherwise cleared to zero

Details

Equivalent to calling the buffer related function with the same name using view to derive the buffer parameter.

Related

Buffer_Seek
Buffer_Cursor
Standalone Page
> home > Custom Layer Boundary API

view_current_context

September 8th 2024
Get the current context details at the top of a view's context details stack

Signature

C++
View_Context
view_current_context(Application_Links* app,
                     View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of thew view to query

Return

a copy of the context details for the given view if it exists, zero otherwise

Related

View_Context
Standalone Page
> home > Custom Layer Boundary API

view_current_context_hook_memory

September 8th 2024
Get the memory allocated for a specific hook tied to the current details context of a view

Signature

C++
String_Const_u8
view_current_context_hook_memory(Application_Links* app,
                                 View_ID view_id,
                                 Hook_ID hook_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

hook_id

the id of the hook to query

Return

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

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.
Standalone Page
> home > Custom Layer Boundary API

view_enqueue_command_function

September 8th 2024
Push an command to the core to be processed in the context of a particular view

Signature

C++
b32
view_enqueue_command_function(Application_Links* app,
                              View_ID view_id,
                              Custom_Command_Function* custom_func);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's context thread will be sent the command

custom_func

the function pointer to the command to be processed by the view

Return

non-zero if the view exists, zero otherwise

Details

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.
Standalone Page
> home > Custom Layer Boundary API

view_exists

September 8th 2024
Check that a view id represents a real view

Signature

C++
b32
view_exists(Application_Links* app,
            View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

non-zero if the view exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

view_get_buffer

September 8th 2024
Get the buffer attached to a view

Signature

C++
Buffer_ID
view_get_buffer(Application_Links* app,
                View_ID view_id,
                Access_Flag access);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

access

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

the id of the buffer if the view exists and the buffer satisfies the access requirements, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

view_get_buffer_region

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
Rect_f32
view_get_buffer_region(Application_Links* app,
                       View_ID view_id);
Standalone Page
> home > Custom Layer Boundary API

view_get_buffer_scroll

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
Buffer_Scroll
view_get_buffer_scroll(Application_Links* app,
                       View_ID view_id);
Standalone Page
> home > Custom Layer Boundary API

view_get_cursor_pos

September 8th 2024
Get the position of the core tracked cursor on a view

Signature

C++
i64
view_get_cursor_pos(Application_Links* app,
                    View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

the position of the view's cursor in bytes, if the view exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

view_get_managed_scope

September 8th 2024
Retrieve the managed scope tied to the lifetime of a view

Signature

C++
Managed_Scope
view_get_managed_scope(Application_Links* app,
                       View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

the id of the managed scope tied to the view on success, when the view exists, zero otherwise

Related

Managed_Scope
Standalone Page
> home > Custom Layer Boundary API

view_get_mark_pos

September 8th 2024
Get the position of the core tracked mark on a view

Signature

C++
i64
view_get_mark_pos(Application_Links* app,
                  View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

the position of the view's mark in bytes, if the view exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

view_get_panel

September 8th 2024
Get the id of a panel associated with a view

Signature

C++
Panel_ID
view_get_panel(Application_Links* app,
               View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

the id of the panel associated with the view, if the view exists, zero otherwise

Details

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.
Standalone Page
> home > Custom Layer Boundary API

view_get_preferred_x

September 8th 2024
Get the x coordinate of the core tracked preferred x on a view

Signature

C++
f32
view_get_preferred_x(Application_Links* app,
                     View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

the preferred x of the view in pixels from the left edge of buffer layout space, if the view exists, otherwise zero
Standalone Page
> home > Custom Layer Boundary API

view_get_screen_rect

September 8th 2024
Get the rectangle on screen covered by a view

Signature

C++
Rect_f32
view_get_screen_rect(Application_Links* app,
                     View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

Return

the rectangle covered by the view in pixels relative to the screen rectangle's top left corner, if the view exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

view_get_setting

September 8th 2024
Retrieve a core setting of a view

Signature

C++
b32
view_get_setting(Application_Links* app,
                 View_ID view_id,
                 View_Setting_ID setting,
                 i64* value_out);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to query

setting

the id of the setting to query

value_out

the output destination of the setting's value

Return

non-zero on success, when the view and setting exist, zero otherwise

Related

View_Setting_ID
Standalone Page
> home > Custom Layer Boundary API

view_line_shift_y

September 8th 2024
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

Signature

C++
Line_Shift_Vertical
view_line_shift_y(Application_Links* app,
                  View_ID view_id,
                  i64 line,
                  f32 y_shift);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

line

the line number of the line that serves as the relative starting point of the measurement

y_shift

the y shift, in pixels, from the top of the specified line to be measured

Return

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

Line numbers are 1 based.
Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view.

Related

Line_Shift_Vertical
Standalone Page
> home > Custom Layer Boundary API

view_line_y_difference

September 8th 2024
Compute the signed vertical pixel distance between the top of two lines

Signature

C++
f32
view_line_y_difference(Application_Links* app,
                       View_ID view_id,
                       i64 line_a,
                       i64 line_b);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

line_a

the line number of the line 'A' in the subtraction top(A) - top(B)

line_b

the line number of the line 'B' in the subtraction top(A) - top(B)

Return

the signed distance between the lines in pixels on success, when the view exists and contains both given line numbers

Details

Line numbers are 1 based.
Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view.
Standalone Page
> home > Custom Layer Boundary API

view_padded_box_of_pos

September 8th 2024
Compute the rectangle around a character at a particular byte position, relative to the top left corner of a given line

Signature

C++
Rect_f32
view_padded_box_of_pos(Application_Links* app,
                       View_ID view_id,
                       i64 base_line,
                       i64 pos);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

base_line

the line number of the line that serves as the relative starting point of the measurement

pos

the absolute byte index of the position to query

Return

the rectangle around 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

Line numbers are 1 based.
Standalone Page
> home > Custom Layer Boundary API

view_pop_context

September 8th 2024
Pop a view's stack of context details

Signature

C++
b32
view_pop_context(Application_Links* app,
                 View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

Return

non-zero on success, when the view exists and the details stack has more than one entry, zero otherwise

Related

View_Context
Standalone Page
> home > Custom Layer Boundary API

view_pos_at_relative_xy

September 8th 2024
Compute a byte position at a particular point relative to the top left corner of a particular line

Signature

C++
i64
view_pos_at_relative_xy(Application_Links* app,
                        View_ID view_id,
                        i64 base_line,
                        Vec2_f32 relative_xy);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

base_line

the line number of the line that serves as the relative starting point of the measurement

relative_xy

the point, in pixels, interpreted relative to the line's top left corner, that will serve as the query point

Return

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

Line numbers are 1 based.
Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view.
Standalone Page
> home > Custom Layer Boundary API

view_pos_from_relative_character

September 8th 2024
Compute the byte position associated with the start of a particular character specified relative to the first character of a particular line

Signature

C++
i64
view_pos_from_relative_character(Application_Links* app,
                                 View_ID view_id,
                                 i64 base_line,
                                 i64 character);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

base_line

the line number of the line that serves as the relative starting point of the measurement

character

the relative character index of the query character, based at the first character of base line

Return

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

Line numbers are 1 based.
Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view.
Standalone Page
> home > Custom Layer Boundary API

view_push_context

September 8th 2024
Push a view's stack of context details with a pointer to the new values for the context

Signature

C++
b32
view_push_context(Application_Links* app,
                  View_ID view_id,
                  View_Context* ctx);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

ctx

the new field values of the view context details to be copied onto the top of the stack

Return

non-zero if the view exists, otherwise zero

Related

View_Context
Standalone Page
> home > Custom Layer Boundary API

view_quit_ui

September 8th 2024
Try to force a view to exit a UI loop and return to the default buffer display behavior

Signature

C++
b32
view_quit_ui(Application_Links* app,
             View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

Return

non-zero if the view exists, zero otherwise

Details

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.
Standalone Page
> home > Custom Layer Boundary API

view_relative_box_of_pos

September 8th 2024
Compute the box of a character that spans a particular byte position, relative to the top left corner of a given line

Signature

C++
Rect_f32
view_relative_box_of_pos(Application_Links* app,
                         View_ID view_id,
                         i64 base_line,
                         i64 pos);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

base_line

the line number of the line that serves as the relative starting point of the measurement

pos

the absolute byte index of the position to query

Return

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

Line numbers are 1 based.
Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view.
Standalone Page
> home > Custom Layer Boundary API

view_relative_character_from_pos

September 8th 2024
Compute a character index relative to a particular lines first character

Signature

C++
i64
view_relative_character_from_pos(Application_Links* app,
                                 View_ID view_id,
                                 i64 base_line,
                                 i64 pos);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view who's layout will be measured

base_line

the line number of the line that serves as the relative starting point of the measurement

pos

the absolute byte index of the position to query

Return

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

Line numbers are 1 based.
Equivalent to calling the buffer related function of the same name by deriving the buffer, width, and face from the view.
Standalone Page
> home > Custom Layer Boundary API

view_set_active

September 8th 2024
Set the active view

Signature

C++
b32
view_set_active(Application_Links* app,
                View_ID view_id);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to set as active

Return

non-zero if the view exists, zero otherwise
Standalone Page
> home > Custom Layer Boundary API

view_set_buffer

September 8th 2024
Set a view's associated buffer

Signature

C++
b32
view_set_buffer(Application_Links* app,
                View_ID view_id,
                Buffer_ID buffer_id,
                Set_Buffer_Flag flags);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

buffer_id

the id of the buffer to associate to this view

flags

flags controlling the behavior of the view as it changes to the new buffer

Return

non-zero if the view and buffer both exist, otherwise zero

Related

Set_Buffer_Flag
Standalone Page
> home > Custom Layer Boundary API

view_set_buffer_scroll

September 8th 2024
Plans to deprecate - do not rely on this call!

Signature

C++
b32
view_set_buffer_scroll(Application_Links* app,
                       View_ID view_id,
                       Buffer_Scroll scroll,
                       Set_Buffer_Scroll_Rule rule);
Standalone Page
> home > Custom Layer Boundary API

view_set_cursor

September 8th 2024
Set a view's internal cursor position

Signature

C++
b32
view_set_cursor(Application_Links* app,
                View_ID view_id,
                Buffer_Seek seek);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

seek

the seek target to use to derive the new position

Return

non-zero if the view exists, zero otherwise

Related

Buffer_Seek
Standalone Page
> home > Custom Layer Boundary API

view_set_mark

September 8th 2024
Set a view's internal mark position

Signature

C++
b32
view_set_mark(Application_Links* app,
              View_ID view_id,
              Buffer_Seek seek);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

seek

the seek target to use to derive the new position

Return

non-zero if the view exists, zero otherwise

Related

Buffer_Seek
Standalone Page
> home > Custom Layer Boundary API

view_set_preferred_x

September 8th 2024
Set the preferred x on a view

Signature

C++
b32
view_set_preferred_x(Application_Links* app,
                     View_ID view_id,
                     f32 x);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

x

the new preferred x coordinate

Return

non-zero if the view exists, zero otherwise

Details

the preferred x is used to keep a cursor aligned as closely as possible to a particular x-coordinate durring vertical movements
Standalone Page
> home > Custom Layer Boundary API

view_set_setting

September 8th 2024
Retrieve a core setting of a view

Signature

C++
b32
view_set_setting(Application_Links* app,
                 View_ID view_id,
                 View_Setting_ID setting,
                 i64 value);

Parameters

app

the standard custom layer context pointer

view_id

the id of the view to modify

setting

the id of the setting to modify

value

the new value of the specified setting

Return

non-zero on success, when the view and setting exist, zero otherwise

Related

View_Setting_ID
Standalone Page