From 8e8a8a44fb85addc8a235d763ad71825cf2d90de Mon Sep 17 00:00:00 2001 From: Mario Kilies Date: Sat, 29 Jan 2011 15:18:03 +0100 Subject: Added documentation for ui.c. --- src/ui.c | 44 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/src/ui.c b/src/ui.c index 0c14ed0..f7b9b08 100644 --- a/src/ui.c +++ b/src/ui.c @@ -10,7 +10,7 @@ #define CP_RED_ON_BLACK 5 #define KEY_ESCAPE 27 -#define KEY_RETURN 10 +#define KEY_RETURN 10 // Is needed, because the KEY_ENTER defined by ncurses does not work #define KEY_VI_LEFT 'h' #define KEY_VI_RIGHT 'l' @@ -26,6 +26,14 @@ static WINDOW *w_hand_cards; static WINDOW *w_final_scores; +/** + * Draws a card in a given window at a specified position. The card can also be highlighted (this is used for visualization of a selected card). + * @param[in] w The window to draw the card in + * @param[in] row The row at which the card will be drawn + * @param[in] col The column at which the card will be drawn + * @param[in] highlight If true, the card will be highlighted + * @param[in] c The card, that will be drawn +*/ static void draw_card(WINDOW *w, const uint8_t row, const uint8_t col, const bool highlight, const card c) { assert(w != NULL); @@ -129,6 +137,14 @@ static void draw_card(WINDOW *w, const uint8_t row, const uint8_t col, const boo wattroff(w, A_BOLD); } +/** + * Draws a card stack in a given window at a specified position. The card stack can also be highlighted (this is used for visualization of a selected card stack). + * @param[in] w The window to draw the card stack in + * @param[in] row The row at which the card stack will be drawn + * @param[in] col The column at which the card stack will be drawn + * @param[in] highlight If true, the card stack will be highlighted + * @param[in] cs The card stack, that will be drawn +*/ static void draw_card_stack(WINDOW *w, const uint8_t row, const uint8_t col, const bool highlight, const card_stack_t *cs) { assert(w != NULL); @@ -179,7 +195,7 @@ void ui_display_wnd_table_cards(const table_stacks_t *ts, const bool highlight, } /** - * Displays the stack points window. + * Displays the stack points window. One stack points entry can be highlighted (this is used for visualization of a selected stack). * @param[in] ts The table stacks used for calculation of stack points * @param[in] highlight If true, stack points will be highlighted * @param[in] highlighted_points The stack points to highlight. Only used, if highlight is true @@ -209,7 +225,7 @@ void ui_display_wnd_stack_points(const table_stacks_t *ts, const bool highlight, } /** - * Displays the current state window, showing all player names and their open cards and the client player's score. + * Displays the current state window, showing all player names and their open cards and the client player's score. A player from the player list can be highlighted (used to display the player whose turn it is). * @param[in] pl Player list. List has to be sorted by open card, in ascending order * @param[in] num_players The number of players to show a player name and open card for * @param[in] highlight If true, a player in the player table will be highlighted @@ -265,7 +281,7 @@ void ui_display_wnd_current_state(const player_list_t *pl, const uint8_t num_pla } /** - * Displays the message window. + * Displays the message window. The displayed message can be highlighted. * @param[in] message The message to display * @param[in] highlight If true, the message will be highlighted */ @@ -285,7 +301,7 @@ void ui_display_wnd_messages(const char *message, const bool highlight) } /** - * Displays the hand cards window. + * Displays the hand cards window. A single card from the hand can be highlighted (used for visualization of a selected card). * @param[in] h The hand that will be displayed. h must be sorted in ascending order * @param[in] highlight If true, a card will be highlighted * @param[in] highlighted_card The card to highlight. Only used, if highlight is true @@ -337,7 +353,10 @@ void ui_display_wnd_hand_cards(const hand_t *h, const bool highlight, const uint } /** - * Displays the final scores window and highlights the player. + * Displays the final scores window and highlights a given player's name and score. The players that finish the game on the first place will be highlighted in a distinct way. + * @param[in] pl Player list. List has to be sorted by score, in ascending order + * @param[in] num_players The number of players to show a player name and score for + * @param[in] highlighted_player The player to highlight */ void ui_display_wnd_final_scores(const player_list_t *pl, const uint8_t num_players, const player_id_t highlighted_player) { @@ -396,6 +415,11 @@ void ui_display_wnd_final_scores(const player_list_t *pl, const uint8_t num_play } while (KEY_RETURN != key && KEY_ESCAPE != key); } +/** + * Starts the card chooser. The player has to pick a card from a given hand. The hand and a message that the player has to pick a card will be displayed. The function blocks until the player has made his choice. The index of the picked card within the hand will be returned. + * @param[in] h The hand to pick a card from + * @return The index of the chosen card +*/ uint8_t ui_choose_card(hand_t *h) { assert(h != NULL); @@ -454,6 +478,11 @@ uint8_t ui_choose_card(hand_t *h) return chosen_card_idx; } +/** + * Starts the card stack chooser. The player has to pick a card stack from given table stacks. The table stacks, stack points and a message that the player has to pick a card stack will be displayed. The function blocks until the player has made his choice. The index of the picked card stack within the table stacks will be returned. + * @param[in] ts The table stacks to pick a card stack from + * @return The index of the chosen card stack +*/ uint8_t ui_choose_stack(const table_stacks_t *ts) { assert(ts != NULL); @@ -505,6 +534,9 @@ uint8_t ui_choose_stack(const table_stacks_t *ts) return chosen_stack_idx; } +/** + * Updates the screen. +*/ void ui_update(void) { doupdate(); -- cgit v1.2.3