4coder API

§1 Introduction

This is the documentation for alpha 4.0.9 super! The documentation has been made as accurate as possible but there may be errors. If you have questions or discover errors please contact editor@4coder.net.

§2 Types and Functions

§2.1 Function List

§2.2 Descriptions

§2.2.0: exec_command

void app->exec_command(
Application_Links *app,
uint64_t command_id
)
Parameters
command_id
an integer id enumerated in 4coder_custom.h starting with cmdid
Description
Executes the command associated with the command_id passed in

§2.2.1: exec_system_command

int app->exec_system_command(
Application_Links *app,
View_Summary *view,
Buffer_Identifier buffer,
char *path,
int path_len,
char *command,
int command_len,
unsigned int flags
)
Parameters
view
the target view that will display the output buffer, may be NULL, see description for details
buffer
a buffer identifier for the buffer that will be filled with the output from the command
path
the path from which the command is executed
path_len
the length of the path string
command
the command to be executed
command_len
the length of the command string
flags
may be zero or one or more CLI flags ORed together
Return
returns non-zero if the command is successfully started, returns zero otherwise
Description
Executes a system command as if called from the command line, and sends the output to a buffer. The buffer identifier can either name a new buffer that does not exist, name a buffer that does exist, or provide the id of a buffer that does exist. If the buffer already exists the command will fail, unless CLI_OverlapWithConflict is set in the flags. If the buffer is not already in an open view, and the view parameter is no NULL, then the provided view will display the output buffer. If the view parameter is NULL, no view will display the output. If CLI_OverlapWithConflict is set in the flags, the command will always be executed even if another command was outputting to the same buffer still. If CLI_AlwaysBindToView is set and the view parameter is not NULL, then the specified view will always begin displaying the output buffer, even if another open view already displays that buffer. If CLI_CursorAtEnd is set the cursor in the output buffer will be placed at the end of the buffer instead of at the beginning.

§2.2.2: clipboard_post

void app->clipboard_post(
Application_Links *app,
char *str,
int len
)
Parameters
str
the string to post to the clipboard
len
the length of the string str
Description
Stores the string str in the clipboard initially with index 0. Also reports the copy to the operating system, so that it may be pasted into other applications.

§2.2.3: clipboard_count

int app->clipboard_count(
Application_Links *app
)
Description
returns the number of items in the clipboard

§2.2.4: clipboard_index

int app->clipboard_index(
Application_Links *app,
int index,
char *out,
int len
)
Parameters
index
the index of the item to be read
out
a buffer where the clipboard contents are written or NULL
len
the length of the out buffer
Return
returns the size of the item on the clipboard associated with the given index
Description
There are multiple items on the 4coder clipboard. The most recent copy is always at index 0. The second most recent is at index 1, and so on for all the stored clipboard items. This function reads one of the clipboard items and stores it into the out buffer, if the out buffer is not NULL. This function always returns the size of the clipboard item specified even if the output buffer is NULL. If the output buffer is too small to contain the whole string, it is filled with the first len character of the clipboard contents. The output string is not null terminated.

§2.2.5: get_buffer_first

Buffer_Summary app->get_buffer_first(
Application_Links *app,
unsigned int access
)
Parameters
access
the access flags for the access
Return
returns the summary of the first buffer in a buffer loop
Description
Begins a loop across all the buffers. If the buffer returned does not exist, the loop is finished. Buffers should not be killed durring a buffer loop.
See Also
Access_Flag
get_buffer_next

§2.2.6: get_buffer_next

void app->get_buffer_next(
Application_Links *app,
Buffer_Summary *buffer,
unsigned int access
)
Parameters
buffer
pointer to the loop buffer originally returned by get_buffer_first
access
the access flags for the access
Description
Writes the next buffer into the buffer struct. To get predictable results every call to get_buffer_first and get_buffer_next in the loop should have the same access flags. If the buffer returned does not exist, the loop is finished. Buffers should not be killed durring a buffer loop.
See Also
Access_Flag
get_buffer_first

§2.2.7: get_buffer

Buffer_Summary app->get_buffer(
Application_Links *app,
int buffer_id,
unsigned int access
)
Parameters
buffer_id
the id of the buffer to get
access
the access flags for the access
Return
returns a summary that describes the indicated buffer if it exists and is accessible

§2.2.8: get_buffer_by_name

Buffer_Summary app->get_buffer_by_name(
Application_Links *app,
char *name,
int len,
unsigned int access
)
Parameters
name
the name of the buffer
len
the length of the name string
access
the access flags for the access
Return
returns a summary that describes the indicated buffer if it exists and is accessible

§2.2.9: buffer_boundary_seek

