From: Andre Noll Date: Sun, 16 Mar 2014 11:09:01 +0000 (+0100) Subject: Doxify para_gui. X-Git-Tag: v0.5.3~12^2~4 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=ccd288cee4d15e54640d87c1451b46c3ff0e2591 Doxify para_gui. Now that para_gui is in a much better shape, let's make it a first class citizen and document all public functions and data structures. --- diff --git a/Doxyfile b/Doxyfile index 00cb6cc9..239cd262 100644 --- a/Doxyfile +++ b/Doxyfile @@ -619,7 +619,6 @@ EXCLUDE_SYMLINKS = NO # for example use the pattern */test/* EXCLUDE_PATTERNS = *.cmdline.* \ - gui* \ gcc-compat.h \ fade.c \ *_command_list.h \ diff --git a/gui.c b/gui.c index 4f536c5d..9b7c2f99 100644 --- a/gui.c +++ b/gui.c @@ -35,7 +35,9 @@ static struct gui_window { bool needs_update; } top, bot, sb, in, sep; +/** How many lines of output to remember. */ #define RINGBUFFER_SIZE 512 + struct rb_entry { char *msg; size_t len; @@ -51,10 +53,11 @@ static int exec_fds[2] = {-1, -1}; static struct gui_args_info conf; static int loglevel; +/** Type of the process currently being executed. */ enum exec_status { - EXEC_IDLE, /* no command running */ - EXEC_DCMD, /* para or display command running */ - EXEC_XCMD, /* external command running */ + EXEC_IDLE, /**< No process running. */ + EXEC_DCMD, /**< para or display process running. */ + EXEC_XCMD, /**< External process running. */ }; /** @@ -132,6 +135,7 @@ struct status_task { int fd; }; +/** Stdout/stderr of the executing process is read in chunks of this size. */ #define COMMAND_BUF_SIZE 32768 struct exec_task { @@ -497,6 +501,7 @@ static __printf_2_3 void curses_log(int ll, const char *fmt,...) vfprintf(stderr, fmt, ap); va_end(ap); } +/** The log function of para_gui, always set to curses_log(). */ __printf_2_3 void (*para_log)(int, const char*, ...) = curses_log; static void shutdown_curses(void) @@ -1449,6 +1454,31 @@ static int setup_tasks_and_schedule(void) return schedule(&sched); } +/** + * The main function of para_gui. + * + * \param argc Usual argument count. + * \param argv Usual argument vector. + * + * After initialization para_gui registers the following tasks to the paraslash + * scheduler: status, exec, signal, input. + * + * The status task executes the para_audioc stat command to obtain the status + * of para_server and para_audiod, and displays this information in the top + * window of para_gui. + * + * The exec task is responsible for printing the output of the currently + * running executable to the bottom window. + * + * The signal task performs suitable actions according to any signals received. + * For example it refreshes all windows on terminal size changes and resets the + * terminal on \p SIGTERM. + * + * The input task reads single key strokes from stdin. For each key pressed, it + * executes the command handler associated with this key. + * + * \return \p EXIT_SUCCESS or \p EXIT_FAILURE. + */ int main(int argc, char *argv[]) { gui_cmdline_parser(argc, argv, &conf); /* exits on errors */ diff --git a/gui.h b/gui.h index 13f50806..eabfd3c7 100644 --- a/gui.h +++ b/gui.h @@ -6,32 +6,73 @@ /** \file gui.h symbols used by gui and gui_theme */ +/** How to display one status item. */ struct stat_item_data { - const char *prefix, *postfix; - unsigned x, y, len; - int fg, bg, align; + const char *prefix; /**< Text to print before the item content. */ + const char *postfix; /**< Text to print after item content. */ + unsigned x; /**< Horizontal start coordinate for this item. */ + unsigned y; /**< Vertical start coordinate for this item. */ + unsigned len; /**< Item width, including \a prefix and \a postfix. */ + int fg; /**< Foreground color. */ + int bg; /**< Background color. */ + int align; /**< How to align this item. */ }; +/** Theme definition. */ struct gui_theme { + /** Printed at startup. */ const char *name; + /** Also printed at startup. */ const char *author; - int sb_fg, sb_bg; - int cmd_fg, cmd_bg; - int output_fg, output_bg; - int msg_fg, msg_bg; - int err_msg_fg, err_msg_bg; - int sep_fg, sep_bg; + /** Foreground color of the status bar. */ + int sb_fg; + /** Background color of the status bar. */ + int sb_bg; + /** Foreground for the name and args of the executing process. */ + int cmd_fg; + /** Background for the name and args of the executing process. */ + int cmd_bg; + /** Foreground color for stdout of the executing process. */ + int output_fg; + /** Background color for stdout of the executing process. */ + int output_bg; + /** Foreground color for log messages of moderate severity. */ + int msg_fg; + /** Background color for log messages of moderate severity. */ + int msg_bg; + /** Foreground color for severe log messages. */ + int err_msg_fg; + /** Background color for severe log messages. */ + int err_msg_bg; + /** Foreground color for the separator line. */ + int sep_fg; + /** Background color for the separator line. */ + int sep_bg; + /** The character for the separator line. */ char sep_char; - int default_fg, default_bg; - - int top_lines_default, top_lines_min; - int lines_min, cols_min; + /** Default foreground color, see assume_default_colors(3). */ + int default_fg; + /** Default background color. */ + int default_bg; + /** Default number of lines of the top window. */ + int top_lines_default; + /** Minimal admissible number of lines to display the top window. */ + int top_lines_min; + /** Minimal admissible number of lines to display this theme. */ + int lines_min; + /** Minimal admissible number of columns to display this theme. */ + int cols_min; + /** Individual status item properties. */ struct stat_item_data data[NUM_STAT_ITEMS]; }; void theme_init(const char *name, struct gui_theme *t); void theme_prev(struct gui_theme *t); void theme_next(struct gui_theme *t); + +/** Status item text should be left-aligned. */ #define LEFT 1 +/** Status item text should be right-aligned. */ #define RIGHT 2 +/** Status item text should be displayed centered. */ #define CENTER 3 diff --git a/gui_theme.c b/gui_theme.c index 3c9886d1..b13fdf9f 100644 --- a/gui_theme.c +++ b/gui_theme.c @@ -4,6 +4,8 @@ * Licensed under the GPL v2. For licencing details see COPYING. */ +/** \file gui_theme.c Theme definitions. */ + #include "para.h" #include "gui.h" #include @@ -368,6 +370,7 @@ static struct theme_description themes[] = { }, }; +/** Number of elements in the \a themes array. */ #define NUM_THEMES (ARRAY_SIZE(themes)) static int current_theme_num; @@ -384,6 +387,14 @@ static void set_theme(int num, struct gui_theme *t) PARA_NOTICE_LOG("theme: %s\n", t->name); } +/** + * Initialize a theme. + * + * \param name Name of the theme to be initialized. + * \param t The function fills out this structure. + * + * This function exits if there is no theme called \a name. + */ void theme_init(const char *name, struct gui_theme *t) { int i; @@ -399,11 +410,29 @@ void theme_init(const char *name, struct gui_theme *t) exit(EXIT_FAILURE); } +/** + * Activate the previous available theme. + * + * \param t Theme definition is stored here. + * + * This picks the theme that comes before the currently active one, or the last + * availabe theme, if the current one is the first. + * + * \sa \ref theme_next(). + */ void theme_prev(struct gui_theme *t) { return set_theme(++current_theme_num, t); } +/** + * Activate the next available theme. + * + * \param t Theme definition is stored here. + * + * This works exacly as theme_prev() but cycles forwards through the list of + * available themes. + */ void theme_next(struct gui_theme *t) { return set_theme(--current_theme_num, t);