From 8cfe7e026ff6bcde9b12b43092b854bfdaa2d848 Mon Sep 17 00:00:00 2001 From: Kalle Olavi Niemitalo Date: Fri, 27 Jul 2007 16:50:37 +0300 Subject: [PATCH] Doxygenate src/terminal/ --- src/terminal/color.c | 25 +++++--- src/terminal/color.h | 25 ++++---- src/terminal/draw.c | 16 +++-- src/terminal/draw.h | 81 +++++++++++++----------- src/terminal/event.c | 16 ++--- src/terminal/event.h | 69 +++++++++++++-------- src/terminal/hardio.c | 3 +- src/terminal/itrm.h | 64 +++++++++---------- src/terminal/kbd.c | 130 ++++++++++++++++++++------------------- src/terminal/kbd.h | 42 ++++++------- src/terminal/mouse.c | 13 ++-- src/terminal/palette.inc | 49 ++++++++------- src/terminal/screen.c | 122 +++++++++++++++++++++++------------- src/terminal/screen.h | 28 ++++----- src/terminal/tab.c | 13 ++-- src/terminal/terminal.c | 3 +- src/terminal/terminal.h | 113 ++++++++++++++++++---------------- src/terminal/window.c | 5 +- src/terminal/window.h | 24 ++++---- 19 files changed, 468 insertions(+), 373 deletions(-) diff --git a/src/terminal/color.c b/src/terminal/color.c index 8112628da..e0e5b7158 100644 --- a/src/terminal/color.c +++ b/src/terminal/color.c @@ -1,4 +1,5 @@ -/* Terminal color composing. */ +/** Terminal color composing. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -51,11 +52,12 @@ color_distance(const struct rgb *c1, const struct rgb *c2) #define RGB_HASH_SIZE 4096 #define HASH_RGB(color, l) ((RGBCOLOR(color) + (l)) & (RGB_HASH_SIZE - 1)) -/* Initialize a rgb struct from a color_T */ +/** Initialize a rgb struct from a color_T + * @relates rgb */ #define INIT_RGB(color) \ { RED_COLOR(color), GREEN_COLOR(color), BLUE_COLOR(color) } -/* Locates the nearest terminal color. */ +/** Locates the nearest terminal color. */ static inline unsigned char get_color(color_T color, const struct rgb *palette, int level) { @@ -109,9 +111,9 @@ get_color(color_T color, const struct rgb *palette, int level) #undef GREEN_COLOR_MASK #undef BLUE_COLOR_MASK -/* Controls what color ranges to use when setting the terminal color. */ -/* TODO: Part of the 256 color palette is gray scale, maybe we could experiment - * with a grayscale mode. ;) --jonas */ +/** Controls what color ranges to use when setting the terminal color. + * @todo TODO: Part of the 256 color palette is gray scale, maybe we + * could experiment with a grayscale mode. ;) --jonas */ enum palette_range { PALETTE_FULL = 0, PALETTE_HALF, @@ -173,7 +175,8 @@ static const struct color_mode_info *const color_modes[] = { * only if CONFIG_TRUE_COLOR is not defined. */ /* COLOR_MODE_TRUE_COLOR */ &color_mode_16, }; -/* Get a compile-time error if the array has the wrong size. */ +/** Get a compile-time error if the ::color_modes array has the wrong + * size. */ typedef int assert_enough_color_modes[ (sizeof(color_modes) / sizeof(color_modes[0]) == COLOR_MODES) ? 1 : -1]; @@ -191,9 +194,11 @@ typedef int assert_enough_color_modes[ * * Bright colors will be rendered bold. */ -/* This table is based mostly on wild guesses of mine. Feel free to +/** Map foreground colors to more visible ones on various backgrounds. + * Use like: fg = fg_color[fg][bg]; + * + * This table is based mostly on wild guesses of mine. Feel free to * correct it. --pasky */ -/* Indexed by [fg][bg]->fg: */ static const unsigned char fg_color[16][8] = { /* bk r gr br bl m c w */ @@ -231,7 +236,7 @@ static const unsigned char fg_color[16][8] = { { 15, 15, 15, 15, 15, 15, 15, 15 }, }; -/* When determining wether to use negative image we make the most significant +/* When determining whether to use negative image we make the most significant * be least significant. */ #define CMPCODE(c) (((c) << 1 | (c) >> 2) & TERM_COLOR_MASK) #define use_inverse(bg, fg) CMPCODE(fg & TERM_COLOR_MASK) < CMPCODE(bg) diff --git a/src/terminal/color.h b/src/terminal/color.h index 5ab55bb8a..4ce8d31b2 100644 --- a/src/terminal/color.h +++ b/src/terminal/color.h @@ -21,26 +21,27 @@ struct screen_char; #define TERM_COLOR_FOREGROUND_16(color) ((color)[0] & TERM_COLOR_MASK) #define TERM_COLOR_BACKGROUND_16(color) (((color)[0] >> 4) & TERM_COLOR_MASK) -/* Bit flags to control how the colors are handled. */ +/** Bit flags to control how the colors are handled. */ enum color_flags { - /* Use a decreased color range. */ + /** Use a decreased color range. */ COLOR_DECREASE_LIGHTNESS = 1, - /* Mangle the color to stand out if attributes like underline are set. - * Useful for terminals that doesn't support these attributes. */ + /** Mangle the color to stand out if attributes like underline are set. + * Useful for terminals that don't support these attributes. */ COLOR_ENHANCE_UNDERLINE = 2, - /* Adjust the forground color to be more readable by increasing the + /** Adjust the foreground color to be more readable by increasing the * contrast. */ COLOR_INCREASE_CONTRAST = 4, - /* Adjust the contrast if the back- and foregroundcolor is equal. + /** Adjust the contrast if the back- and foregroundcolor is equal. * If inverting should be done also pass the latter flag. */ COLOR_ENSURE_CONTRAST = 8, COLOR_ENSURE_INVERTED_CONTRAST = 16, }; -/* These numbers are used in the terminal._template_.colors and +/** How many colors the terminal supports. + * These numbers are used in the terminal._template_.colors and * document.dump.color_mode options. They should be kept stable so * that configuration files are portable between ELinks versions. * Any unsupported modes should be treated as COLOR_MODE_16. @@ -65,10 +66,12 @@ enum color_mode { inline void set_term_color16(struct screen_char *schar, enum color_flags flags, unsigned char fg, unsigned char bg); -/* Mixes the color pair and attributes to a terminal text color. */ -/* If @flags has masked in the COLOR_INCREASE_CONTRAST the foreground color will - * be adjusted. */ -/* XXX: @schar may not be NULL and is modified adding stuff like boldness. */ +/** Mixes the color pair and attributes to a terminal text color. + * If @a flags has masked in the ::COLOR_INCREASE_CONTRAST the + * foreground color will be adjusted. + * + * XXX: @a schar may not be NULL and is modified adding stuff like + * boldness. */ void set_term_color(struct screen_char *schar, struct color_pair *pair, enum color_flags flags, enum color_mode mode); diff --git a/src/terminal/draw.c b/src/terminal/draw.c index dae5d473c..93382b4de 100644 --- a/src/terminal/draw.c +++ b/src/terminal/draw.c @@ -1,4 +1,5 @@ -/* Public terminal drawing API. Frontend for the screen image in memory. */ +/** Public terminal drawing API. Frontend for the screen image in memory. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -15,7 +16,7 @@ #include "util/color.h" #include "util/box.h" -/* Makes sure that @x and @y are within the dimensions of the terminal. */ +/** Makes sure that @a x and @a y are within the dimensions of the terminal. */ #define check_range(term, x, y) \ do { \ int_bounds(&(x), 0, (term)->width - 1); \ @@ -104,7 +105,7 @@ draw_char_color(struct terminal *term, int x, int y, struct color_pair *color) set_screen_dirty(term->screen, y, y); } -/* The data parameter here is like screen_char.data: UCS-4 if the +/*! The @a data parameter here is like screen_char.data: UCS-4 if the * charset of the terminal is UTF-8 (possible only if CONFIG_UTF8 is * defined), and a byte otherwise. */ void @@ -139,8 +140,8 @@ draw_char_data(struct terminal *term, int x, int y, unsigned char data) set_screen_dirty(term->screen, y, y); } -/* Updates a line in the terms screen. */ -/* When doing frame drawing @x can be different than 0. */ +/*! Used by viewer to copy over a document. + * When doing frame drawing @a x can be different than 0. */ void draw_line(struct terminal *term, int x, int y, int l, struct screen_char *line) { @@ -258,8 +259,10 @@ draw_border(struct terminal *term, struct box *box, } #ifdef CONFIG_UTF8 -/* Checks cells left and right to the box for broken double-width chars. +/** Checks cells left and right to the box for broken double-width chars. * Replace it with UCS_ORPHAN_CELL. + * + * @verbatim * 1+---+3 * 1|box|##4 * 1| |##4 @@ -267,6 +270,7 @@ draw_border(struct terminal *term, struct box *box, * 1+---+##4 * 2#####4 * 1,2,3,4 - needs to be checked, # - shadow , +,-,| - border + * @endverbatim */ void fix_dwchar_around_box(struct terminal *term, struct box *box, int border, diff --git a/src/terminal/draw.h b/src/terminal/draw.h index 83405a289..988a27b00 100644 --- a/src/terminal/draw.h +++ b/src/terminal/draw.h @@ -7,6 +7,7 @@ struct color_pair; struct box; struct terminal; +/** How many bytes we need for the colors of one character cell. */ #if defined(CONFIG_TRUE_COLOR) /* 0, 1, 2 - rgb foreground; 3, 4, 5 - rgb background */ #define SCREEN_COLOR_SIZE 6 @@ -17,8 +18,10 @@ struct terminal; #define SCREEN_COLOR_SIZE 1 #endif -/* All attributes should fit inside an unsigned char. */ -/* XXX: The bold mask is used as part of the color encoding. */ +/** Attributes of a character on the screen. + * All attributes should fit inside an unsigned char. + * + * XXX: The bold mask is used as part of the color encoding. */ enum screen_char_attr { SCREEN_ATTR_UNSEARCHABLE = 0x01, SCREEN_ATTR_BOLD = 0x08, @@ -28,41 +31,44 @@ enum screen_char_attr { SCREEN_ATTR_FRAME = 0x80, }; -/* One position in the terminal screen's image. */ +/** One position in the terminal screen's image. */ struct screen_char { - /* Contains either character value or frame data. - * If @attr includes SCREEN_ATTR_FRAME, then @data is enum - * border_char; otherwise, @data is a character value. - * If the charset of the terminal is UTF-8 (which is possible - * only if CONFIG_UTF8 is defined), then the character value - * is in UCS-4; otherwise, the charset is assumed to be - * unibyte, and the character value is a byte in that - * charset. */ + /** Contains either character value or frame data. + * - If #attr includes ::SCREEN_ATTR_FRAME, then @c data is + * enum border_char. + * - Otherwise, if the charset of the terminal is UTF-8, then + * @c data is a character value in UCS-4. This is possible + * only if CONFIG_UTF8 is defined. + * - Otherwise, the charset of the terminal is assumed to be + * unibyte, and @c data is a byte in that charset. */ #ifdef CONFIG_UTF8 unicode_val_T data; #else unsigned char data; #endif /* CONFIG_UTF8 */ - /* Attributes are screen_char_attr bits. */ + /** Attributes are ::screen_char_attr bits. */ unsigned char attr; - /* The fore- and background color. */ + /** The fore- and background color. */ unsigned char color[SCREEN_COLOR_SIZE]; }; +/** @relates screen_char */ #define copy_screen_chars(to, from, amount) \ do { memcpy(to, from, (amount) * sizeof(struct screen_char)); } while (0) -/* Linux frame symbols table (it's magically converted to other terminals when - * needed). */ -/* In the screen image, they have attribute SCREEN_ATTR_FRAME; you should drop them - * to the image using draw_border_char(). */ -/* TODO: When we'll support internal Unicode, this should be changed to some - * Unicode sequences. --pasky */ - -/* Codes extracted from twin-0.4.6 GPL project, a Textmode WINdow environment, - * by Massimiliano Ghilardi http://linuz.sns.it/~max/ */ +/** @name Linux frame symbols table. + * It is magically converted to other terminals when needed. + * In the screen image, they have attribute SCREEN_ATTR_FRAME; + * you should drop them to the image using draw_border_char(). + * + * \todo TODO: When we'll support internal Unicode, this should be + * changed to some Unicode sequences. --pasky + * + * Codes extracted from twin-0.4.6 GPL project, a Textmode WINdow environment, + * by Massimiliano Ghilardi http://linuz.sns.it/~max/ + * @{ */ /* Not yet used #define T_UTF_16_BOX_DRAWINGS_LIGHT_VERTICAL 0x2502 @@ -149,6 +155,9 @@ struct screen_char { #define T_CP437_BOX_DRAWINGS_LIGHT_UP_AND_LEFT 0x00D9 #define T_CP437_BOX_DRAWINGS_LIGHT_DOWN_AND_RIGHT 0x00DA +/** @} */ + + #define BD_LIGHT(XXX) T_CP437_BOX_DRAWINGS_LIGHT_##XXX #define BD_DOUBLE(XXX) T_CP437_BOX_DRAWINGS_DOUBLE_##XXX #define BD_MIXED(XXX) T_CP437_BOX_DRAWINGS_##XXX @@ -213,29 +222,29 @@ enum border_cross_direction { BORDER_X_UP }; -/* Extracts a char from the screen. */ +/** Extracts a char from the screen. */ struct screen_char *get_char(struct terminal *, int x, int y); -/* Sets the color of a screen position. */ +/** Sets the color of a screen position. */ void draw_char_color(struct terminal *term, int x, int y, struct color_pair *color); -/* Sets the data of a screen position. */ +/** Sets the data of a screen position. */ #ifdef CONFIG_UTF8 void draw_char_data(struct terminal *term, int x, int y, unicode_val_T data); #else void draw_char_data(struct terminal *term, int x, int y, unsigned char data); #endif /* CONFIG_UTF8 */ -/* Sets the data to @border and of a screen position. */ +/** Sets the data to @a border and of a screen position. */ void draw_border_char(struct terminal *term, int x, int y, enum border_char border, struct color_pair *color); -/* Sets the cross position of two borders. */ +/** Sets the cross position of two borders. */ void draw_border_cross(struct terminal *, int x, int y, enum border_cross_direction, struct color_pair *color); -/* Draws a char. */ +/** Draws a char. */ #ifdef CONFIG_UTF8 void draw_char(struct terminal *term, int x, int y, unicode_val_T data, enum screen_char_attr attr, @@ -246,16 +255,17 @@ void draw_char(struct terminal *term, int x, int y, struct color_pair *color); #endif /* CONFIG_UTF8 */ -/* Draws area defined by @box using the same colors and attributes. */ +/** Draws area defined by @a box using the same colors and attributes. */ void draw_box(struct terminal *term, struct box *box, unsigned char data, enum screen_char_attr attr, struct color_pair *color); -/* Draws a shadow of @width and @height with color @color around @box. */ +/** Draws a shadow of @a width and @a height with color @a color + * around @a box. */ void draw_shadow(struct terminal *term, struct box *box, struct color_pair *color, int width, int height); -/* Draw borders. */ +/** Draw borders. */ void draw_border(struct terminal *term, struct box *box, struct color_pair *color, int width); @@ -264,23 +274,22 @@ void fix_dwchar_around_box(struct terminal *term, struct box *box, int border, int shadow_width, int shadow_height); #endif /* CONFIG_UTF8 */ -/* Draws @length chars from @text. */ +/** Draws @a length chars from @a text. */ void draw_text(struct terminal *term, int x, int y, unsigned char *text, int length, enum screen_char_attr attr, struct color_pair *color); -/* Draws @length chars from @line on the screen. */ -/* Used by viewer to copy over a document. */ +/** Draws @a length chars from @a line on the screen. */ void draw_line(struct terminal *term, int x, int y, int length, struct screen_char *line); -/* Updates the terminals cursor position. When @blockable is set the +/** Updates the terminals cursor position. When @a blockable is set the * block_cursor terminal option decides whether the cursor should be put at the * bottom right corner of the screen. */ void set_cursor(struct terminal *term, int x, int y, int blockable); -/* Blanks the screen. */ +/** Blanks the screen. */ void clear_terminal(struct terminal *); #endif diff --git a/src/terminal/event.c b/src/terminal/event.c index 5922727dd..2030244ed 100644 --- a/src/terminal/event.c +++ b/src/terminal/event.c @@ -1,4 +1,5 @@ -/* Event system support routines. */ +/** Event system support routines. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -33,18 +34,19 @@ #include "viewer/timer.h" -/* Information used for communication between ELinks instances */ +/** Information used for communication between ELinks instances */ struct terminal_interlink { - /* How big the input queue is and how much is free */ + /** How big the input queue is */ int qlen; + /** How much is free */ int qfreespace; - /* UTF8 input key value decoding data. */ + /** UTF-8 input key value decoding data. */ struct { unicode_val_T ucs; int len; unicode_val_T min; - /* Modifier keys from the key event that carried the + /** Modifier keys from the key event that carried the * first byte of the character. We need this because * ELinks sees e.g. ESC U+00F6 as 0x1B 0xC3 0xB6 and * converts it to Alt-0xC3 0xB6, attaching the @@ -52,8 +54,8 @@ struct terminal_interlink { term_event_modifier_T modifier; } utf8; - /* This is the queue of events as coming from the other ELinks instance - * owning the hosting terminal. */ + /** This is the queue of events as coming from the other + * ELinks instance owning the hosting terminal. */ unsigned char input_queue[1]; }; diff --git a/src/terminal/event.h b/src/terminal/event.h index 8599b55c7..9de3ce1e2 100644 --- a/src/terminal/event.h +++ b/src/terminal/event.h @@ -12,6 +12,7 @@ struct terminal; #define MAX_CWD_LEN 256 /* this must be multiple of 8! (alignment problems) */ +/** Type of an event received from a terminal. */ enum term_event_type { EVENT_INIT, EVENT_KBD, @@ -21,34 +22,40 @@ enum term_event_type { EVENT_ABORT, }; +/** An event received from a terminal. This type can be changed + * without breaking interlink compatibility. */ struct term_event { enum term_event_type ev; union { - /* EVENT_MOUSE */ + /** ::EVENT_MOUSE */ struct term_event_mouse mouse; - /* EVENT_KBD */ + /** ::EVENT_KBD */ struct term_event_keyboard keyboard; - /* EVENT_INIT, EVENT_RESIZE, EVENT_REDRAW */ + /** ::EVENT_INIT, ::EVENT_RESIZE, ::EVENT_REDRAW */ struct term_event_size { int width, height; } size; } info; }; +/** An event transferred via the interlink socket. This is quite + * similar to struct term_event but has a different format for + * keyboard events. If you change this type, you can break interlink + * compatibility. */ struct interlink_event { enum term_event_type ev; union { - /* EVENT_MOUSE */ + /* ::EVENT_MOUSE */ struct interlink_event_mouse mouse; - /* EVENT_KBD */ + /* ::EVENT_KBD */ struct interlink_event_keyboard keyboard; - /* EVENT_INIT, EVENT_RESIZE, EVENT_REDRAW */ + /* ::EVENT_INIT, ::EVENT_RESIZE, ::EVENT_REDRAW */ #define interlink_event_size term_event_size struct interlink_event_size size; } info; @@ -79,10 +86,12 @@ set_kbd_term_event(struct term_event *ev, int key, kbd_set(&ev->info.keyboard, key, modifier); } -/* @key can be either an 8-bit byte or a value from enum term_event_special_key. - * In the latter case, this function negates the value, unless it is KBD_UNDEF. - * For example, key == KBD_ENTER results in ev->info.keyboard.key = -KBD_ENTER. - * This mapping keeps the interlink protocol compatible with ELinks 0.11. */ +/** Initialize @c ev as an interlink keyboard event. + * @a key can be either an 8-bit byte or a value from enum + * term_event_special_key. In the latter case, this function negates + * the value, unless it is KBD_UNDEF. For example, key == KBD_ENTER + * results in ev->info.keyboard.key = -KBD_ENTER. This mapping keeps + * the interlink protocol compatible with ELinks 0.11. */ static inline void set_kbd_interlink_event(struct interlink_event *ev, int key, term_event_modifier_T modifier) @@ -126,32 +135,34 @@ set_wh_interlink_event(struct interlink_event *ev, enum term_event_type type, in #define set_resize_interlink_event(ev, w, h) set_wh_interlink_event(ev, EVENT_RESIZE, w, h) -/* This holds the information used when handling the initial connection between - * a dumb and master terminal. */ -/* XXX: We might be connecting to an older ELinks or an older ELinks is +/** This holds the information used when handling the initial + * connection between a dumb and master terminal. + * + * XXX: We might be connecting to an older ELinks or an older ELinks is * connecting to a newer ELinks master so for the sake of compatibility it * would be unwise to just change the layout of the struct. If you do have to * add new members add them at the bottom and use magic variables to * distinguish them when decoding the terminal info. */ struct terminal_info { - struct interlink_event event; /* The EVENT_INIT event */ - unsigned char name[MAX_TERM_LEN]; /* $TERM environment name */ - unsigned char cwd[MAX_CWD_LEN]; /* Current working directory */ - int system_env; /* System info (X, screen) */ - int length; /* Length of @data member */ - int session_info; /* Value depends on @magic */ - int magic; /* Identity of the connector */ + struct interlink_event event; /**< The ::EVENT_INIT event */ + unsigned char name[MAX_TERM_LEN]; /**< $TERM environment name */ + unsigned char cwd[MAX_CWD_LEN]; /**< Current working directory */ + int system_env; /**< System info (X, screen) */ + int length; /**< Length of #data member */ + int session_info; /**< Value depends on #magic */ + int magic; /**< Identity of the connector */ - /* In the master that is connected to all bytes after @data will be - * interpreted as URI string information. */ + /** In the master that is connected to all bytes after @c data + * will be interpreted as URI string information. */ unsigned char data[1]; }; -/* The @data member has to have size of one for portability but it can be - * empty/zero so when reading and writing it we need to ignore the byte. */ +/** The terminal_info.data member has to have size of one for + * portability but it can be empty/zero so when reading and writing it + * we need to ignore the byte. */ #define TERMINAL_INFO_SIZE offsetof(struct terminal_info, data) -/* We use magic numbers to signal the identity of the dump client terminal. +/** We use magic numbers to signal the identity of the dump client terminal. * Magic numbers are composed by the INTERLINK_MAGIC() macro. It is a negative * magic to be able to distinguish the oldest format from the newer ones. */ #define INTERLINK_MAGIC(major, minor) -(((major) << 8) + (minor)) @@ -162,7 +173,8 @@ struct terminal_info { void term_send_event(struct terminal *, struct term_event *); void in_term(struct terminal *); -/* For keyboard events handling */ +/** @name For keyboard events handling + * @{ */ #define get_kbd_key(event) (kbd_get_key(&(event)->info.keyboard)) #define check_kbd_key(event, key) (kbd_key_is(&(event)->info.keyboard, (key))) @@ -171,9 +183,11 @@ void in_term(struct terminal *); #define check_kbd_textinput_key(event) (get_kbd_key(event) >= ' ' && check_kbd_modifier(event, KBD_MOD_NONE)) #define check_kbd_label_key(event) (get_kbd_key(event) > ' ' && (check_kbd_modifier(event, KBD_MOD_NONE) || check_kbd_modifier(event, KBD_MOD_ALT))) +/** @} */ -/* For mouse events handling */ +/** @name For mouse events handling + * @{ */ #define get_mouse_action(event) (mouse_get_action(&(event)->info.mouse)) #define check_mouse_action(event, value) (mouse_action_is(&(event)->info.mouse, (value))) @@ -183,6 +197,7 @@ void in_term(struct terminal *); #define check_mouse_position(event, box) \ mouse_is_in_box(&(event)->info.mouse, box) +/** @} */ #endif /* EL__TERMINAL_EVENT_H */ diff --git a/src/terminal/hardio.c b/src/terminal/hardio.c index 05c31f607..e3f039e32 100644 --- a/src/terminal/hardio.c +++ b/src/terminal/hardio.c @@ -1,4 +1,5 @@ -/* Low-level terminal-suitable I/O routines */ +/** Low-level terminal-suitable I/O routines + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" diff --git a/src/terminal/itrm.h b/src/terminal/itrm.h index 53a15e999..2b5276a5f 100644 --- a/src/terminal/itrm.h +++ b/src/terminal/itrm.h @@ -4,7 +4,7 @@ #define ITRM_OUT_QUEUE_SIZE 16384 -/* Currently, ELinks treats control sequences as text if they are +/** Currently, ELinks treats control sequences as text if they are * longer than ITRM_IN_QUEUE_SIZE bytes. So it should be defined * as greater than the length of any control sequence that ELinks * is expected to receive. These are the longest so far: @@ -15,44 +15,44 @@ struct itrm_queue { unsigned char *data; - /* The amount of data in the queue, in bytes. This may be + /** The amount of data in the queue, in bytes. This may be * less than the amount of memory allocated for the buffer; * struct itrm_queue does not keep track of that, and has * no global policy on whether the buffer can be resized. */ int len; }; -/* Things coming into an itrm, whether from the terminal or from the +/** Things coming into an itrm, whether from the terminal or from the * master. */ struct itrm_in { - /* A file descriptor for the standard input. In some ports, + /** A file descriptor for the standard input. In some ports, * this is the terminal device itself; in others, this is a * pipe from an input thread. In principle, the data format * depends on the terminal. */ int std; - /* In a slave process, a file descriptor for a socket from + /** In a slave process, a file descriptor for a socket from * which it reads data sent by the master process. The other * end of the socket connection is terminal.fdout in the * master process. The format of these data is almost the - * same as could be sent to the terminal (via itrm.out.std), + * same as could be sent to the terminal (via itrm_out.std), * but there are special commands that begin with a null byte. * - * In the master process, @sock is the same as itrm.out.std, + * In the master process, @c sock is the same as itrm_out.std, * but nothing actually uses it. */ int sock; - /* A file descriptor for controlling the standard input. This - * is always the terminal device itself, thus the same as @std + /** A file descriptor for controlling the standard input. This + * is always the terminal device itself, thus the same as #std * in some ports. ELinks doesn't read or write with this file - * descriptor; it only does things like tcsetattr. */ + * descriptor; it only does things like tcsetattr(). */ int ctl; - /* Bytes that have been received from @std but not yet - * converted to events. queue.data is allocated for - * ITRM_IN_QUEUE_SIZE bytes and never resized. The itrm + /** Bytes that have been received from #std but not yet + * converted to events. itrm_queue.data is allocated for + * ::ITRM_IN_QUEUE_SIZE bytes and never resized. The itrm * layer cannot parse control sequences longer than that. - * Anything that modifies queue.len should also call + * Anything that modifies itrm_queue.len should also call * unhandle_itrm_stdin() if the queue becomes full, or * handle_itrm_stdin() if the queue stops being full. * Those functions are internal to kbd.c. */ @@ -62,14 +62,14 @@ struct itrm_in { /* Things going out from an itrm, whether to the terminal or to the * master. */ struct itrm_out { - /* A file descriptor for the standard output. In some ports, + /** A file descriptor for the standard output. In some ports, * this is the terminal device itself; in others, this is a * pipe to an output thread. The data format depends on the * terminal in principle, but this has not yet been * implemented; see bug 96. */ int std; - /* A file descriptor for a pipe or socket to which this + /** A file descriptor for a pipe or socket to which this * process sends input events. The other end of the pipe or * socket connection is terminal.fdin in the master process. * If the connection is from the master process to itself, it @@ -79,36 +79,36 @@ struct itrm_out { * sent. */ int sock; - /* Bytes that should be written to @sock. They will be + /** Bytes that should be written to #sock. They will be * written when select() indicates the write won't block. To * add data here, call itrm_queue_event(), which reallocates - * queue.data if appropriate. The size of this queue is - * unrelated to ITRM_OUT_QUEUE_SIZE. */ + * itrm_queue.data if appropriate. The size of this queue is + * unrelated to ::ITRM_OUT_QUEUE_SIZE. */ struct itrm_queue queue; }; -/* A connection between a terminal and a master ELinks process. +/** A connection between a terminal and a master ELinks process. * Normally, only one struct itrm exists in each master or slave - * process, and the global pointer @ditrm (not declared here) + * process, and the global pointer ::ditrm (not declared here) * points to it. */ struct itrm { - struct itrm_in in; /* Input */ - struct itrm_out out; /* Output */ + struct itrm_in in; /**< Input */ + struct itrm_out out; /**< Output */ - timer_id_T timer; /* ESC timeout timer */ - struct termios t; /* For restoring original attributes */ - void *mouse_h; /* Mouse handle */ - unsigned char *orig_title; /* For restoring window title */ + timer_id_T timer; /**< ESC timeout timer */ + struct termios t; /**< For restoring original attributes */ + void *mouse_h; /**< Mouse handle */ + unsigned char *orig_title; /**< For restoring window title */ - unsigned int blocked:1; /* Whether it was blocked */ - unsigned int altscreen:1; /* Whether to use alternate screen */ - unsigned int touched_title:1; /* Whether the term title was changed */ - /* The @remote flag is not set in regular slave terminals. + unsigned int blocked:1; /**< Whether it was blocked */ + unsigned int altscreen:1; /**< Whether to use alternate screen */ + unsigned int touched_title:1; /**< Whether the term title was changed */ + /*! The @c remote flag is not set in regular slave terminals. * Instead, it means the itrm controls a preexisting terminal, * and windows should not be displayed on the terminal of the * itrm (but see bug 776: the master clears the terminal anyway); * thus the terminal init and done strings are not sent. */ - unsigned int remote:1; /* Whether it is a remote session */ + unsigned int remote:1; /**< Whether it is a remote session */ }; #endif diff --git a/src/terminal/kbd.c b/src/terminal/kbd.c index 67def6adc..f6bc226ff 100644 --- a/src/terminal/kbd.c +++ b/src/terminal/kbd.c @@ -1,4 +1,8 @@ -/* Support for keyboard interface */ +/** Support for keyboard interface + * @file + * + * \todo TODO: move stuff from here to itrm.{c,h} and mouse.{c,h} + */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -37,8 +41,6 @@ #include "util/string.h" #include "util/time.h" -/* TODO: move stuff from here to itrm.{c,h} and mouse.{c,h} */ - struct itrm *ditrm = NULL; static void free_itrm(struct itrm *); @@ -49,7 +51,7 @@ static void handle_itrm_stdin(struct itrm *); static void unhandle_itrm_stdin(struct itrm *); #ifdef CONFIG_DEBUG -/* This hack makes GCC put enum term_event_special_key in the debug +/** This hack makes GCC put enum term_event_special_key in the debug * information even though it is not otherwise used. The const * prevents an unused-variable warning. */ static const enum term_event_special_key dummy_term_event_special_key; @@ -70,9 +72,9 @@ free_all_itrms(void) } -/* A select_handler_T write_func for itrm->out.sock. This is called - * when there is data in itrm->out.queue and it is possible to write - * it to itrm->out.sock. When itrm->out.queue becomes empty, this +/** A select_handler_T write_func for itrm_out.sock. This is called + * when there is data in \c itrm->out.queue and it is possible to write + * it to \c itrm->out.sock. When \c itrm->out.queue becomes empty, this * handler is temporarily removed. */ static void itrm_queue_write(struct itrm *itrm) @@ -154,8 +156,8 @@ kbd_ctrl_c(void) hard_write(fd, seq, sizeof(seq) - 1) -#define INIT_TERMINAL_SEQ "\033)0\0337" /* Special Character and Line Drawing Set, Save Cursor */ -#define INIT_ALT_SCREEN_SEQ "\033[?47h" /* Use Alternate Screen Buffer */ +#define INIT_TERMINAL_SEQ "\033)0\0337" /**< Special Character and Line Drawing Set, Save Cursor */ +#define INIT_ALT_SCREEN_SEQ "\033[?47h" /**< Use Alternate Screen Buffer */ static void send_init_sequence(int h, int altscreen) @@ -171,9 +173,9 @@ send_init_sequence(int h, int altscreen) #endif } -#define DONE_CLS_SEQ "\033[2J" /* Erase in Display, Clear All */ -#define DONE_TERMINAL_SEQ "\0338\r \b" /* Restore Cursor (DECRC) + ??? */ -#define DONE_ALT_SCREEN_SEQ "\033[?47l" /* Use Normal Screen Buffer */ +#define DONE_CLS_SEQ "\033[2J" /**< Erase in Display, Clear All */ +#define DONE_TERMINAL_SEQ "\0338\r \b" /**< Restore Cursor (DECRC) + ??? */ +#define DONE_ALT_SCREEN_SEQ "\033[?47l" /**< Use Normal Screen Buffer */ static void send_done_sequence(int h, int altscreen) @@ -242,7 +244,7 @@ setraw(int fd, struct termios *p) return 0; } -/* Construct the struct itrm of this process, make ditrm point to it, +/** Construct the struct itrm of this process, make ditrm point to it, * set up select() handlers, and send the initial interlink packet. * * The first five parameters are file descriptors that this function @@ -250,23 +252,25 @@ setraw(int fd, struct termios *p) * set select() handlers. Please see the definitions of struct * itrm_in and struct itrm_out for further explanations. * - * param member file if process is master file if process is slave - * ------ ------ ------------------------- ------------------------ - * std_in in.std read tty device (or pipe) read tty device (or pipe) - * std_out out.std write tty device (or pipe) write tty device (or pipe) - * sock_in in.sock ==std_out (masterhood flag) read socket from master - * sock_out out.sock write pipe to same process write socket to master - * ctl_in in.ctl control tty device control tty device + * @param std_in itrm_in.std: read tty device (or pipe) + * @param std_out itrm_out.std: write tty device (or pipe) + * @param sock_in itrm_in.sock + * - If master: == @a std_out (masterhood flag) + * - If slave: read socket from master + * @param sock_out itrm_out.sock + * - If master: write pipe to same process + * - If slave: write socket to master + * @param ctl_in itrm_in.ctl: control tty device * * The remaining three parameters control the initial interlink packet. * - * init_string = A string to be passed to the master process. Need - * not be null-terminated. If remote==0, this is a URI. - * Otherwise, this is a remote command. - * init_len = The length of init_string, in bytes. - * remote = 0 if asking the master to start a new session - * and display it via this process. Otherwise, - * enum remote_session_flags. */ + * @param init_string A string to be passed to the master process. Need + * not be null-terminated. If @a remote == 0, this is + * a URI. Otherwise, this is a remote command. + * @param init_len The length of init_string, in bytes. + * @param remote = 0 if asking the master to start a new session + * and display it via this process. Otherwise, + * enum remote_session_flags. */ void handle_trm(int std_in, int std_out, int sock_in, int sock_out, int ctl_in, void *init_string, int init_len, int remote) @@ -342,7 +346,7 @@ handle_trm(int std_in, int std_out, int sock_in, int sock_out, int ctl_in, } -/* A select_handler_T read_func and error_func for the pipe (long) h. +/** A select_handler_T read_func and error_func for the pipe (long) @a h. * This is called when the subprocess started on the terminal of this * ELinks process exits. ELinks then resumes using the terminal. */ static void @@ -435,9 +439,9 @@ free_itrm(struct itrm *itrm) mem_free(itrm); } -/* Resize terminal to dimensions specified by @text string. - * @text should look like "width,height,old-width,old-height" where width and - * height are integers. */ +/** Resize terminal to dimensions specified by @a text string. + * @a text should look like "width,height,old-width,old-height" + * where width and height are integers. */ static inline void resize_terminal_from_str(unsigned char *text) { @@ -501,7 +505,7 @@ safe_hard_write(int fd, unsigned char *buf, int len) done_draw(); } -/* A select_handler_T read_func for itrm->in.sock. A slave process +/** A select_handler_T read_func for itrm_in.sock. A slave process * calls this when the master sends it data to be displayed. The * master process never calls this. */ static void @@ -632,7 +636,7 @@ free_and_return: } -/* Parse an ECMA-48 control sequence that was received from a +/** Parse an ECMA-48 control sequence that was received from a * terminal. Extract the Final Byte (if there are no Intermediate * Bytes) and the value of the first parameter (if it is an integer). * @@ -640,10 +644,10 @@ free_and_return: * CONTROL SEQUENCE INTRODUCER encoded as ESC [. (ECMA-48 also allows * 0x9B as a single-byte CSI, but we don't support that here.) * - * Return one of: - * -1 if the control sequence is not yet complete; the caller sets a timer. - * 0 if the control sequence does not comply with ECMA-48. - * The length of the control sequence otherwise. */ + * @returns one of: + * - -1 if the control sequence is not yet complete; the caller sets a timer. + * - 0 if the control sequence does not comply with ECMA-48. + * - The length of the control sequence otherwise. */ static inline int get_esc_code(unsigned char *str, int len, unsigned char *final_byte, int *first_param_value) @@ -706,16 +710,16 @@ get_esc_code(unsigned char *str, int len, unsigned char *final_byte, #include /* isprint() isspace() */ #endif -/* Decode a control sequence that begins with CSI (CONTROL SEQUENCE - * INTRODUCER) encoded as ESC [, and set *@ev accordingly. +/** Decode a control sequence that begins with CSI (CONTROL SEQUENCE + * INTRODUCER) encoded as ESC [, and set @a *ev accordingly. * (ECMA-48 also allows 0x9B as a single-byte CSI, but we don't * support that here.) * - * Return one of: - * -1 if the control sequence is not yet complete; the caller sets a timer. - * 0 if the control sequence should be parsed by some other function. - * The length of the control sequence otherwise. - * Returning >0 does not imply this function has altered *ev. */ + * @returns one of: + * - -1 if the control sequence is not yet complete; the caller sets a timer. + * - 0 if the control sequence should be parsed by some other function. + * - The length of the control sequence otherwise. + * Returning >0 does not imply this function has altered @a *ev. */ static int decode_terminal_escape_sequence(struct itrm *itrm, struct interlink_event *ev) { @@ -874,13 +878,13 @@ decode_terminal_escape_sequence(struct itrm *itrm, struct interlink_event *ev) return el; } -/* Decode an escape sequence that begins with SS3 (SINGLE SHIFT 3). +/** Decode an escape sequence that begins with SS3 (SINGLE SHIFT 3). * These are used for application cursor keys and the application keypad. - * Return one of: - * -1 if the escape sequence is not yet complete; the caller sets a timer. - * 0 if the escape sequence should be parsed by some other function. - * The length of the escape sequence otherwise. - * Returning >0 does not imply this function has altered *ev. */ + * @returns one of: + * - -1 if the escape sequence is not yet complete; the caller sets a timer. + * - 0 if the escape sequence should be parsed by some other function. + * - The length of the escape sequence otherwise. + * Returning >0 does not imply this function has altered @a *ev. */ static int decode_terminal_application_key(struct itrm *itrm, struct interlink_event *ev) { @@ -930,11 +934,8 @@ decode_terminal_application_key(struct itrm *itrm, struct interlink_event *ev) } -/* Initialize *@ev to match the byte @key received from the terminal. - * Actually, @key could also be a value from enum term_event_special_key; - * but callers that use those values generally don't need the mapping - * provided by this function, so they call set_kbd_interlink_event() - * directly. */ +/** Initialize @a *ev to match the byte @a key received from the terminal. + * @a key must not be a value from enum term_event_special_key. */ static void set_kbd_event(struct interlink_event *ev, int key, term_event_modifier_T modifier) @@ -975,7 +976,7 @@ set_kbd_event(struct interlink_event *ev, set_kbd_interlink_event(ev, key, modifier); } -/* Timer callback for @itrm->timer. As explained in @install_timer, +/** Timer callback for itrm.timer. As explained in install_timer(), * this function must erase the expired timer ID from all variables. */ static void kbd_timeout(struct itrm *itrm) @@ -1012,11 +1013,12 @@ kbd_timeout(struct itrm *itrm) while (process_queue(itrm)); } -/* Parse one event from itrm->in.queue and append to itrm->out.queue. - * Return the number of bytes removed from itrm->in.queue; at least 0. - * If this function leaves the queue not full, it also reenables reading - * from itrm->in.std. (Because it does not add to the queue, it never - * need disable reading.) On entry, the itrm must not be blocked. */ +/** Parse one event from itrm_in.queue and append to itrm_out.queue. + * @pre On entry, @a *itrm must not be blocked. + * @returns the number of bytes removed from itrm->in.queue; at least 0. + * @post If this function leaves the queue not full, it also reenables + * reading from itrm->in.std. (Because it does not add to the queue, + * it never need disable reading.) */ static int process_queue(struct itrm *itrm) { @@ -1146,7 +1148,7 @@ return_without_event: } -/* A select_handler_T read_func for itrm->in.std. This is called when +/** A select_handler_T read_func for itrm_in.std. This is called when * characters typed by the user arrive from the terminal. */ static void in_kbd(struct itrm *itrm) @@ -1179,7 +1181,7 @@ in_kbd(struct itrm *itrm) while (process_queue(itrm)); } -/* Enable reading from itrm->in.std. ELinks will read any available +/** Enable reading from itrm_in.std. ELinks will read any available * bytes from the tty into itrm->in.queue and then parse them. * Reading should be enabled whenever itrm->in.queue is not full and * itrm->blocked is 0. */ @@ -1190,7 +1192,7 @@ handle_itrm_stdin(struct itrm *itrm) (select_handler_T) free_itrm, itrm); } -/* Disable reading from itrm->in.std. Reading should be disabled +/** Disable reading from itrm_in.std. Reading should be disabled * whenever itrm->in.queue is full (there is no room for the data) * or itrm->blocked is 1 (other processes may read the data). */ static void diff --git a/src/terminal/kbd.h b/src/terminal/kbd.h index f5b6d8795..e886f8cb7 100644 --- a/src/terminal/kbd.h +++ b/src/terminal/kbd.h @@ -5,28 +5,28 @@ struct itrm; -/* A character received from a terminal. */ +/** A character received from a terminal. */ #ifdef CONFIG_UTF8 typedef unicode_val_T term_event_char_T; /* in UCS-4 */ #else typedef unsigned char term_event_char_T; /* in the charset of the terminal */ #endif -/* A key received from a terminal, without modifiers. The value is +/** A key received from a terminal, without modifiers. The value is * either from term_event_char_T or from enum term_event_special_key. * To check which one it is, use is_kbd_character(). * - * Values <= -0x100 are special; from enum term_event_special_key. - * Values between -0xFF and -2 are not used yet; treat as special. - * Value == -1 is KBD_UNDEF; not sent via socket. - * Values >= 0 are characters; from term_event_char_T. + * - Values <= -0x100 are special; from enum term_event_special_key. + * - Values between -0xFF and -2 are not used yet; treat as special. + * - Value == -1 is KBD_UNDEF; not sent via socket. + * - Values >= 0 are characters; from term_event_char_T. * * Any at least 32-bit signed integer type would work here; using an * exact-width type hurts portability in principle, but some other * parts of ELinks already require the existence of uint32_t. */ typedef int32_t term_event_key_T; -/* Values for term_event_keyboard.modifier and +/** Values for term_event_keyboard.modifier and * interlink_event_keyboard.modifier */ typedef enum { KBD_MOD_NONE = 0, @@ -35,36 +35,36 @@ typedef enum { KBD_MOD_ALT = 4 } term_event_modifier_T; -/* A key received from a terminal, with modifiers. */ +/** A key received from a terminal, with modifiers. */ struct term_event_keyboard { term_event_key_T key; term_event_modifier_T modifier; }; -/* Like struct term_event_keyboard but used in the interlink protocol +/** Like struct term_event_keyboard but used in the interlink protocol * between ELinks processes. Because the processes may be running * different versions of ELinks, especially if a new version has just * been installed, this structure should be kept binary compatible as * long as possible. See bug 793 for a list of pending changes to the * protocol. */ struct interlink_event_keyboard { - /* This is like term_event_key_T but carries individual bytes + /** This is like term_event_key_T but carries individual bytes * rather than entire characters, and uses different values * for special keys. * - * Values <= -2 are not used, for ELinks 0.11 compatibility. - * Value == -1 is KBD_UNDEF; not sent via socket. - * Values between 0 and 0xFF are bytes received from the terminal. - * Values >= 0x100 are special; absolute values of constants - * from enum term_event_special_key, e.g. -KBD_ENTER. */ + * - Values <= -2 are not used, for ELinks 0.11 compatibility. + * - Value == -1 is KBD_UNDEF; not sent via socket. + * - Values between 0 and 0xFF are bytes received from the terminal. + * - Values >= 0x100 are special; absolute values of constants + * from enum term_event_special_key, e.g. -KBD_ENTER. */ int key; - /* The values are from term_event_modifier_T, but the type + /** The values are from term_event_modifier_T, but the type * must be int so that the representation remains compatible * with ELinks 0.11. */ int modifier; }; -/* Codes of special keys, for use in term_event_key_T. +/** Codes of special keys, for use in term_event_key_T. * The enum has a tag mainly to let you cast numbers to it in GDB and see * their names. ELinks doesn't use this enum type as term_event_key_T, * because it might be 16-bit and Unicode characters wouldn't then fit. */ @@ -106,11 +106,11 @@ static inline int is_kbd_fkey(term_event_key_T key) { return key <= KBD_F1 && ke #define number_to_kbd_fkey(num) (KBD_F1 - (num) + 1) #define kbd_fkey_to_number(key) (KBD_F1 - (key) + 1) -/* int is_kbd_character(term_event_key_T key); - * Check whether @key is a character or a special key. - * Return true if @key is a character from term_event_char_T. +/**Check whether @a key is a character or a special key. + * @code int is_kbd_character(term_event_key_T key); @endcode + * Return true if @a key is a character from ::term_event_char_T. * (The character is not necessarily printable.) - * Return false if @key is a special key from enum term_event_special_key. */ + * Return false if @a key is a special key from enum term_event_special_key. */ #define is_kbd_character(key) ((key) >= 0) void diff --git a/src/terminal/mouse.c b/src/terminal/mouse.c index 7af40ee2c..8744cd7ca 100644 --- a/src/terminal/mouse.c +++ b/src/terminal/mouse.c @@ -1,4 +1,5 @@ -/* Support for mouse interface */ +/** Support for mouse interface + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -45,8 +46,8 @@ extern struct itrm *ditrm; hard_write(fd, seq, sizeof(seq) - 1) -#define INIT_TWIN_MOUSE_SEQ "\033[?9h" /* Send MIT Mouse Row & Column on Button Press */ -#define INIT_XWIN_MOUSE_SEQ "\033[?1000h" /* Send Mouse X & Y on button press and release */ +#define INIT_TWIN_MOUSE_SEQ "\033[?9h" /**< Send MIT Mouse Row & Column on Button Press */ +#define INIT_XWIN_MOUSE_SEQ "\033[?1000h" /**< Send Mouse X & Y on button press and release */ void send_mouse_init_sequence(int h) @@ -55,8 +56,8 @@ send_mouse_init_sequence(int h) write_sequence(h, INIT_XWIN_MOUSE_SEQ); } -#define DONE_TWIN_MOUSE_SEQ "\033[?9l" /* Don't Send MIT Mouse Row & Column on Button Press */ -#define DONE_XWIN_MOUSE_SEQ "\033[?1000l" /* Don't Send Mouse X & Y on button press and release */ +#define DONE_TWIN_MOUSE_SEQ "\033[?9l" /**< Don't Send MIT Mouse Row & Column on Button Press */ +#define DONE_XWIN_MOUSE_SEQ "\033[?1000l" /**< Don't Send Mouse X & Y on button press and release */ void send_mouse_done_sequence(int h) @@ -123,7 +124,7 @@ decode_mouse_position(struct itrm *itrm, int from) #define TW_BUTT_MIDDLE 2 #define TW_BUTT_RIGHT 4 -/* Returns length of the escape sequence or -1 if the caller needs to set up +/** @returns length of the escape sequence or -1 if the caller needs to set up * the ESC delay timer. */ int decode_terminal_mouse_escape_sequence(struct itrm *itrm, struct interlink_event *ev, diff --git a/src/terminal/palette.inc b/src/terminal/palette.inc index 610822f87..7f29c437a 100644 --- a/src/terminal/palette.inc +++ b/src/terminal/palette.inc @@ -1,7 +1,10 @@ -/* Terminal color palettes. */ -/* TODO: We should probably autogenerate this using xterm's perl script. */ +/** Terminal color palettes. + * @file + * + * \todo TODO: We should probably autogenerate this using xterm's perl + * script. */ -/* The 16 ANSI colors. */ +/** The 16 ANSI colors. */ static const struct rgb palette16[] = { #if defined(PALA) {0x00, 0x00, 0x00}, @@ -58,10 +61,11 @@ static const struct rgb palette16[] = { }; #ifdef CONFIG_88_COLORS -/* Regexp'd from Dickey's xterm 88colres.h file. */ -/* Colors 0-15 are the ANSI colors (and the same as palette16[]). - * Colors 16-79 are a 4x4x4 color cube - * Colors 80-91 are a grayscale ramp (with black and white left out). */ +/** The 88 xterm colors. + * Regexp'd from Dickey's xterm 88colres.h file. + * - Colors 0-15 are the ANSI colors (and the same as palette16[]). + * - Colors 16-79 are a 4x4x4 color cube + * - Colors 80-91 are a grayscale ramp (with black and white left out). */ static const struct rgb palette88[] = { {0x00, 0x00, 0x00}, /* 0 */ {0x80, 0x00, 0x00}, /* 1 */ @@ -160,11 +164,12 @@ static const struct rgb palette88[] = { #endif #ifdef CONFIG_256_COLORS -/* Regexp'd from Dickey's xterm 256colres.h file. */ -/* Colors 0- 15 are the ANSI colors (from xterm-215/XTerm-col.ad - * and Xorg's rgb.txt, not the same as palette16[]). - * Colors 16-231 are a 6x6x6 color cube - * Colors 232-255 are a grayscale ramp (with black and white left out). +/** The 256 xterm colors. + * Regexp'd from Dickey's xterm 256colres.h file. + * - Colors 0- 15 are the ANSI colors (from xterm-215/XTerm-col.ad + * and Xorg's rgb.txt, not the same as palette16[]). + * - Colors 16-231 are a 6x6x6 color cube + * - Colors 232-255 are a grayscale ramp (with black and white left out). * * The 6x6x6 color cube of xterm uses brightnesses 00-5f-87-af-d7-ff * whereas the "web-safe" palette uses 00-33-66-99-cc-ff, which then @@ -179,19 +184,21 @@ static const struct rgb palette88[] = { * function, which passes through all six points and has a continuous * positive first derivative: * + * @verbatim * y = (765/11) - sqrt(585225/121 - (2601/55)*x) when x <= 0x5f * x = (-55/2601)*y^2 + (150/51)*y when x <= 0x5f * y = (51/40)*x + (-561/8) when x >= 0x5f + * @endverbatim + */ +/* If you use Emacs, just run eval-last-sexp (C-x C-e) on the following: * - * If you use Emacs then here is how to do it easily: - * - * (while (re-search-forward "0x\\([[:xdigit:]]+\\)" nil t) - (let* ((x (string-to-number (match-string 1) 16)) - (y (if (<= x #x5f) - (- (/ 765.0 11.0) - (sqrt (- (/ 585225.0 121.0) (* (/ 2601.0 55.0) x)))) - (+ (* (/ 51.0 40.0) x) (/ -561.0 8.0))))) - (replace-match (format "%.2x" (round y)) nil t nil 1))) + * (while (re-search-forward "0x\\([[:xdigit:]]+\\)" nil t) #@3 + * (let* ((x (string-to-number (match-string 1) 16)) #@3 + * (y (if (<= x #x5f) #@3 + * (- (/ 765.0 11.0) #@3 + * (sqrt (- (/ 585225.0 121.0) (* (/ 2601.0 55.0) x))))#@3 + * (+ (* (/ 51.0 40.0) x) (/ -561.0 8.0))))) #@3 + * (replace-match (format "%.2x" (round y)) nil t nil 1))) */ static const struct rgb palette256[] = { {0x00, 0x00, 0x00}, /* 0 black */ diff --git a/src/terminal/screen.c b/src/terminal/screen.c index 54ffee3df..2233d282b 100644 --- a/src/terminal/screen.c +++ b/src/terminal/screen.c @@ -1,4 +1,5 @@ -/* Terminal screen drawing routines. */ +/** Terminal screen drawing routines. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -28,10 +29,17 @@ /* TODO: We must use termcap/terminfo if available! --pasky */ +/** Mapping from (enum border_char - 0xB0) to ASCII characters. */ const unsigned char frame_dumb[48] = " ||||++||++++++--|-+||++--|-+----++++++++ "; + +/** Mapping from (enum border_char - 0xB0) to VT100 line-drawing + * characters. */ static const unsigned char frame_vt100[48] = "aaaxuuukkuxkjjjkmvwtqnttmlvwtqnvvwwmmllnnjla "; -/* For UTF-8 I/O */ +/** Mapping from (enum border_char - 0xB0) to VT100 line-drawing + * characters encoded in CP437. + * When UTF-8 I/O is enabled, ELinks uses this array instead of + * frame_vt100[], and converts the characters from CP437 to UTF-8. */ static const unsigned char frame_vt100_u[48] = { 177, 177, 177, 179, 180, 180, 180, 191, 191, 180, 179, 191, 217, 217, 217, 191, @@ -41,11 +49,15 @@ static const unsigned char frame_vt100_u[48] = { 197, 217, 218, 177, 32, 32, 32, 32 }; -/* This is for FreeBSD fonts that place graphics characters in the +/** Mapping from (enum border_char - 0xB0) to obsolete FreeBSD ACS + * graphics. + * + * This is for FreeBSD fonts that place graphics characters in the * 0x80...0x9F range, which ISO 8859 does not use. The characters are * supposed to be sorted according to the codes used in VT100 or in * the terminfo "acsc" capability: * + * @verbatim * 0x80 U+2588 '0' ACS_BLOCK * 0x81 U+25C6 '`' ACS_DIAMOND * 0x82 U+2592 'a' ACS_CKBOARD @@ -78,6 +90,7 @@ static const unsigned char frame_vt100_u[48] = { * 0x9D U+2260 '|' ACS_NEQUAL * 0x9E U+00A3 '}' ACS_STERLING * 0x9F U+00B7 '~' ACS_BULLET + * @endverbatim * * (Ncurses 5.5 defines ACS_BOARD using 'h' and ACS_LANTERN using 'i', * but those are not the characters meant above.) @@ -98,10 +111,15 @@ static const unsigned char frame_freebsd[48] = { 143, 139, 141, 128, 128, 128, 128, 128, }; -/* For UTF-8 I/O. Derived from frame_freebsd[] by converting the - * characters to Unicode and back to CP437. frame_freebsd[1] = 138 = - * 0x8a = U+240B SYMBOL FOR VERTICAL TABULATION does not exist in - * CP437, so we substitute U+2592 MEDIUM SHADE. */ +/** Mapping from (enum border_char - 0xB0) to obsolete FreeBSD ACS + * graphics encoded in CP437. + * When UTF-8 I/O is enabled, ELinks uses this array instead of + * frame_freebsd[], and converts the characters from CP437 to UTF-8. + * + * Derived from frame_freebsd[] by converting the characters to + * Unicode and back to CP437. frame_freebsd[1] = 138 = 0x8a = U+240B + * SYMBOL FOR VERTICAL TABULATION does not exist in CP437, so we + * substitute U+2592 MEDIUM SHADE. */ static const unsigned char frame_freebsd_u[48] = { 177, 177, 219, 179, 180, 180, 180, 191, 191, 180, 179, 191, 217, 217, 217, 191, @@ -111,6 +129,7 @@ static const unsigned char frame_freebsd_u[48] = { 197, 217, 218, 219, 219, 219, 219, 219, }; +/** Mapping from (enum border_char - 0xB0) to KOI8-R. */ static const unsigned char frame_koi[48] = { 144, 145, 146, 129, 135, 178, 180, 167, 166, 181, 161, 168, 174, 173, 172, 131, @@ -120,7 +139,10 @@ static const unsigned char frame_koi[48] = { 188, 133, 130, 141, 140, 142, 143, 139, }; -/* Most of this table is just 176 + . */ +/** Mapping from (enum border_char - 0xB0) to CP850 or CP852. Most of + * this table is just 0xB0 + @, because these codepages + * are quite similar to CP437. However, they lack some line-drawing + * characters, so we must use others instead. */ static const unsigned char frame_restrict[48] = { 176, 177, 178, 179, 180, 179, 186, 186, 205, 185, 186, 187, 188, 186, 205, 191, @@ -132,58 +154,67 @@ static const unsigned char frame_restrict[48] = { #define TERM_STRING(str) INIT_STRING(str, sizeof(str) - 1) -/* Like add_string_to_string but has fewer checks to slow it down. */ +/** Like add_string_to_string but has fewer checks to slow it down. */ #define add_term_string(str, tstr) \ add_bytes_to_string(str, (tstr).source, (tstr).length) -/* ECMA-48: CSI Ps... 06/13 = SGR - SELECT GRAPHIC RENDITION - * Ps = 10 = primary (default) font - * Ps = 11 = first alternative font */ +/** Frame begin/end sequences that switch fonts with ECMA-48 SGR. + * ECMA-48: CSI Ps... 06/13 = SGR - SELECT GRAPHIC RENDITION + * - Ps = 10 = primary (default) font + * - Ps = 11 = first alternative font */ static const struct string m11_hack_frame_seqs[] = { /* end border: */ TERM_STRING("\033[10m"), /* begin border: */ TERM_STRING("\033[11m"), }; +/** Frame begin/end sequences for VT100. */ static const struct string vt100_frame_seqs[] = { /* end border: */ TERM_STRING("\x0f"), /* begin border: */ TERM_STRING("\x0e"), }; +/** Underline begin/end sequences using ECMA-48 SGR. + * ECMA-48: CSI Ps... 06/13 = SGR - SELECT GRAPHIC RENDITION + * - Ps = 4 = singly underlined + * - Ps = 21 = doubly underlined + * - Ps = 24 = not underlined (neither singly nor doubly) */ static const struct string underline_seqs[] = { - /* begin underline: */ TERM_STRING("\033[24m"), - /* end underline: */ TERM_STRING("\033[4m"), + /* end underline: */ TERM_STRING("\033[24m"), + /* begin underline: */ TERM_STRING("\033[4m"), }; -/* Used in {add_char*()} and {redraw_screen()} to reduce the logic. It is - * updated from terminal._template_.* using option change_hooks. */ -/* TODO: termcap/terminfo can maybe gradually be introduced via this - * structure. We'll see. --jonas */ +/** Used in @c add_char*() and @c redraw_screen() to reduce the logic. + * It is updated from terminal._template_.* using option.change_hook. + * + * @todo TODO: termcap/terminfo can maybe gradually be introduced via + * this structure. We'll see. --jonas */ struct screen_driver { LIST_HEAD(struct screen_driver); - /* The terminal._template_.type. Together with the @name member the + /** The terminal._template_.type. Together with the #name member they * uniquely identify the screen_driver. */ enum term_mode_type type; + /** set_screen_driver_opt() sets these. */ struct screen_driver_opt { - /* Charsets when doing UTF8 I/O. */ - /* [0] is the common charset and [1] is the frame charset. - * Test whether to use UTF8 I/O using the use_utf8_io() macro. */ + /** Charsets when doing UTF-8 I/O. + * [0] is the common charset and [1] is the frame charset. + * Test whether to use UTF-8 I/O using the use_utf8_io() macro. */ int charsets[2]; - /* The frame translation table. May be NULL. */ + /** The frame translation table. May be NULL. */ const unsigned char *frame; - /* The frame mode setup and teardown sequences. May be NULL. */ + /** The frame mode setup and teardown sequences. May be NULL. */ const struct string *frame_seqs; - /* The underline mode setup and teardown sequences. May be NULL. */ + /** The underline mode setup and teardown sequences. May be NULL. */ const struct string *underline; - /* The color mode */ + /** The color mode */ enum color_mode color_mode; - /* These are directly derived from the terminal options. */ + /** These are directly derived from the terminal options. */ unsigned int transparent:1; #ifdef CONFIG_UTF8 @@ -198,6 +229,7 @@ struct screen_driver { unsigned char name[1]; /* XXX: Keep last! */ }; +/** Default options for ::TERM_DUMB. */ static const struct screen_driver_opt dumb_screen_driver_opt = { /* charsets: */ { -1, -1 }, /* No UTF8 I/O */ /* frame: */ frame_dumb, @@ -210,6 +242,7 @@ static const struct screen_driver_opt dumb_screen_driver_opt = { #endif /* CONFIG_UTF8 */ }; +/** Default options for ::TERM_VT100. */ static const struct screen_driver_opt vt100_screen_driver_opt = { /* charsets: */ { -1, -1 }, /* No UTF8 I/O */ /* frame: */ frame_vt100, @@ -222,6 +255,7 @@ static const struct screen_driver_opt vt100_screen_driver_opt = { #endif /* CONFIG_UTF8 */ }; +/** Default options for ::TERM_LINUX. */ static const struct screen_driver_opt linux_screen_driver_opt = { /* charsets: */ { -1, -1 }, /* No UTF8 I/O */ /* frame: */ NULL, /* No restrict_852 */ @@ -234,6 +268,7 @@ static const struct screen_driver_opt linux_screen_driver_opt = { #endif /* CONFIG_UTF8 */ }; +/** Default options for ::TERM_KOI8. */ static const struct screen_driver_opt koi8_screen_driver_opt = { /* charsets: */ { -1, -1 }, /* No UTF8 I/O */ /* frame: */ frame_koi, @@ -246,6 +281,7 @@ static const struct screen_driver_opt koi8_screen_driver_opt = { #endif /* CONFIG_UTF8 */ }; +/** Default options for ::TERM_FREEBSD. */ static const struct screen_driver_opt freebsd_screen_driver_opt = { /* charsets: */ { -1, -1 }, /* No UTF8 I/O */ /* frame: */ frame_freebsd, @@ -258,7 +294,8 @@ static const struct screen_driver_opt freebsd_screen_driver_opt = { #endif /* CONFIG_UTF8 */ }; -/* XXX: Keep in sync with enum term_mode_type. */ +/** Default options for all the different types of terminals. + * XXX: Keep in sync with enum term_mode_type. */ static const struct screen_driver_opt *const screen_driver_opts[] = { /* TERM_DUMB: */ &dumb_screen_driver_opt, /* TERM_VT100: */ &vt100_screen_driver_opt, @@ -271,8 +308,8 @@ static const struct screen_driver_opt *const screen_driver_opts[] = { static INIT_LIST_OF(struct screen_driver, active_screen_drivers); -/* Set driver->opt according to driver->type and term_spec. - * Other members of *driver need not have been initialized. +/** Set screen_driver.opt according to screen_driver.type and \a term_spec. + * Other members of \a *driver need not have been initialized. * * If you modify anything here, check whether option descriptions * should be updated. */ @@ -430,7 +467,7 @@ get_screen_driver(struct terminal *term) return add_screen_driver(type, term, len); } -/* Release private screen drawing utilities. */ +/** Release private screen drawing utilities. */ void done_screen_drivers(struct module *xxx) { @@ -438,8 +475,8 @@ done_screen_drivers(struct module *xxx) } -/* Adds the term code for positioning the cursor at @x and @y to @string. - * The template term code is: "\033[<@y>;<@x>H" */ +/** Adds the term code for positioning the cursor at @a x and @a y to + * @a string. The template term code is: "\033[<@a y>;<@a x>H" */ static inline struct string * add_cursor_move_to_string(struct string *screen, int y, int x) { @@ -469,7 +506,7 @@ struct screen_state { unsigned char underline; unsigned char bold; unsigned char attr; - /* Following should match struct screen_char color field. */ + /** Following should match the screen_char.color field. */ unsigned char color[SCREEN_COLOR_SIZE]; }; @@ -620,7 +657,7 @@ add_char_data(struct string *screen, struct screen_driver *driver, } } -/* Time critical section. */ +/** Time critical section. */ static inline void add_char16(struct string *screen, struct screen_driver *driver, struct screen_char *ch, struct screen_state *state) @@ -772,7 +809,7 @@ add_char_color(struct string *screen, const struct string *seq, unsigned char co #define add_background_color(str, seq, chr) add_char_color(str, &(seq)[1], (chr)->color[1]) #define add_foreground_color(str, seq, chr) add_char_color(str, &(seq)[0], (chr)->color[0]) -/* Time critical section. */ +/** Time critical section. */ static inline void add_char256(struct string *screen, struct screen_driver *driver, struct screen_char *ch, struct screen_state *state) @@ -887,7 +924,7 @@ add_char_true_color(struct string *screen, const struct string *seq, unsigned ch add_char_to_string(screen, 'm'); } -/* Time critical section. */ +/** Time critical section. */ static inline void add_char_true(struct string *screen, struct screen_driver *driver, struct screen_char *ch, struct screen_state *state) @@ -1007,8 +1044,8 @@ add_char_true(struct string *screen, struct screen_driver *driver, } \ } -/* Updating of the terminal screen is done by checking what needs to be updated - * using the last screen. */ +/*! Updating of the terminal screen is done by checking what needs to + * be updated using the last screen. */ void redraw_screen(struct terminal *term) { @@ -1127,8 +1164,9 @@ init_screen(void) return screen; } -/* The two images are allocated in one chunk. */ -/* TODO: It seems allocation failure here is fatal. We should do something! */ +/*! The two images are allocated in one chunk. + * \todo TODO: It seems allocation failure here is fatal. + * We should do something! */ void resize_screen(struct terminal *term, int width, int height) { @@ -1171,7 +1209,7 @@ done_screen(struct terminal_screen *screen) struct module terminal_screen_module = struct_module( /* Because this module is a submodule of terminal_module, - * which is listed main_modules rather than in builtin_modules, + * which is listed in main_modules rather than in builtin_modules, * its name does not appear in the user interface and * so need not be translatable. */ /* name: */ "Terminal Screen", diff --git a/src/terminal/screen.h b/src/terminal/screen.h index 35cd43510..9513a51e4 100644 --- a/src/terminal/screen.h +++ b/src/terminal/screen.h @@ -6,24 +6,24 @@ struct module; struct screen_char; struct terminal; -/* The terminal's screen manages */ +/** The terminal's screen manages */ struct terminal_screen { - /* This is the screen's image, character by character. */ + /** This is the screen's image, character by character. */ struct screen_char *image; - /* The previous screen's image, used for optimizing actual drawing. */ + /** The previous screen's image, used for optimizing actual drawing. */ struct screen_char *last_image; - /* The current and the previous cursor positions. */ + /** The current and the previous cursor positions. */ int cx, cy; int lcx, lcy; - /* The range of line numbers that are out of sync with the physical - * screen. @dirty_from > @dirty_to means not dirty. */ + /** The range of line numbers that are out of sync with the physical + * screen. #dirty_from > #dirty_to means not dirty. */ int dirty_from, dirty_to; }; -/* Mark the screen ready for redrawing. */ +/** Mark the screen ready for redrawing. */ static inline void set_screen_dirty(struct terminal_screen *screen, int from, int to) { @@ -31,23 +31,23 @@ set_screen_dirty(struct terminal_screen *screen, int from, int to) int_lower_bound(&screen->dirty_to, to); } -/* Initializes a screen. Returns NULL upon allocation failure. */ +/** Initializes a screen. Returns NULL upon allocation failure. */ struct terminal_screen *init_screen(void); -/* Cleans up after the screen. */ +/** Cleans up after the screen. */ void done_screen(struct terminal_screen *screen); -/* Update the size of the previous and the current screen image to hold @x time - * @y chars. */ +/** Update the size of the previous and the current screen image to + * hold @a x time @a y chars. */ void resize_screen(struct terminal *term, int x, int y); -/* Updates the terminal screen. */ +/** Updates the terminal screen. */ void redraw_screen(struct terminal *term); -/* Erases the entire screen and moves the cursor to the upper left corner. */ +/** Erases the entire screen and moves the cursor to the upper left corner. */ void erase_screen(struct terminal *term); -/* Meeep! */ +/** Meeep! */ void beep_terminal(struct terminal *term); extern struct module terminal_screen_module; diff --git a/src/terminal/tab.c b/src/terminal/tab.c index e4dfa63b0..b9795483d 100644 --- a/src/terminal/tab.c +++ b/src/terminal/tab.c @@ -1,4 +1,5 @@ -/* Tab-style (those containing real documents) windows infrastructure. */ +/** Tab-style (those containing real documents) windows infrastructure. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -60,7 +61,7 @@ found_pos: return win; } -/* Number of tabs at the terminal (in term->windows) */ +/** Number of tabs at the terminal (in term->windows) */ inline int number_of_tabs(struct terminal *term) { @@ -73,7 +74,7 @@ number_of_tabs(struct terminal *term) return result; } -/* Number of tab */ +/** Number of tab */ int get_tab_number(struct window *window) { @@ -93,7 +94,7 @@ get_tab_number(struct window *window) return num; } -/* Get tab of an according index */ +/** Get tab of an according index */ struct window * get_tab_by_number(struct terminal *term, int num) { @@ -113,7 +114,7 @@ get_tab_by_number(struct terminal *term, int num) return win; } -/* Returns number of the tab at @xpos, or -1 if none. */ +/** Returns number of the tab at @a xpos, or -1 if none. */ int get_tab_number_by_xpos(struct terminal *term, int xpos) { @@ -130,7 +131,7 @@ get_tab_number_by_xpos(struct terminal *term, int xpos) return -1; } -/* if @tabs_count > 0, then it is taken as the result of a recent +/*! If @a tabs_count > 0, then it is taken as the result of a recent * call to number_of_tabs() so it just uses this value. */ void switch_to_tab(struct terminal *term, int tab, int tabs_count) diff --git a/src/terminal/terminal.c b/src/terminal/terminal.c index bd7e73b8e..5217cc68a 100644 --- a/src/terminal/terminal.c +++ b/src/terminal/terminal.c @@ -1,4 +1,5 @@ -/* Terminal interface - low-level displaying implementation. */ +/** Terminal interface - low-level displaying implementation. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" diff --git a/src/terminal/terminal.h b/src/terminal/terminal.h index 7a14f3245..4c2f7c339 100644 --- a/src/terminal/terminal.h +++ b/src/terminal/terminal.h @@ -11,7 +11,7 @@ struct terminal_screen; struct terminal_interlink; -/* The terminal type, meaningful for frames (lines) drawing. */ +/** The terminal type, meaningful for frames (lines) drawing. */ enum term_mode_type { TERM_DUMB = 0, TERM_VT100, @@ -20,71 +20,72 @@ enum term_mode_type { TERM_FREEBSD, }; -/* This is a bitmask describing the environment we are living in, +/** This is a bitmask describing the environment we are living in, * terminal-wise. We can then conditionally use various features available * in such an environment. */ enum term_env_type { - /* This basically means that we can use the text i/o :). Always set. */ + /** This basically means that we can use the text i/o :). Always set. */ ENV_CONSOLE = 1, - /* We are running in a xterm-compatible box in some windowing + /** We are running in a xterm-compatible box in some windowing * environment. */ ENV_XWIN = 2, - /* We are running under a screen. */ + /** We are running under a screen. */ ENV_SCREEN = 4, - /* We are running in a OS/2 VIO terminal. */ + /** We are running in a OS/2 VIO terminal. */ ENV_OS2VIO = 8, - /* BeOS text terminal. */ + /** BeOS text terminal. */ ENV_BE = 16, - /* We live in a TWIN text-mode windowing environment. */ + /** We live in a TWIN text-mode windowing environment. */ ENV_TWIN = 32, - /* Microsoft Windows cmdline thing. */ + /** Microsoft Windows cmdline thing. */ ENV_WIN32 = 64, - /* Match all terminal environments */ + /** Match all terminal environments */ ENV_ANY = ~0, }; enum term_redrawing_state { - TREDRAW_READY = 0, /* Can redraw */ - TREDRAW_BUSY = 1, /* Redrawing already in progress */ - TREDRAW_DELAYED = 2, /* Do not redraw for now */ + TREDRAW_READY = 0, /**< Can redraw */ + TREDRAW_BUSY = 1, /**< Redrawing already in progress */ + TREDRAW_DELAYED = 2, /**< Do not redraw for now */ }; -/* This is one of the axis of ELinks' user interaction. {struct terminal} +/** This is one of the axis of ELinks' user interaction. struct terminal * defines the terminal ELinks is running on --- each ELinks instance has * one. It contains the basic terminal attributes, the settings associated * with this terminal, screen content (and more abstract description of what * is currently displayed on it) etc. It also maintains some runtime - * information about the actual ELinks instance owning this terminal. */ -/* TODO: Regroup the following into logical chunks. --pasky */ + * information about the actual ELinks instance owning this terminal. + * + * \todo TODO: Regroup the following into logical chunks. --pasky */ struct terminal { - LIST_HEAD(struct terminal); /* {terminals} */ + LIST_HEAD(struct terminal); /*!< ::terminals is the sentinel. */ - /* This is (at least partially) a stack of all the windows living in + /** This is (at least partially) a stack of all the windows living in * this terminal. A window can be wide range of stuff, from a menu box * through classical dialog window to a tab. See terminal/window.h for * more on windows. * * Tabs are special windows, though, and you never want to display them - * all, but only one of them. ALWAYS check {inactive_tab} during + * all, but only one of them. ALWAYS check inactive_tab() during * iterations through this list (unless it is really useless or you * are sure what are you doing) to make sure that you don't distribute * events etc to inactive tabs. * - * The stack is top-down, thus .next is the stack's top, the - * current window; and .prev is the bottom, covered by others. + * The stack is top-down, thus @c .next is the stack's top, the + * current window; and @c .prev is the bottom, covered by others. * - Dialogs or active menus are at the top. - * - Next come all tabs (window.type == WINDOW_TAB). The tab + * - Next come all tabs (window.type == ::WINDOW_TAB). The tab * listed leftmost in the tab bar is at the top, and the tab - * listed rightmost is at the bottom; but current_tab controls + * listed rightmost is at the bottom; but #current_tab controls * which tab is actually displayed. * - If the main menu is inactive, then it is at the very bottom, * hidden under the tabs. - * Call assert_window_stacking to verify this. + * Call assert_window_stacking() to verify this. * - * FIXME: Tabs violate the stack nature of this list, they appear there - * randomly but always in the order in which they were inserted there. - * Eventually, they should all live at the stack bottom, with the - * actual tab living on the VERY bottom. --pasky + * @todo FIXME: Tabs violate the stack nature of this list, they + * appear there randomly but always in the order in which they were + * inserted there. Eventually, they should all live at the stack + * bottom, with the actual tab living on the VERY bottom. --pasky * * Keeping the current tab at the very bottom would require storing * tab numbers explicitly, rather than computing them from the @@ -92,64 +93,66 @@ struct terminal { * inactive main menu? --KON */ LIST_OF(struct window) windows; - /* The specification of terminal in terms of terminal options. */ + /** The specification of terminal in terms of terminal options. */ struct option *spec; - /* This is the terminal's current title, as perhaps displayed somewhere - * in the X window frame or so. */ + /** This is the terminal's current title, as perhaps displayed + * somewhere in the X window frame or so. */ unsigned char *title; - /* This is the screen. See terminal/screen.h */ + /** This is the screen. See terminal/screen.h */ struct terminal_screen *screen; - /* This is for displaying main menu */ + /** This is for displaying main menu */ struct menu *main_menu; - /* These are pipes for communication with the ELinks instance owning - * this terminal. */ + + /** These are pipes for communication with the ELinks instance owning + * this terminal. + * @see struct itrm */ int fdin, fdout; - /* This indicates that the terminal is blocked, that is nothing should + /** This indicates that the terminal is blocked, that is nothing should * be drawn on it etc. Typically an external program is running on it * right now. This is a file descriptor. */ int blocked; - /* Terminal dimensions. */ + /** Terminal dimensions. */ int width, height; - /* Indicates whether we are currently in the process of redrawing the + /** Indicates whether we are currently in the process of redrawing the * stuff being displayed on the terminal. It is typically used to * prevent redrawing inside of redrawing. */ enum term_redrawing_state redrawing; - /* Indicates the master terminal, that is the terminal under + /** Indicates the master terminal, that is the terminal under * supervision of the master ELinks instance (the one doing all the * work and even maintaining these structures ;-). */ unsigned int master:1; #ifdef CONFIG_UTF8 - /* Indicates whether the charset of the terminal is UTF-8. */ + /** Indicates whether the charset of the terminal is UTF-8. */ unsigned int utf8_cp:1; - /* Indicates whether UTF-8 I/O is used. Forced on if the + /** Indicates whether UTF-8 I/O is used. Forced on if the * UTF-8 charset is selected. (bug 827) */ unsigned int utf8_io:1; #endif /* CONFIG_UTF8 */ - /* The current tab number. */ + /** The current tab number. */ int current_tab; #ifdef CONFIG_LEDS - /* Current length of leds part of status bar. */ + /** Current length of leds part of status bar. */ int leds_length; #endif - /* The type of environment this terminal lives in. */ + /** The type of environment this terminal lives in. */ enum term_env_type environment; - /* The current working directory for this terminal / ELinks instance. */ + /** The current working directory for this terminal / ELinks instance. */ unsigned char cwd[MAX_CWD_LEN]; - /* For communication between instances */ + /** For communication between instances */ struct terminal_interlink *interlink; struct term_event_mouse prev_mouse_event; @@ -158,7 +161,7 @@ struct terminal { #define do_not_ignore_next_mouse_event(term) \ memset(&(term)->prev_mouse_event, 0, sizeof((term)->prev_mouse_event)) -/* We keep track about all the terminals in this list. */ +/** We keep track about all the terminals in this list. */ extern LIST_OF(struct terminal) terminals; @@ -175,24 +178,26 @@ void destroy_all_terminals(void); void exec_thread(unsigned char *, int); void close_handle(void *); -/* Operations that can be requested with do_terminal_function(). +/** Operations that can be requested with do_terminal_function(). * The interlink protocol passes these values as one byte in a * null-terminated string, so zero cannot be used. */ -#define TERM_FN_TITLE 1 -#define TERM_FN_RESIZE 2 +enum { + TERM_FN_TITLE = 1, + TERM_FN_RESIZE = 2 +}; -/* How to execute a program in a terminal. These values are used in +/** How to execute a program in a terminal. These values are used in * the interlink protocol and must fit in one byte. */ enum term_exec { - /* Execute in the background. ELinks keeps using the terminal + /** Execute in the background. ELinks keeps using the terminal * and the program should not use it. */ TERM_EXEC_BG = 0, - /* Execute in the foreground. The program may use the terminal. + /** Execute in the foreground. The program may use the terminal. * ELinks will redraw when the program exits. */ TERM_EXEC_FG = 1, - /* Execute in the background and in a new process group. */ + /** Execute in the background and in a new process group. */ TERM_EXEC_NEWWIN = 2 }; diff --git a/src/terminal/window.c b/src/terminal/window.c index 3bad556d9..d4cd6c1b9 100644 --- a/src/terminal/window.c +++ b/src/terminal/window.c @@ -1,4 +1,5 @@ -/* Terminal windows stuff. */ +/** Terminal windows stuff. + * @file */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -174,7 +175,7 @@ add_empty_window(struct terminal *term, void (*fn)(void *), void *data) } #if CONFIG_DEBUG -/* Check that term->windows are in the documented order. */ +/** Check that terminal.windows are in the documented order. */ void assert_window_stacking(struct terminal *term) { diff --git a/src/terminal/window.h b/src/terminal/window.h index a75e7cbba..1490a7c5f 100644 --- a/src/terminal/window.h +++ b/src/terminal/window.h @@ -8,13 +8,13 @@ struct terminal; struct window; enum window_type { - /* Normal windows: */ - /* Used for things like dialogs. The default type when adding windows + /** Normal windows. + * Used for things like dialogs. The default type when adding windows * with add_window(). */ WINDOW_NORMAL, - /* Tab windows: */ - /* Tabs are a separate session and has separate history, current + /** Tab windows. + * Tabs are a separate session and has separate history, current * document and action-in-progress .. basically a separate browsing * state. */ WINDOW_TAB, @@ -23,26 +23,26 @@ enum window_type { typedef void (window_handler_T)(struct window *, struct term_event *); struct window { - LIST_HEAD(struct window); + LIST_HEAD(struct window); /*!< terminal.windows is the sentinel. */ enum window_type type; - /* The window event handler */ + /** The window event handler */ window_handler_T *handler; - /* For tab windows the session is stored in @data. For normal windows - * it can contain dialog data. */ - /* It is free()'d by delete_window() */ + /** For tab windows the session is stored in @c data. + * For normal windows it can contain dialog data. + * It is free()'d by delete_window() */ void *data; - /* The terminal (and screen) that hosts the window */ + /** The terminal (and screen) that hosts the window */ struct terminal *term; - /* Used for tabs focus detection. */ + /** Used for tabs focus detection. */ int xpos, width; int x, y; - /* For delayed tab resizing */ + /** For delayed tab resizing */ unsigned int resize:1; };