int app->buffer_boundary_seek(
Application_Links *app,
Buffer_Summary *buffer,
int start_pos,
int seek_forward,
unsigned int flags
)
Parameters
buffer
the buffer to seek through
start_pos
the absolute position in the buffer to begin the seek
seek_forward
non-zero indicates to seek forward otherwise the seek goes backward
flags
one or more types of boundaries to use for stopping the seek
Return
returns the position where the seek stops
See Also
Seek_Boundary_Flag

§2.2.10: buffer_read_range

int app->buffer_read_range(
Application_Links *app,
Buffer_Summary *buffer,
int start,
int end,
char *out
)
Parameters
buffer
The buffer to be read.
start
The beginning of the read range.
end
One past the end of the read range.
out
The output buffer to fill with the result of the read.
Return
Returns non-zero on success.
Description
The output buffer must have a capacity of at least (end - start). The output is not null terminated. This call fails if the buffer does not exist, or if the read range is not within the bounds of the buffer.

§2.2.11: buffer_replace_range

int app->buffer_replace_range(
Application_Links *app,
Buffer_Summary *buffer,
int start,
int end,
char *str,
int len
)
Parameters
buffer
the buffer to edit
start
the start of the range to edit
end
the end of the range to edit
str
the string to write into the range
len
the length of the str string
Return
returns non-zero if the replacement succeeds
Description
If this call succeeds it deletes the range from start to end and writes str in the same position. If end == start then this call is equivalent to inserting the string at start. If len == 0 this call is equivalent to deleteing the range from start to end. This call fails if the buffer does not exist, or if the replace range is not within the bounds of the buffer.

§2.2.12: buffer_set_setting

int app->buffer_set_setting(
Application_Links *app,
Buffer_Summary *buffer,
int setting,
int value
)
Parameters
buffer
the buffer to set a setting on
setting
one of the Buffer_Setting_ID enum values that identifies the setting to set
value
the value to set the specified setting to
See Also
Buffer_Setting_ID

§2.2.13: buffer_auto_indent

int app->buffer_auto_indent(
Application_Links *app,
Buffer_Summary *buffer,
int start,
int end,
int tab_width,
unsigned int flags
)
Parameters
buffer
the buffer in which to apply the auto indenting
start
the position to start the auto indenting
end
the position to end the auto indenting
tab_width
the number of spaces to place as a tab
flags
the auto tab behavior flags
Return
returns non-zero when the call succeeds
Description
Applies the built in auto-indentation rule to the code in the range from start to end by inserting spaces or tabs at the beginning of the lines. If the buffer does not have lexing enabled or the lexing job has not completed this function will fail.
See Also
Auto_Indent_Flag

§2.2.14: create_buffer

Buffer_Summary app->create_buffer(
Application_Links *app,
char *filename,
int filename_len,
unsigned int flags
)
Parameters
filename
the name of the file to be opened or created
filename_len
the length of the filename string
flags
flags for buffer creation behavior
Return
returns the summary of the created buffer on success or a NULL buffer otherwise
Description
Tries to create a new buffer and associate it to the given filename. If such a buffer already exists the existing buffer is returned in the buffer summary and no new buffer is created. If the buffer does not exist a new buffer is created and named after the given filename. If the filename corresponds to a file on the disk that file is loaded and put into buffer, if the filename does not correspond to a file on disk the buffer is created empty.
See Also
Buffer_Create_Flag

§2.2.15: save_buffer

int app->save_buffer(
Application_Links *app,
Buffer_Summary *buffer,
char *filename,
int filename_len,
unsigned int flags
)
Parameters
buffer
the buffer to save to a file
filename
the name of the file to save the buffer into
filename_len
length of the filename string
flags
not currently used
Return
returns non-zero if the save succeeds

§2.2.16: kill_buffer

int app->kill_buffer(
Application_Links *app,
Buffer_Identifier buffer,
int view_id,
unsigned int flags
)
Parameters
buffer
a buffer identifier specifying the buffer to try to kill
view_id
the id of view that will contain the "are you sure" dialogue
flags
flags for buffer kill behavior
Return
returns non-zero if the kill succeeds
Description
Tries to kill the idenfied buffer. If the buffer is dirty and the "are you sure" dialogue needs to be displayed the provided view is used to show the dialogue. If the view is not open the kill fails.
See Also
Buffer_Kill_Flags

§2.2.17: get_view_first

View_Summary app->get_view_first(
Application_Links *app,
unsigned int access
)
Parameters
access
the access flags for the access
Return
returns the summary of the first view in a view loop
Description
Begins a loop across all the open views. If the view summary returned is NULL, the loop is finished. Views should not be closed or opened durring a view loop.
See Also
Access_Flag
get_view_next

