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