From: Andre Noll Date: Thu, 12 Jun 2025 21:41:19 +0000 (+0200) Subject: gui X-Git-Url: https://git.tuebingen.mpg.de/?a=commitdiff_plain;h=34ee9450abca54347ec3f78792d87f130137d092;p=paraslash.git gui --- diff --git a/error.h b/error.h index 971d3e7f..7f540555 100644 --- a/error.h +++ b/error.h @@ -2,7 +2,6 @@ /** \file error.h List of error codes and messages. */ -/** \cond para_error */ /** Codes and messages. */ #define PARA_ERRORS \ PARA_ERROR(SUCCESS, "success"), \ diff --git a/gui.c b/gui.c index 81385301..bb323084 100644 --- a/gui.c +++ b/gui.c @@ -1,6 +1,25 @@ /* Copyright (C) 1998 Andre Noll , see file COPYING. */ -/** \file gui.c Curses-based interface for paraslash. */ +/** \file gui.c Curses-based user interface. + * + * This file contains the bulk of the source code of para_gui(1), including + * main(). Another related source file is \ref gui_theme.c, which contains + * the theme definitions. + * + * para_gui(1) employs the scheduler to perform I/O on various file descriptors + * without threading. It does not use the buffer tree API, though. + * + * At startup the stat subcommand of para_audioc(1) is executed to obtain + * status information about para_server(1) and para_audiod(1). Moreover, + * the program runs arbitrary user-defined programs via configurable key + * bindings. The helper functions of \ref exec.c are called to execute both + * types of programs. + * + * The program also maintains a simple ring buffer, implemented in \ref + * ringbuffer.c, to remember recent command output. + */ + +/** \cond doxygen_ignore */ #include #include @@ -21,7 +40,6 @@ #include "sched.h" #include "signal.h" -/** Array of error strings. */ DEFINE_PARA_ERRLIST; static struct lls_parse_result *cmdline_lpr, *lpr; @@ -40,7 +58,7 @@ static struct gui_window { bool needs_update; } top, bot, sb, in, sep; -/** How many lines of output to remember. */ +/* How many lines of output to remember. */ #define RINGBUFFER_SIZE 512 struct rb_entry { @@ -55,18 +73,18 @@ static pid_t exec_pid; static int exec_fds[2] = {-1, -1}; static int loglevel; -/** Type of the process currently being executed. */ +/* Type of the process currently being executed. */ enum exec_status { EXEC_IDLE, /**< No process running. */ EXEC_DCMD, /**< para or display process running. */ EXEC_XCMD, /**< External process running. */ }; -/** +/* * Codes for various colors. * - * Each status item has its own color pair. The ones defined here start at a - * higher number so that they do not overlap with these. + * Each status item has its own color pair. The enumeration items defined here + * start at a higher number so that they do not overlap with the status items. */ enum gui_color_pair { COLOR_STATUSBAR = NUM_STAT_ITEMS + 1, @@ -138,7 +156,7 @@ struct status_task { int fd; }; -/** Stdout/stderr of the executing process is read in chunks of this size. */ +/* Stdout/stderr of the executing process is read in chunks of this size. */ #define COMMAND_BUF_SIZE 32768 struct exec_task { @@ -180,7 +198,7 @@ static int get_num_cols(struct gui_window *w) return cols; } -/** Number of lines of the window are occupied by an output line. */ +/* Number of lines of the window are occupied by an output line. */ #define NUM_LINES(len) (1 + (len) / get_num_cols(&bot)) /* isendwin() returns false before initscr() was called */ @@ -361,7 +379,8 @@ static int first_visible_rbe(unsigned *lines) } /* -returns number of first visible rbe, *lines is the number of lines drawn. + * Returns the number of the first visible rbe. After the call, *lines is + * the number of lines drawn. */ static int draw_top_rbe(unsigned *lines) { @@ -496,7 +515,7 @@ static __printf_2_3 void curses_log(int ll, const char *fmt,...) va_end(ap); } -/** The log function of para_gui, always set to curses_log(). */ +/* The log function of para_gui, always set to curses_log(). */ __printf_2_3 void (*para_log)(int, const char *, ...) = curses_log; /* Call endwin() to reset the terminal into non-visual mode. */ @@ -1450,11 +1469,12 @@ static void handle_help_flags(void) exit(EXIT_SUCCESS); } -/** +/** \endcond + * * The main function of para_gui. * - * \param argc Usual argument count. - * \param argv Usual argument vector. + * \param argc Options are defined in the gui lopsub suite. + * \param argv The gui suite defines no subcommands. * * After initialization para_gui registers the following tasks to the paraslash * scheduler: status, exec, signal, input. @@ -1473,7 +1493,7 @@ static void handle_help_flags(void) * 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. + * \return EXIT_SUCCESS or EXIT_FAILURE. */ int main(int argc, char *argv[]) { diff --git a/play.c b/play.c index d1cb5983..05dcaa27 100644 --- a/play.c +++ b/play.c @@ -1,6 +1,6 @@ /* Copyright (C) 2012 Andre Noll , see file COPYING. */ -/** \file play.c Paraslash's standalone player +/** \file play.c Standalone command line player. * * para_play(1) is an interactive tool to play audio files in a terminal. * It employs the buffer tree API to link together the afh receiver, a @@ -8,11 +8,10 @@ * all supported audio formats. * * Interactive command line editing is based on the API defined in \ref - * interactive.h. Subcommands of para_play(1) are realized as lopsub - * subcommands. + * interactive.h. */ -/** \cond */ +/** \cond doxygen_ignore */ #include #include @@ -1187,11 +1186,10 @@ static int play_post_monitor(__a_unused struct sched *s, __a_unused void *contex * * The main function of para_play(1). * - * \param argc Command line options are parsed by the lopsub library. + * \param argc Options are defined in the play lopsub suite. * - * \param argv Options are defined in the lopsub suite file of the source - * tree (not part of the doxygen system). The suite file also contains the - * definitions of the various subcommands (stop, pause, etc.). + * \param argv Subcommands (stop, pause, play, etc.) are realized as lopsub + * subcommands, and these are defined in the play suite file. * * para_play(1) distributes its work by submitting various tasks to the * paraslash scheduler. The receiver, filter and writer tasks, which are used