4coder API

bool32 app->exec_command( )

This call returns non-zero if command_id named a valid internal command.

A call to exec_command executes an internal command. If command_id is invalid a warning is posted to *messages*.

bool32 app->exec_system_command( )

This call returns non-zero on success.

A call to exec_system_command executes a 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 is not already in an open view and the view parameter is not NULL, then the provided view will display the output buffer. If the view parameter is NULL, no view will switch to the output.

void app->clipboard_post( )

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.

int32_t app->clipboard_count( )

This call returns the number of items in the clipboard.

int32_t app->clipboard_index( )

This call returns the size of the item associated with item_index.

This function always returns the size of the item 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.

Buffer_Summary app->get_buffer_first( )

This call returns the summary of the first buffer in a buffer loop.

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

void app->get_buffer_next( )

This call steps a buffer summary to the next buffer in the global buffer order. The global buffer order is kept roughly in the order of most recently used to least recently used. If the buffer outputted does not exist, the loop is finished. Buffers should not be killed or created durring a buffer loop.

Buffer_Summary app->get_buffer( )

This call returns a summary that describes the indicated buffer if it exists and is accessible.

Buffer_Summary app->get_buffer_by_name( )

This call returns a summary that describes the indicated buffer if it exists and is accessible.

int32_t app->buffer_boundary_seek( )

This call returns the absolute position where the seek stopped. If the seek goes below 0 the returned value is -1. If the seek goes past the end the returned value is the size of the buffer.

bool32 app->buffer_read_range( )

This call returns non-zero if the read succeeds.

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.

bool32 app->buffer_replace_range( )

This call returns non-zero if the replacement succeeds.

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.

bool32 app->buffer_set_setting( )

bool32 app->buffer_auto_indent( )

This call returns non-zero when the call succeeds.

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.

Buffer_Summary app->create_buffer( )

This call returns the summary of the created buffer.

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.

bool32 app->save_buffer( )

This call returns non-zero on success.

bool32 app->kill_buffer( )

This call returns non-zero on success.

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.

View_Summary app->get_view_first( )

This call returns the summary of the first view in a view loop.

This call begins a loop across all the open views. If the view summary returned is a null summary, the loop is finished. Views should not be closed or opened durring a view loop.

void app->get_view_next( )

This call steps a view summary to the next view in the global view order. If the view outputted does not exist, the loop is finished. Views should not be closed or opened durring a view loop.

View_Summary app->get_view( )

This call returns a summary that describes the indicated view if it is open and accessible.

View_Summary app->get_active_view( )

This call returns a summary that describes the active view.

bool32 app->set_active_view( )

This call returns non-zero on success.

If the given view is open, it is set as the active view, and takes subsequent commands and is returned from get_active_view.

bool32 app->view_set_setting( )

This call returns non-zero on success.

bool32 app->view_set_split_proportion( )

This call returns non-zero on success.

bool32 app->view_compute_cursor( )

This call returns non-zero on success.

Computes a Full_Cursor for the given seek position with no side effects.

bool32 app->view_set_cursor( )

This call returns non-zero on success.

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

bool32 app->view_set_mark( )

This call returns non-zero on success.

This call sets the the view's mark position.

bool32 app->view_set_highlight( )

This call returns non-zero on success.

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.

bool32 app->view_set_buffer( )

This call returns non-zero on success.

On success view_set_buffer sets the specified view's current buffer and cancels and dialogue shown in the view and displays the file.

bool32 app->view_post_fade( )

This call returns non-zero on success.

User_Input app->get_user_input( )

This call returns a User_Input that describes a user input event.

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.

User_Input app->get_command_input( )

This call returns the input that triggered the currently executing command.

Mouse_State app->get_mouse_state( )

This call returns the current mouse state as of the beginning of the frame.

bool32 app->start_query_bar( )

This call returns non-zero on success.

This call tells the active view to begin displaying a "Query_Bar" which is a small GUI element that can overlap a buffer or other 4coder GUI. The contents of the bar can be changed after the call to start_query_bar and the query bar shown by 4coder will reflect the change. Since the bar stops showing when the command exits the only use for this call is in an interactive command that makes calls to get_user_input.

void app->end_query_bar( )

Stops showing the particular query bar specified by the bar parameter.

void app->print_message( )

This call posts a string to the *messages* buffer.

void app->change_theme( )

This call changes 4coder's theme to one of the built in themes.

void app->change_font( )

This call changes 4coder's font to one of the built in fonts.

void app->set_theme_colors( )

For each struct in the array, the slot in the main color pallet specified by the struct's tag is set to the color code in the struct. If the tag value is invalid no change is made to the color pallet.

void app->get_theme_colors( )

For each struct in the array, the color field of the struct is filled with the color from the slot in the main color pallet specified by the tag. If the tag value is invalid the color is filled with black.

int32_t app->directory_get_hot( )

