summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authormvglasow <michael -at- vonglasow.com>2015-11-12 15:29:55 +0100
committermvglasow <michael -at- vonglasow.com>2015-11-12 15:29:55 +0100
commitd54b83bde6a667b33ff3d700b12f4ec68a066037 (patch)
tree05312bdfcadeb586c98c5fe8829c6546299039a7
parent8f416fffaddeb3cce7172359222cf390e88f2ec9 (diff)
downloadnavit-d54b83bde6a667b33ff3d700b12f4ec68a066037.tar.gz
Refactor:gui_internal:Some documentation updates
Signed-off-by: mvglasow <michael -at- vonglasow.com>
-rw-r--r--navit/gui/internal/gui_internal.c12
-rw-r--r--navit/gui/internal/gui_internal_command.c13
-rw-r--r--navit/gui/internal/gui_internal_widget.c120
3 files changed, 98 insertions, 47 deletions
diff --git a/navit/gui/internal/gui_internal.c b/navit/gui/internal/gui_internal.c
index 23d4d24c6..3f65397dc 100644
--- a/navit/gui/internal/gui_internal.c
+++ b/navit/gui/internal/gui_internal.c
@@ -1078,6 +1078,18 @@ gui_internal_cmd_delete_waypoint(struct gui_priv *this, struct widget *wm, void
}
+/**
+ * @brief
+ *
+ * One of {@code pc_in} or {@code g_in} must be supplied, the other should be {@code NULL}.
+ *
+ * @param this The internal GUI instance
+ * @param pc_in Projected coordinates of the position
+ * @param g_in WGS84 coordinates of the position
+ * @param wm
+ * @param name The display name for the position
+ * @param flags Flags specifying the operations available from the GUI
+ */
/* meaning of the bits in "flags":
* 1: "Streets"
* 2: "House numbers"
diff --git a/navit/gui/internal/gui_internal_command.c b/navit/gui/internal/gui_internal_command.c
index 62d7a0f35..b7f561a91 100644
--- a/navit/gui/internal/gui_internal_command.c
+++ b/navit/gui/internal/gui_internal_command.c
@@ -47,6 +47,8 @@ extern char *version;
*
* @param gc A WGS84 coordinate pair
* @param sep The separator character to insert between latitude and longitude
+ *
+ * @return The coordinates as a formatted string
*/
static char *
coordinates_geo(const struct coord_geo *gc, char sep)
@@ -89,6 +91,17 @@ coordinates_geo(const struct coord_geo *gc, char sep)
return ret;
}
+/**
+ * @brief Converts a coordinate pair to its WGS84 string representation.
+ *
+ * This function takes a coordinate pair, transforms it to WGS84 and converts it to a string of the form
+ * {@code 45°28'0" N 9°11'26" E}.
+ *
+ * @param gc A coordinate pair
+ * @param sep The separator character to insert between latitude and longitude
+ *
+ * @return The coordinates as a formatted string
+ */
char *
gui_internal_coordinates(struct pcoord *pc, char sep)
{
diff --git a/navit/gui/internal/gui_internal_widget.c b/navit/gui/internal/gui_internal_widget.c
index ebd91d200..8a72587d6 100644
--- a/navit/gui/internal/gui_internal_widget.c
+++ b/navit/gui/internal/gui_internal_widget.c
@@ -108,6 +108,12 @@ gui_internal_image_render(struct gui_priv *this, struct widget *w)
}
}
+/**
+ * @brief Renders a label.
+ *
+ * @param this The internal GUI instance
+ * @param w The widget to render
+ */
static void
gui_internal_label_render(struct gui_priv *this, struct widget *w)
{
@@ -138,9 +144,15 @@ gui_internal_label_render(struct gui_priv *this, struct widget *w)
}
/**
- * @brief A text box is a widget that renders a text string containing newlines.
+ * @brief Creates a text box.
+ *
+ * A text box is a widget that renders a text string containing newlines.
* The string will be broken up into label widgets at each newline with a vertical layout.
*
+ * @param this The internal GUI instance
+ * @param text The text to be displayed in the text box
+ * @param font The font to use for the text
+ * @param flags
*/
struct widget *
gui_internal_text_font_new(struct gui_priv *this, const char *text, int font, enum flags flags)
@@ -342,9 +354,10 @@ static void gui_internal_box_render(struct gui_priv *this, struct widget *w)
/**
- * @brief Compute the size and location for the widget.
- *
+ * @brief Computes the size and location for the widget.
*
+ * @param this The internal GUI instance
+ * @param w The widget to render
*/
static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
{
@@ -366,7 +379,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
}
- /**
+ /*
* count the number of children
*/
l=w->children;
@@ -378,7 +391,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
orientation=orientation_horizontal;
switch (orientation) {
case orientation_horizontal:
- /**
+ /*
* For horizontal orientation:
* pack each child and find the largest height and
* compute the total width. x spacing (spx) is considered
@@ -407,7 +420,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
expandd=expand=1;
break;
case orientation_vertical:
- /**
+ /*
* For vertical layouts:
* We pack each child and compute the largest width and
* the total height. y spacing (spy) is considered
@@ -436,7 +449,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
expandd=expand=1;
break;
case orientation_horizontal_vertical:
- /**
+ /*
* For horizontal_vertical orientation
* pack the children.
* Compute the largest height and largest width.
@@ -467,7 +480,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
expandd=expand=1;
break;
default:
- /**
+ /*
* No orientation was specified.
* width and height are both 0.
* The width & height of this widget
@@ -487,7 +500,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
expand=100;
#endif
- /**
+ /*
* At this stage the width and height of this
* widget has been computed.
* We now make a second pass assigning heights,
@@ -609,7 +622,7 @@ static void gui_internal_box_pack(struct gui_priv *this, struct widget *w)
gui_internal_box_pack(this, w);
return;
}
- /**
+ /*
* Call pack again on each child,
* the child has now had its size and coordinates
* set so they can repack their children.
@@ -798,7 +811,7 @@ gui_internal_scroll_buttons_init(struct gui_priv *this, struct widget *widget, s
*
* @param this The graphics context.
* @param flags widget sizing flags.
- * @returns The newly created widget
+ * @return The newly created widget
*/
struct widget * gui_internal_widget_table_new(struct gui_priv * this, enum flags flags, int buttons)
{
@@ -828,8 +841,12 @@ struct widget * gui_internal_widget_table_new(struct gui_priv * this, enum flags
/**
* @brief Clears all the rows from the table.
+ *
* This function removes all rows from a table.
* New rows can later be added to the table.
+ *
+ * @param this The internal GUI instance
+ * @param table The table widget
*/
void gui_internal_widget_table_clear(struct gui_priv * this,struct widget * table)
{
@@ -858,9 +875,11 @@ void gui_internal_widget_table_clear(struct gui_priv * this,struct widget * tabl
}
/**
- * @brief Move GList pointer to the next table row, skipping other table children (button box, for example).
- * @param row GList pointer into the children list
- * @returns GList pointer to the next row in the children list, or NULL if there are no any rows left.
+ * @brief Moves GList pointer to the next table row, skipping other table children (button box, for example).
+ *
+ * @param row GList pointer into the children list
+ *
+ * @return GList pointer to the next row in the children list, or NULL if there are no any rows left.
*/
GList *
gui_internal_widget_table_next_row(GList * row)
@@ -873,9 +892,11 @@ gui_internal_widget_table_next_row(GList * row)
}
/**
- * @brief Move GList pointer to the previous table row, skipping other table children (button box, for example).
- * @param row GList pointer into the children list
- * @returns GList pointer to the previous row in the children list, or NULL if there are no any rows left.
+ * @brief Moves GList pointer to the previous table row, skipping other table children (button box, for example).
+ *
+ * @param row GList pointer into the children list
+ *
+ * @return GList pointer to the previous row in the children list, or NULL if there are no any rows left.
*/
GList *
gui_internal_widget_table_prev_row(GList * row)
@@ -888,9 +909,11 @@ gui_internal_widget_table_prev_row(GList * row)
}
/**
- * @brief Move GList pointer to the first table row, skipping other table children (button box, for example).
- * @param row GList pointer into the children list
- * @returns GList pointer to the first row in the children list, or NULL if table is empty.
+ * @brief Moves GList pointer to the first table row, skipping other table children (button box, for example).
+ *
+ * @param row GList pointer into the children list
+ *
+ * @return GList pointer to the first row in the children list, or NULL if table is empty.
*/
GList *
gui_internal_widget_table_first_row(GList * row)
@@ -905,8 +928,9 @@ gui_internal_widget_table_first_row(GList * row)
}
/**
- * @brief Get GList pointer to the table row drawn on the top of the screen.
- * @returns GList pointer to the top row in the children list, or NULL.
+ * @brief Gets GList pointer to the table row drawn on the top of the screen.
+ *
+ * @return GList pointer to the top row in the children list, or NULL.
*/
GList *
gui_internal_widget_table_top_row(struct gui_priv *this, struct widget * table)
@@ -919,8 +943,9 @@ gui_internal_widget_table_top_row(struct gui_priv *this, struct widget * table)
}
/**
- * @brief Set internal top row pointer of the table to point to a given row widget.
- * @returns GList pointer to the top row in the children list of the table.
+ * @brief Sets internal top row pointer of the table to point to a given row widget.
+ *
+ * @return GList pointer to the top row in the children list of the table.
*/
GList *
gui_internal_widget_table_set_top_row(struct gui_priv *this, struct widget * table, struct widget *row)
@@ -939,10 +964,12 @@ gui_internal_widget_table_set_top_row(struct gui_priv *this, struct widget * tab
/**
- * Creates a new table_row widget.
+ * @brief Creates a new table_row widget.
+ *
* @param this The graphics context
* @param flags Sizing flags for the row
- * @returns The new table_row widget.
+ *
+ * @return The new table_row widget.
*/
struct widget *
gui_internal_widget_table_row_new(struct gui_priv * this, enum flags flags)
@@ -958,6 +985,7 @@ gui_internal_widget_table_row_new(struct gui_priv * this, enum flags flags)
/**
* @brief Computes the column dimensions for the table.
*
+ * @param this The internal GUI instance
* @param w The table widget to compute dimensions for.
*
* This function examines all of the rows and columns for the table w
@@ -983,7 +1011,7 @@ gui_internal_compute_table_dimensions(struct gui_priv * this,struct widget * w)
int total_width=0;
int column_count=0;
- /**
+ /*
* Scroll through the the table and
* 1. Compute the maximum width + height of each column across all rows.
*/
@@ -1038,7 +1066,7 @@ gui_internal_compute_table_dimensions(struct gui_priv * this,struct widget * w)
} /*row loop */
- /**
+ /*
* If the width of all columns is less than the width off
* the table expand each cell proportionally.
*
@@ -1057,12 +1085,11 @@ gui_internal_compute_table_dimensions(struct gui_priv * this,struct widget * w)
/**
* @brief Computes the height and width for the table.
*
- * The height and widht are computed to display all cells in the table
+ * The height and width are computed to display all cells in the table
* at the requested height/width.
*
* @param this The graphics context
* @param w The widget to pack.
- *
*/
void
gui_internal_table_pack(struct gui_priv * this, struct widget * w)
@@ -1109,7 +1136,7 @@ gui_internal_table_pack(struct gui_priv * this, struct widget * w)
if(w->h + w->c.y > this->root.h )
{
- /**
+ /*
* Do not allow the widget to exceed the screen.
*
*/
@@ -1122,7 +1149,7 @@ gui_internal_table_pack(struct gui_priv * this, struct widget * w)
}
- /**
+ /*
* Deallocate column descriptions.
*/
g_list_foreach(column_data,(GFunc)g_free,NULL);
@@ -1133,7 +1160,7 @@ gui_internal_table_pack(struct gui_priv * this, struct widget * w)
/**
- * @brief Invalidates coordinates for previosly rendered table widget rows.
+ * @brief Invalidates coordinates for previously rendered table widget rows.
*
* @param table_data Data from the table object.
*/
@@ -1182,7 +1209,7 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
return;
y=w->p.y;
gui_internal_table_hide_rows(table_data);
- /**
+ /*
* Skip rows that are on previous pages.
*/
cur_row = w->children;
@@ -1193,7 +1220,7 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
} else {
table_data->top_row=NULL;
}
- /**
+ /*
* Loop through each row. Drawing each cell with the proper sizes,
* at the proper positions.
*/
@@ -1298,7 +1325,7 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
gui_internal_widget_render(this,table_data->scroll_buttons.button_box);
}
- /**
+ /*
* Deallocate column descriptions.
*/
g_list_foreach(column_desc,(GFunc)g_free,NULL);
@@ -1306,12 +1333,14 @@ gui_internal_table_render(struct gui_priv * this, struct widget * w)
}
/**
- * @brief handles the 'next page' table event.
+ * @brief Handles the 'next page' table event.
+ *
* A callback function that is invoked when the 'next page' button is pressed
* to advance the contents of a table widget.
*
* @param this The graphics context.
* @param wm The button widget that was pressed.
+ * @param data
*/
void
gui_internal_table_button_next(struct gui_priv * this, struct widget * wm, void *data)
@@ -1345,7 +1374,8 @@ gui_internal_table_button_next(struct gui_priv * this, struct widget * wm, void
/**
- * @brief handles the 'previous page' table event.
+ * @brief Handles the 'previous page' table event.
+ *
* A callback function that is invoked when the 'previous page' button is pressed
* to go back in the contents of a table widget.
*
@@ -1386,18 +1416,14 @@ gui_internal_table_button_prev(struct gui_priv * this, struct widget * wm, void
/**
- * @brief deallocates a table_data structure.
+ * @brief Deallocates a table_data structure.
*
+ * @note button_box and its children (next_button,prev_button)
+ * have their memory managed by the table itself.
+ *
+ * @param p The table_data structure
*/
void gui_internal_table_data_free(void * p)
{
-
-
- /**
- * @note button_box and its children (next_button,prev_button)
- * have their memory managed by the table itself.
- */
g_free(p);
-
-
}