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 Type List
§2.3 Function Descriptions
§2.3.1: 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.3.2: 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.3.3: 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.3.4: clipboard_count
int app->clipboard_count(
Application_Links *app
)
Description
returns the number of items in the clipboard
§2.3.5: 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.3.6: 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
§2.3.7: 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
§2.3.8: 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.3.9: get_buffer_by_name
Buffer_Summary app->get_buffer_by_name(
Application_Links *app,
char *name,
int len,
unsigned int access
)
Parameters
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.3.10: 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
§2.3.11: buffer_read_range
int app->buffer_read_range(
Application_Links *app,
Buffer_Summary *buffer,
int start,
int end,
char *out
)
Parameters
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.3.12: buffer_replace_range
int app->buffer_replace_range(
Application_Links *app,
Buffer_Summary *buffer,
int start,
int end,
char *str,
int len
)
Parameters
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.3.13: buffer_set_setting
int app->buffer_set_setting(
Application_Links *app,
Buffer_Summary *buffer,
int setting,
int value
)
Parameters
buffer
The buffer on which to set a setting.
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
§2.3.14: 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
§2.3.15: 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
§2.3.16: 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
Return
returns non-zero if the save succeeds
§2.3.17: 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
§2.3.18: 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
§2.3.19: 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
§2.3.20: 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.3.21: 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
§2.3.22: 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
§2.3.23: view_set_setting
int app->view_set_setting(
Application_Links *app,
View_Summary *view,
int setting,
int value
)
Parameters
view
The view on which to set a setting.
setting
One of the View_Setting_ID enum values that identifies the setting to set.
value
The value to set the specified setting to.
See Also
§2.3.24: 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.3.25: 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.
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
§2.3.26: 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
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
§2.3.27: 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
Return
returns non-zero on success
Description
Sets the the view's mark position.
See Also
§2.3.28: 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.3.29: 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
§2.3.30: 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
§2.3.33: get_mouse_state
Mouse_State app->get_mouse_state(
Application_Links *app
)
Return
returns the current mouse state
See Also
§2.3.34: 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
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.3.35: 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
Description
bar must be a pointer previously passed to start_query_bar previously in the same command.
§2.3.36: print_message
void app->print_message(
Application_Links *app,
char *str,
int len
)
Parameters
str
the string to post to *messages*
§2.3.37: 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.3.38: 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.3.39: 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.3.40: 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.3.41: 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.3.42: 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.3.43: 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.3.44: file_exists
int app->file_exists(
Application_Links *app,
char *filename,
int len
)
Parameters
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.3.45: 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.3.46: get_4ed_path
int app->get_4ed_path(
Application_Links *app,
char *out,
int capacity
)
Parameters
out
A char 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.
§2.3.47: show_mouse_cursor
void app->show_mouse_cursor(
Application_Links *app,
int show
)
Parameters
show
The show state to put the mouse cursor into, should be one of the Mouse_Cursor_Show_Type enum values.
See Also
§2.4 Type Descriptions
§2.4.1: Key_Code
typedef unsigned char Key_Code;
§2.4.2: Key_Modifier
enum Key_Modifier;
§2.4.3: Command_ID
enum Command_ID;
§2.4.5: Event_Message_Type_ID
enum Event_Message_Type_ID;
§2.4.6: Buffer_Setting_ID
enum Buffer_Setting_ID;
§2.4.7: View_Setting_ID
enum View_Setting_ID;
§2.4.8: Mouse_Cursor_Show_Type
enum Mouse_Cursor_Show_Type;
§2.4.9: Key_Modifier_Flag
enum Key_Modifier_Flag;
§2.4.10: Buffer_Create_Flag
enum Buffer_Create_Flag;
§2.4.11: Buffer_Kill_Flag
enum Buffer_Kill_Flag;
§2.4.12: Access_Flag
enum Access_Flag;
§2.4.13: Seek_Boundary_Flag
enum Seek_Boundary_Flag;
§2.4.15: Auto_Indent_Flag
enum Auto_Indent_Flag;
§2.4.16: Set_Buffer_Flag
enum Set_Buffer_Flag;
§2.4.18: Key_Event_Data
struct Key_Event_Data {
Key_Code keycode;
Key_Code character;
Key_Code character_no_caps_lock;
char modifiers[MDFR_INDEX_COUNT];
};
§2.4.19: Mouse_State
struct Mouse_State {
char l;
char r;
char press_l;
char press_r;
char release_l;
char release_r;
char wheel;
char out_of_window;
int x;
int y;
};
§2.4.20: Range
union Range {
struct {
int min;
int max;
};
struct {
int start;
int end;
};
};
§2.4.21: File_Info
struct File_Info {
char * filename;
int filename_len;
int folder;
};
§2.4.22: File_List
struct File_List {
void * block;
File_Info * infos;
int count;
int block_size;
};
§2.4.23: Buffer_Identifier
struct Buffer_Identifier {
char * name;
int name_len;
int id;
};
§2.4.24: Buffer_Summary
struct Buffer_Summary {
int exists;
int ready;
int buffer_id;
unsigned int lock_flags;
int size;
char * file_name;
int file_name_len;
char * buffer_name;
int buffer_name_len;
int buffer_cursor_pos;
int is_lexed;
int map_id;
};
§2.4.25: View_Summary
struct View_Summary {
int exists;
int view_id;
int buffer_id;
unsigned int lock_flags;
Full_Cursor cursor;
Full_Cursor mark;
float preferred_x;
float line_height;
int unwrapped_lines;
int show_whitespace;
i32_Rect file_region;
GUI_Scroll_Vars scroll_vars;
};
§2.4.27: Query_Bar
struct Query_Bar {
String prompt;
String string;
};
§2.4.28: Event_Message
struct Event_Message {
int type;
};
§2.4.29: Theme_Color
struct Theme_Color {
Style_Tag tag;
uint32_t color;
};