This call returns the size of the string written into the buffer.

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 on the custom side.

File_List app->get_file_list( )

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

void app->free_file_list( )

After this call the file list passed in should not be read or written to.

bool32 app->file_exists( )

This call returns non-zero if and only if the file exists.

bool32 app->directory_cd( )

This call returns non-zero if the call succeeds.

This call succeeds if the new directory exists and the it fits inside the dir buffer. If the call succeeds the dir buffer is filled with the new directory and len is overwritten with the length of the new 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.

bool32 app->get_4ed_path( )

This call returns non-zero on success.

void app->show_mouse_cursor( )

typedef int32_t bool32;

bool32 is an alias name to signal that an integer parameter or field is for true/false vales.

typedef uint32_t int_color;

int_color is an alias name to signal that an integer parameter or field is for a color value, colors are specified as 24 bit integers in 3 channels: 0xRRGGBB.

typedef unsigned char Key_Code;

Key_Code is the alias for key codes including raw codes and codes translated to textual input that takes modifiers into account.

typedef int32_t Buffer_ID;

Buffer_ID is used to name a 4coder buffer. Each buffer has a unique id but when a buffer is closed it's id may be recycled by future, different buffers.

typedef int32_t View_ID;

View_ID is used to name a 4coder view. Each view has a unique id in the range [1,16].

enum Key_Modifier;

A Key_Modifier acts as an index for specifying modifiers in arrays.

enum Command_ID;

A Command_ID is used as a name for commands implemented internally in 4coder.

enum User_Input_Type_ID;

User_Input_Type_ID specifies a type of user input event.

enum Event_Message_Type_ID;

Event_Message_Type_ID is a part of an unfinished feature.

enum Buffer_Setting_ID;

A Buffer_Setting_ID names a setting in a buffer.

enum View_Setting_ID;

A View_Setting_ID names a setting in a view.

enum Mouse_Cursor_Show_Type;

A Mouse_Cursor_Show_Type value specifes a mode for 4coder to handle the mouse cursor.

enum Key_Modifier_Flag;

A Key_Modifier_Flag field is used to specify a specific state of modifiers. Flags can be combined with bit or to specify a state with multiple modifiers.

enum Buffer_Create_Flag;

A Buffer_Create_Flag field specifies how a buffer should be created.

enum Buffer_Kill_Flag;

A Buffer_Kill_Flag field specifies how a buffer should be killed.

enum Access_Flag;

An Access_Flag field specifies what sort of permission you grant to an access call. An access call is usually one the returns a summary struct. If a 4coder object has a particular protection flag set and the corresponding bit is not set in the access field, that 4coder object is hidden. On the other hand if a protection flag is set in the access parameter and the object does not have that protection flag, the object is still returned from the access call.

enum Seek_Boundary_Flag;

A Seek_Boundary_Flag field specifies a set of "boundary" types used in seeks for the beginning or end of different types of words.

enum Command_Line_Input_Flag;

A Command_Line_Input_Flag field specifies the behavior of a call to a command line interface.

enum Auto_Indent_Flag;

An Auto_Indent_Flag field specifies the behavior of an auto indentation operation.

enum Set_Buffer_Flag;

A Set_Buffer_Flag field specifies the behavior of an operation that sets the buffer of a view.

enum Input_Type_Flag;

A Input_Type_Flag field specifies a set of input event types.

union Generic_Command {
};

Generic_Command acts as a name for a command, and can name an internal command or a custom command.

struct Key_Event_Data {
};

Key_Event_Data describes a key event, including the translation to a character, the translation to a character ignoring the state of caps lock, and an array of all the modifiers that were pressed at the time of the event.

struct Mouse_State {
};

Mouse_State describes an entire mouse state complete with the position, left and right button states, the wheel state, and whether or not the mouse if in the window.

union Range {
};

Range describes an integer range typically used for ranges within a buffer. Ranges tend are usually not passed as a Range struct into the API, but this struct is used to return ranges. Throughout the API ranges are thought of in the form [min,max

struct File_Info {
};

File_Info describes the name and type of a file.

struct File_List {
};

File_List is a list of File_Info structs.

struct Buffer_Identifier {
};

Buffer_Identifier acts as a loosely typed description of a buffer that can either be a name or an id. If the

struct Buffer_Summary {
};

Buffer_Summary acts as a handle to a buffer and describes the state of the buffer.

struct View_Summary {
};

View_Summary acts as a handle to a view and describes the state of the view.

struct User_Input {
};

User_Input describes a user input event which can be either a key press or mouse event.

struct Query_Bar {
};

Query_Bar is a struct used to store information in the user's control that will be displayed as a drop down bar durring an interactive command.

struct Event_Message {
};

This feature is not implemented.

struct Theme_Color {
};

Theme_Color stores a style tag/color pair, for the purpose of setting and getting colors in the theme .