§2.2.18: get_view_next

void app->get_view_next(
Application_Links *app,
View_Summary *view,
unsigned int access
)
Parameters
view
pointer to the loop view originally returned by get_view_first
access
the access flags for the access
Description
Writes the next view into the view struct. To get predictable results every call to get_view_first and get_view_next in the loop should have the same access flags. If the view summary returned is NULL, the loop is finished. Views should not be closed or opened durring a view loop.
See Also
Access_Flag
get_view_first

§2.2.19: get_view

View_Summary app->get_view(
Application_Links *app,
int view_id,
unsigned int access
)
Parameters
view_id
the id of the view to get
access
the access flags for the access
Return
returns a summary that describes the indicated view if it is open and is accessible

§2.2.20: get_active_view

View_Summary app->get_active_view(
Application_Links *app,
unsigned int access
)
Parameters
access
the access flags for the access
Return
returns a summary that describes the active view
See Also
set_active_view

§2.2.21: set_active_view

int app->set_active_view(
Application_Links *app,
View_Summary *view
)
Parameters
view
the view to set as active
Return
returns non-zero on success
Description
If the given view is a currently open view, it is set as the active view, and takes subsequent commands and is returned from get_active_view.
See Also
get_active_view

§2.2.22: view_set_split_proportion

int app->view_set_split_proportion(
Application_Links *app,
View_Summary *view,
float t
)
Parameters
view
The view on which to adjust size.
t
The proportion of the view's containing box that it should occupy in [0,1]
Return
Returns non-zero on success.

§2.2.23: view_compute_cursor

int app->view_compute_cursor(
Application_Links *app,
View_Summary *view,
Buffer_Seek seek,
Full_Cursor *cursor_out
)
Parameters
view
The view on which to run the cursor computation.
seek
The seek position.
cursor_out
On success this is filled with result of the seek.
Return
Returns non-zero on success.
Description
Computes a full cursor for the given seek position.
See Also
Buffer_Seek

§2.2.24: view_set_cursor

int app->view_set_cursor(
Application_Links *app,
View_Summary *view,
Buffer_Seek seek,
int set_preferred_x
)
Parameters
view
the view in which to set the cursor
seek
the seek position
set_preferred_x
if true the preferred x is updated to match the new cursor position
Return
returns non-zero on success
Description
Sets the the view's cursor position. set_preferred_x should usually be true unless the change in cursor position is is a vertical motion that tries to keep the cursor in the same column or x position.
See Also
Buffer_Seek

§2.2.25: view_set_mark

int app->view_set_mark(
Application_Links *app,
View_Summary *view,
Buffer_Seek seek
)
Parameters
view
the view in which to set the mark
seek
the seek position
Return
returns non-zero on success
Description
Sets the the view's mark position.
See Also
Buffer_Seek

§2.2.26: view_set_highlight

int app->view_set_highlight(
Application_Links *app,
View_Summary *view,
int start,
int end,
int turn_on
)
Parameters
view
the view to set the highlight in
start
the start of the highlight range
end
the end of the highlight range
turn_on
indicates whether the highlight is being turned on or off
Return
returns non-zero on success
Description
The highlight is mutually exclusive to the cursor. When the turn_on parameter is set to true the highlight will be shown and the cursor will be hidden. After that either setting the with view_set_cursor or calling view_set_highlight and the turn_on set to false, will switch back to showing the cursor.

§2.2.27: view_set_buffer

int app->view_set_buffer(
Application_Links *app,
View_Summary *view,
int buffer_id,
unsigned int flags
)
Parameters
view
the view to display the buffer in
buffer_id
the buffer to show in the view
flags
set buffer behavior flags
Return
returns non-zero on success
Description
On success view_set_buffer sets the specified view's current buffer and cancels and dialogue shown in the view and displays the file.
See Also
Set_Buffer_Flag

§2.2.28: view_post_fade

int app->view_post_fade(
Application_Links *app,
View_Summary *view,
float seconds,
int start,
int end,
unsigned int color
)
Parameters
view
the veiw to post a fade effect to
seconds
the number of seconds the fade effect should last
start
the first character in the fade range
end
one after the last character in the fade range
color
the color to fade from

§2.2.29: get_user_input

User_Input app->get_user_input(
Application_Links *app,
unsigned int get_type,
unsigned int abort_type
)
Parameters
get_type
input type flag that specifies the types of inputs that should be returned
abort_type
input type flag that specifies the types of inputs that should cause an abort signal
Return
returns a User_Input that describes an event passed to the command
Description
This call preempts the command. The command is resumed if either a get or abort condition is met, or if another command is executed. If either the abort condition is met or another command is executed an abort signal is returned. If an abort signal is ever returned the command should finish execution without any more calls that preempt the command. If a get condition is met the user input is returned
See Also
Input_Type_Flag
User_Input

