-
Notifications
You must be signed in to change notification settings - Fork 1
API reference
int aug_log(const char *format, ...)
Log a message to the debug log file according to format. Returns the number of
characters printed or a negative value on error.
int aug_keyname_to_key(const char *keyname, uint32_t *ch)
Convert keyname (a string such as "^R" or "^C") to its utf-32 value. returns 0
if a value was found for the string and returns non-zero if the value was not found.
void aug_unload()
Unload the calling plugin. Do not call this during aug_plugin_init or aug_plugin_free.
This function can be called by a plugin created thread in order to unload itself from
aug. This API call will first call the plugin's free function from a newly spawned
thread (in this way the plugin can fully cleanup all its resources, including its
joinable threads, even the one that made the call to unload). after this it will delete
the plugin from its list of active plugins. Since this API call does everything from a
detached thread, this function will return immediately.
int aug_conf_val(const char *name, const char *key, const char **val)
Call this function to query for a user specified configuration value parsed from the
configuration file. name is the name of the plugin, key is name of the
configuration variable, and val is a pointer to the location of the variable value. If
the return value is zero the key was successfully found. Note that you can pass the
name of a different plugin to find out configuration info of other plugins or to find
out if a specific plugin is loaded or not.
void aug_callbacks(const struct aug_plugin_cb *callbacks, const struct aug_plugin_cb **prev)
Get or set the callbacks for this plugin. If callbacks is NULL, the current set of
callbacks will not be changed. If prev is NULL, the previous set of callbacks will
not be returned.
int aug_key_bind(uint32_t ch, aug_on_key_fn on_key, void *user)
The user can configure a global command key to use as a prefix and plugins can bind to
this key + some extension. For example, the user might set ^A as the command key, and
a plugin might bind to ^A n by passing ch = 0x6e. If the return value is non-zero,
the key is reserved or already bound. on_key is a function pointer to the callback
to be invoked when the user types the command key plus the extension key ch. user
is an arbitrary void pointer to be passed to the callback function.
int aug_key_unbind(uint32_t ch)
A call to key_bind should be matched by a call to key_unbind as soon as the plugin no
longer needs to use the binding or when aug_plugin_free function is called.
void aug_lock_screen()
void aug_unlock_screen()
Any ncurses calls should be enclosed between these two calls in order to serialize access
to the ncurses library.
void aug_screen_win_alloc_top(int nlines, void (*window_cb)(WINDOW *win, void *user), void (*free_cb)(WINDOW *win, void *user))
void aug_screen_win_alloc_bot(int nlines, void (*window_cb)(WINDOW *win, void *user), void (*free_cb)(WINDOW *win, void *user))
void aug_screen_win_alloc_left(int ncols, void (*window_cb)(WINDOW *win, void *user), void (*free_cb)(WINDOW *win, void *user))
void aug_screen_win_alloc_right(int ncols, void (*window_cb)(WINDOW *win, void *user), void (*free_cb)(WINDOW *win, void *user))
These allocate an ncurses window object with a height of nlines on the top, bottom, or
with a width of ncols on the left or right of the screen. The callback will be invoked
when the window is allocated for the plugin or the screen is resized (thus reallocating a
window for the plugin). The screen will be locked during this callback, so the plugin must
not make any API calls which lock the screen and may make ncurses calls without calling
aug_lock_screen and aug_unlock_screen. The callback will either provide a window
with at least as much width/height as requested by the screen_win_alloc_* call or if
there is not enough space, the WINDOW pointer will be NULL which means the plugin does not
have access to its window until there is enough free space that the call is invoked with a
non-null window. Call the function with suffix top, bot, left and right for a window on the
top, bottom, left and right respectively.
int aug_screen_win_dealloc(void (*window_cb)(WINDOW *win, void *user))
This function deallocates an allocated top, bottom, left or right window. It returns zero
if the window associated with window_cb was found and deallocated. It returns non-zero
if no window associated with window_cb was found. The relevant *free_cb callback
function will be invoked.
void aug_screen_panel_alloc(int nlines, int ncols, int begin_y, int begin_x, PANEL **panel)
Allocate a panel on top of the main terminal window and on top of all previously allocated
(by this plugin or others) panels and store a reference to it in panel. The panel will
be nlines by ncols and start at ( begin_y, begin_x ).
void aug_screen_panel_dealloc(PANEL *panel)
Deallocate panel which was previously allocated by aug_screen_panel_alloc.
void aug_screen_panel_size(int *size)
Modifies size to the number of VISIBLE panels. The API can not currently tell a
plugin how many panels (visible and invisible) are allocated.
void aug_screen_panel_update()
Call this function instead of calling update_panels() from the panels library. This
function does not engage any locks so aug_lock_screen and aug_unlock_screen
should be used to ensure these calls are made safely. In the case of API callbacks
where the screen is already locked, this function can be called without using the
aug_lock_screen/aug_unlock_screen API calls.
void aug_screen_doupdate()
Call this instead of calling doupdate() from the ncurses library. As with
aug_screen_panel_update above, this does not engage any locks.
void aug_primary_term_damage(size_t col_start, size_t col_end, size_t row_start, size_t row_end)
Mark for redrawing the areas of the screen described by the rectangle given by
col_start, col_end, row_start and row_end. As with aug_screen_doupdate
and aug_screen_panel_update, this API call does not use locks, so it must be enclosed
within calls to aug_lock_screen and aug_unlock_screen or it must be called from
within a plugin callback.
void aug_terminal_new(struct aug_terminal_win *twin, char *const *argv, void **terminal)
Fork a child process according to argv and allocate a terminal attached to the child.
twin must point to a window that will be associated with the terminal. terminal
will be assigned to the result and must be passed to other terminal_* API calls.
void aug_terminal_delete(void *terminal)
Delete a previously allocated terminal. This will not clear or destroy the window
(twin from above) or actually kill the child process, it will simply deallocate
memory resources. If the child should be killed, use terminal_pid to get the PID
of the process and send it a signal before calling this function. Obviously, do not
call any other API call with terminal after deleting it (for example, one
thread deletes the terminal and another is still writing into it).
pid_t aug_terminal_pid(const void *terminal)
Returns the process id of the child process spawned for terminal.
int aug_terminal_terminated(const void *terminal)
Returns 0 if the process associated with the terminal has not terminated, otherwise
non-zero is returned.
void aug_terminal_run(void *terminal)
This is the I/O loop for terminal, it watches the pty file descriptor and writes
to/refreshes the ncurses window when appropriate. You will likely create a thread
specifically for the purpose of calling this function, as this will not return until
the child process has exited.
NOTE: you must ensure this function has exited before calling aug_terminal_delete
on terminal. Probably the cleanest way to cleanup terminal is to kill the
child process and join the thread that called this function (this function will
return when the child process exits) after joining the thread you can free the memory
resources by passing terminal to aug_terminal_delete.
size_t aug_terminal_input(void *terminal, const uint32_t *data, int n)
size_t aug_terminal_input_chars(void *terminal, const char *data, int n)
Write input characters to terminal. Characters passed into this function are the
input/keystrokes into terminal (just as if someone had typed them). These functions
return the number of characters that were written to the terminal (there is a limit to
number of characters that can be written at any given time; call this function
repeatedly in a loop until it has written everything).
The first function accepts native UTF-32 in data and the second function accepts
ascii text in data. n is the number of characters in data.
void aug_terminal_refresh(void *terminal)
Refreshes and flushes the damage of terminal to cause output to the screen. You
probably want to run screen_panel_update and screen_doupdate after calling this
function.
size_t aug_primary_input(const uint32_t *data, int n)
size_t aug_primary_input_chars(const char *data, int n)
Similar to the terminal input API calls, these allow a plugin to write input keys/data
to the primary terminal. This is useful for automating input into the primary terminal.
The first function accepts native UTF-32 in data and the second function accepts
ascii text in data. n is the number of characters in data.
void aug_primary_refresh()
Like the aug_terminal_refresh API call, this flushes terminal damage of the primary
terminal window and then refreshes it.