§2.2.30: get_command_input

User_Input app->get_command_input(
Application_Links *app
)
Return
returns the input that triggered the command in execution.
See Also
User_Input

§2.2.31: get_mouse_state

Mouse_State app->get_mouse_state(
Application_Links *app
)
Return
returns the current mouse state
See Also
Mouse_State

§2.2.32: start_query_bar

int app->start_query_bar(
Application_Links *app,
Query_Bar *bar,
unsigned int flags
)
Parameters
bar
a pointer to the Query_Bar struct that defines the bar's contents
flags
not currently used
Return
returns non-zero on success
Description
The memory pointed to by bar must remain valid until a call to end_query_bar or until the command returns.

§2.2.33: end_query_bar

void app->end_query_bar(
Application_Links *app,
Query_Bar *bar,
unsigned int flags
)
Parameters
bar
a pointer to the Query_Bar struct to end
flags
not currently used
Description
bar must be a pointer previously passed to start_query_bar previously in the same command.

§2.2.35: change_theme

void app->change_theme(
Application_Links *app,
char *name,
int len
)
Parameters
name
the name of the built in theme to change to
len
the length of the name string

§2.2.36: change_font

void app->change_font(
Application_Links *app,
char *name,
int len
)
Parameters
name
the name of the built in font to change to
len
the length of the name string

§2.2.37: set_theme_colors

void app->set_theme_colors(
Application_Links *app,
Theme_Color *colors,
int count
)
Parameters
colors
an array of color structs pairing differet style tags to color codes
count
the number of color structs in the colors array
Description
For each color struct in the array, the color in the style pallet is set to the color code paired with the tag.

§2.2.38: get_theme_colors

void app->get_theme_colors(
Application_Links *app,
Theme_Color *colors,
int count
)
Parameters
colors
an array of color structs listing style tags to get color values for
count
the number of color structs in the colors array
Description
For each color struct in the array, the color field of the struct is filled with the color from the specified color in the pallet.

§2.2.39: directory_get_hot

int app->directory_get_hot(
Application_Links *app,
char *out,
int capacity
)
Parameters
out
a buffer that receives the 4coder 'hot directory'
capacity
the maximum size to be output to the output buffer
Return
returns the size of the string written into the buffer
Description
4coder has a concept of a 'hot directory' which is the directory most recently accessed in the GUI. Whenever the GUI is opened it shows the hot directory. In the future this will be deprecated and eliminated in favor of more flexible directories controlled by the custom side.

§2.2.40: get_file_list

File_List app->get_file_list(
Application_Links *app,
char *dir,
int len
)
Parameters
dir
the directory whose files will be enumerated in the returned list
len
the length of the dir string
Return
returns a File_List struct containing pointers to the names of the files in the specified directory. The File_List returned should be passed to free_file_list when it is no longer in use.

§2.2.41: free_file_list

void app->free_file_list(
Application_Links *app,
File_List list
)
Parameters
list
the file list to be freed
Description
after this call the file list passed in should not be read or written to

§2.2.42: file_exists

int app->file_exists(
Application_Links *app,
char *filename,
int len
)
Parameters
filename
the full path to a file
len
the number of characters in the filename string
Return
returns non-zero if the file exists, returns zero if the file does not exist

§2.2.43: directory_cd

int app->directory_cd(
Application_Links *app,
char *dir,
int *len,
int capacity,
char *rel_path,
int rel_len
)
Parameters
dir
a string buffer containing a directory
len
the length of the string in the string buffer
capacity
the maximum size of the string buffer
rel_path
the path to change to, may include '.' or '..'
rel_len
the length of the rel_path string
Return
returns non-zero if the call succeeds, returns zero otherwise
Description
This call succeeds if the directory exists and the new directory fits inside the dir buffer. If the call succeeds the dir buffer is filled with the new directory and len contains the length of the string in the buffer. For instance if dir contains "C:/Users/MySelf" and rel is "Documents" the buffer will contain "C:/Users/MySelf/Documents" and len will contain the length of that string. This call can also be used with rel set to ".." to traverse to parent folders.

§2.2.44: get_4ed_path

int app->get_4ed_path(
Application_Links *app,
char *out,
int capacity
)
Parameters
out
a buffer that receives the path to the 4ed executable file
capacity
the maximum capacity of the output buffer
Return
returns non-zero on success, returns zero on failure