[A] Added tutorial from github wiki to repository
This commit is contained in:
seleznevae
345
docs/tutorial/C_API/Border-styles.md
Normal file
345
docs/tutorial/C_API/Border-styles.md
Normal file
@@ -0,0 +1,345 @@
|
||||
- [Change border style](#change-border-style)
|
||||
- [Custom border styles](#custom-border-styles)
|
||||
- [Built-in border styles](#built-in-border-styles)
|
||||
|
||||
## Change border style
|
||||
**libfort** has a number of built-in border styles.
|
||||
To change border style of **libfort** tables one can use `ft_set_default_border_style`, `ft_set_border_style` functions:
|
||||
```C
|
||||
/* Change border style of all libfort tables that will be created */
|
||||
int ft_set_default_border_style(const struct ft_border_style *style);
|
||||
/* Change border style of a particular table */
|
||||
int ft_set_border_style(ft_table_t *table, const struct ft_border_style *style);
|
||||
|
||||
/**
|
||||
* Structure describing border appearance.
|
||||
*/
|
||||
struct ft_border_chars {
|
||||
const char *top_border_ch;
|
||||
const char *separator_ch;
|
||||
const char *bottom_border_ch;
|
||||
const char *side_border_ch;
|
||||
const char *out_intersect_ch;
|
||||
const char *in_intersect_ch;
|
||||
};
|
||||
|
||||
/**
|
||||
* Structure describing border style.
|
||||
*/
|
||||
struct ft_border_style {
|
||||
struct ft_border_chars border_chs;
|
||||
struct ft_border_chars header_border_chs;
|
||||
const char *hor_separator_char;
|
||||
};
|
||||
```
|
||||
|
||||
Here is a simple example of creating table and setting built-in border style:
|
||||
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
/* Set border style */
|
||||
ft_set_border_style(table, FT_BASIC_STYLE);
|
||||
|
||||
ft_set_cell_prop(table, FT_ANY_ROW, 0, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_CENTER);
|
||||
ft_set_cell_prop(table, FT_ANY_ROW, 1, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_LEFT);
|
||||
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "Rank", "Title", "Year", "Rating");
|
||||
|
||||
ft_write_ln(table, "1", "The Shawshank Redemption", "1994", "9.5");
|
||||
ft_write_ln(table, "2", "12 Angry Men", "1957", "8.8");
|
||||
ft_write_ln(table, "3", "It's a Wonderful Life", "1946", "8.6");
|
||||
ft_add_separator(table);
|
||||
ft_write_ln(table, "4", "2001: A Space Odyssey", "1968", "8.5");
|
||||
ft_write_ln(table, "5", "Blade Runner", "1982", "8.1");
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
Output:
|
||||
```text
|
||||
+------+--------------------------+------+--------+
|
||||
| Rank | Title | Year | Rating |
|
||||
+------+--------------------------+------+--------+
|
||||
| 1 | The Shawshank Redemption | 1994 | 9.5 |
|
||||
| 2 | 12 Angry Men | 1957 | 8.8 |
|
||||
| 3 | It's a Wonderful Life | 1946 | 8.6 |
|
||||
+------+--------------------------+------+--------+
|
||||
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
|
||||
| 5 | Blade Runner | 1982 | 8.1 |
|
||||
+------+--------------------------+------+--------+
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Custom border styles
|
||||
`ft_set_default_border_style`, `ft_set_border_style` can be used to set custom border styles:
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
|
||||
|
||||
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
|
||||
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
|
||||
ft_add_separator(table);
|
||||
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
|
||||
|
||||
/* Set custom border style */
|
||||
struct ft_border_chars border;
|
||||
border.top_border_ch = "^";
|
||||
border.separator_ch = "=";
|
||||
border.bottom_border_ch = "v";
|
||||
border.side_border_ch = "|";
|
||||
border.out_intersect_ch = "x";
|
||||
border.in_intersect_ch = "x";
|
||||
|
||||
struct ft_border_style border_style;
|
||||
memcpy(&border_style.border_chs, &border, sizeof(struct ft_border_chars));
|
||||
memcpy(&border_style.header_border_chs, &border, sizeof(struct ft_border_chars));
|
||||
border_style.hor_separator_char = "~";
|
||||
ft_set_border_style(table, &border_style);
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
x^^^x^^^^^^^^^^^^x^^^^^^^^^^x^^^^^^^^^^^x
|
||||
| N | Driver | Time | Avg Speed |
|
||||
x===x============x==========x===========x
|
||||
| 1 | Ricciardo | 1:25.945 | 222.128 |
|
||||
x===x============x==========x===========x
|
||||
| 2 | Hamilton | 1:26.373 | 221.027 |
|
||||
x~~~x~~~~~~~~~~~~x~~~~~~~~~~x~~~~~~~~~~~x
|
||||
| 3 | Verstappen | 1:26.469 | 220.782 |
|
||||
xvvvxvvvvvvvvvvvvxvvvvvvvvvvxvvvvvvvvvvvx
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Built-in border styles
|
||||
|
||||
## FT_BASIC_STYLE
|
||||
```text
|
||||
+------+--------------------------+------+--------+
|
||||
| Rank | Title | Year | Rating |
|
||||
+------+--------------------------+------+--------+
|
||||
| 1 | The Shawshank Redemption | 1994 | 9.5 |
|
||||
| 2 | 12 Angry Men | 1957 | 8.8 |
|
||||
| 3 | It's a Wonderful Life | 1946 | 8.6 |
|
||||
+------+--------------------------+------+--------+
|
||||
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
|
||||
| 5 | Blade Runner | 1982 | 8.1 |
|
||||
+------+--------------------------+------+--------+
|
||||
```
|
||||
|
||||
## FT_BASIC2_STYLE
|
||||
```text
|
||||
+------+--------------------------+------+--------+
|
||||
| Rank | Title | Year | Rating |
|
||||
+------+--------------------------+------+--------+
|
||||
| 1 | The Shawshank Redemption | 1994 | 9.5 |
|
||||
+------+--------------------------+------+--------+
|
||||
| 2 | 12 Angry Men | 1957 | 8.8 |
|
||||
+------+--------------------------+------+--------+
|
||||
| 3 | It's a Wonderful Life | 1946 | 8.6 |
|
||||
+------+--------------------------+------+--------+
|
||||
| 4 | 2001: A Space Odyssey | 1968 | 8.5 |
|
||||
+------+--------------------------+------+--------+
|
||||
| 5 | Blade Runner | 1982 | 8.1 |
|
||||
+------+--------------------------+------+--------+
|
||||
```
|
||||
|
||||
## FT_SIMPLE_STYLE
|
||||
```text
|
||||
|
||||
Rank Title Year Rating
|
||||
------ -------------------------- ------ --------
|
||||
1 The Shawshank Redemption 1994 9.5
|
||||
2 12 Angry Men 1957 8.8
|
||||
3 It's a Wonderful Life 1946 8.6
|
||||
------ -------------------------- ------ --------
|
||||
4 2001: A Space Odyssey 1968 8.5
|
||||
5 Blade Runner 1982 8.1
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
## FT_PLAIN_STYLE
|
||||
```text
|
||||
-------------------------------------------------
|
||||
Rank Title Year Rating
|
||||
-------------------------------------------------
|
||||
1 The Shawshank Redemption 1994 9.5
|
||||
2 12 Angry Men 1957 8.8
|
||||
3 It's a Wonderful Life 1946 8.6
|
||||
-------------------------------------------------
|
||||
4 2001: A Space Odyssey 1968 8.5
|
||||
5 Blade Runner 1982 8.1
|
||||
```
|
||||
|
||||
## FT_DOT_STYLE
|
||||
```text
|
||||
...................................................
|
||||
: Rank : Title : Year : Rating :
|
||||
:......:..........................:......:........:
|
||||
: 1 : The Shawshank Redemption : 1994 : 9.5 :
|
||||
: 2 : 12 Angry Men : 1957 : 8.8 :
|
||||
: 3 : It's a Wonderful Life : 1946 : 8.6 :
|
||||
:......:..........................:......:........:
|
||||
: 4 : 2001: A Space Odyssey : 1968 : 8.5 :
|
||||
: 5 : Blade Runner : 1982 : 8.1 :
|
||||
:......:..........................:......:........:
|
||||
```
|
||||
|
||||
|
||||
|
||||
## FT_EMPTY_STYLE
|
||||
```text
|
||||
Rank Title Year Rating
|
||||
1 The Shawshank Redemption 1994 9.5
|
||||
2 12 Angry Men 1957 8.8
|
||||
3 It's a Wonderful Life 1946 8.6
|
||||
|
||||
4 2001: A Space Odyssey 1968 8.5
|
||||
5 Blade Runner 1982 8.1
|
||||
```
|
||||
|
||||
## FT_EMPTY2_STYLE
|
||||
```text
|
||||
|
||||
Rank Title Year Rating
|
||||
1 The Shawshank Redemption 1994 9.5
|
||||
2 12 Angry Men 1957 8.8
|
||||
3 It's a Wonderful Life 1946 8.6
|
||||
|
||||
4 2001: A Space Odyssey 1968 8.5
|
||||
5 Blade Runner 1982 8.1
|
||||
|
||||
```
|
||||
|
||||
|
||||
## FT_SOLID_STYLE
|
||||
```text
|
||||
┌──────┬──────────────────────────┬──────┬────────┐
|
||||
│ Rank │ Title │ Year │ Rating │
|
||||
├──────┼──────────────────────────┼──────┼────────┤
|
||||
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
|
||||
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
|
||||
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
|
||||
├──────┼──────────────────────────┼──────┼────────┤
|
||||
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
|
||||
│ 5 │ Blade Runner │ 1982 │ 8.1 │
|
||||
└──────┴──────────────────────────┴──────┴────────╯
|
||||
```
|
||||
|
||||
## FT_SOLID_ROUND_STYLE
|
||||
```text
|
||||
╭──────┬──────────────────────────┬──────┬────────╮
|
||||
│ Rank │ Title │ Year │ Rating │
|
||||
├──────┼──────────────────────────┼──────┼────────┤
|
||||
│ 1 │ The Shawshank Redemption │ 1994 │ 9.5 │
|
||||
│ 2 │ 12 Angry Men │ 1957 │ 8.8 │
|
||||
│ 3 │ It's a Wonderful Life │ 1946 │ 8.6 │
|
||||
├──────┼──────────────────────────┼──────┼────────┤
|
||||
│ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 │
|
||||
│ 5 │ Blade Runner │ 1982 │ 8.1 │
|
||||
╰──────┴──────────────────────────┴──────┴────────╯
|
||||
```
|
||||
|
||||
## FT_NICE_STYLE
|
||||
```text
|
||||
╔══════╦══════════════════════════╦══════╦════════╗
|
||||
║ Rank ║ Title ║ Year ║ Rating ║
|
||||
╠══════╬══════════════════════════╬══════╬════════╣
|
||||
║ 1 ║ The Shawshank Redemption ║ 1994 ║ 9.5 ║
|
||||
║ 2 ║ 12 Angry Men ║ 1957 ║ 8.8 ║
|
||||
║ 3 ║ It's a Wonderful Life ║ 1946 ║ 8.6 ║
|
||||
╟──────╫──────────────────────────╫──────╫────────╢
|
||||
║ 4 ║ 2001: A Space Odyssey ║ 1968 ║ 8.5 ║
|
||||
║ 5 ║ Blade Runner ║ 1982 ║ 8.1 ║
|
||||
╚══════╩══════════════════════════╩══════╩════════╝
|
||||
```
|
||||
|
||||
## FT_DOUBLE_STYLE
|
||||
```text
|
||||
╔══════╦══════════════════════════╦══════╦════════╗
|
||||
║ Rank ║ Title ║ Year ║ Rating ║
|
||||
╠══════╬══════════════════════════╬══════╬════════╣
|
||||
║ 1 ║ The Shawshank Redemption ║ 1994 ║ 9.5 ║
|
||||
║ 2 ║ 12 Angry Men ║ 1957 ║ 8.8 ║
|
||||
║ 3 ║ It's a Wonderful Life ║ 1946 ║ 8.6 ║
|
||||
╠══════╬══════════════════════════╬══════╬════════╣
|
||||
║ 4 ║ 2001: A Space Odyssey ║ 1968 ║ 8.5 ║
|
||||
║ 5 ║ Blade Runner ║ 1982 ║ 8.1 ║
|
||||
╚══════╩══════════════════════════╩══════╩════════╝
|
||||
```
|
||||
|
||||
|
||||
## FT_DOUBLE2_STYLE
|
||||
```text
|
||||
╔══════╤══════════════════════════╤══════╤════════╗
|
||||
║ Rank │ Title │ Year │ Rating ║
|
||||
╠══════╪══════════════════════════╪══════╪════════╣
|
||||
║ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ║
|
||||
╟──────┼──────────────────────────┼──────┼────────╢
|
||||
║ 2 │ 12 Angry Men │ 1957 │ 8.8 ║
|
||||
╟──────┼──────────────────────────┼──────┼────────╢
|
||||
║ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ║
|
||||
╠══════╪══════════════════════════╪══════╪════════╣
|
||||
║ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ║
|
||||
╟──────┼──────────────────────────┼──────┼────────╢
|
||||
║ 5 │ Blade Runner │ 1982 │ 8.1 ║
|
||||
╚══════╧══════════════════════════╧══════╧════════╝
|
||||
```
|
||||
|
||||
## FT_BOLD_STYLE
|
||||
```text
|
||||
┏━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┳━━━━━━━━┓
|
||||
┃ Rank ┃ Title ┃ Year ┃ Rating ┃
|
||||
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
|
||||
┃ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ┃
|
||||
┃ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ┃
|
||||
┃ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ┃
|
||||
┣━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━┫
|
||||
┃ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ┃
|
||||
┃ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ┃
|
||||
┗━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━┻━━━━━━━━┛
|
||||
```
|
||||
|
||||
|
||||
|
||||
## FT_BOLD2_STYLE
|
||||
```text
|
||||
┏━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━┯━━━━━━━━┓
|
||||
┃ Rank │ Title │ Year │ Rating ┃
|
||||
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
|
||||
┃ 1 │ The Shawshank Redemption │ 1994 │ 9.5 ┃
|
||||
┠──────┼──────────────────────────┼──────┼────────┨
|
||||
┃ 2 │ 12 Angry Men │ 1957 │ 8.8 ┃
|
||||
┠──────┼──────────────────────────┼──────┼────────┨
|
||||
┃ 3 │ It's a Wonderful Life │ 1946 │ 8.6 ┃
|
||||
┣━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━┿━━━━━━┿━━━━━━━━┫
|
||||
┃ 4 │ 2001: A Space Odyssey │ 1968 │ 8.5 ┃
|
||||
┠──────┼──────────────────────────┼──────┼────────┨
|
||||
┃ 5 │ Blade Runner │ 1982 │ 8.1 ┃
|
||||
┗━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━┷━━━━━━━━┛
|
||||
```
|
||||
|
||||
|
||||
## FT_FRAME_STYLE
|
||||
```text
|
||||
▛▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▜
|
||||
▌ Rank ┃ Title ┃ Year ┃ Rating ▐
|
||||
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
|
||||
▌ 1 ┃ The Shawshank Redemption ┃ 1994 ┃ 9.5 ▐
|
||||
▌ 2 ┃ 12 Angry Men ┃ 1957 ┃ 8.8 ▐
|
||||
▌ 3 ┃ It's a Wonderful Life ┃ 1946 ┃ 8.6 ▐
|
||||
▌━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━╋━━━━━━━━▐
|
||||
▌ 4 ┃ 2001: A Space Odyssey ┃ 1968 ┃ 8.5 ▐
|
||||
▌ 5 ┃ Blade Runner ┃ 1982 ┃ 8.1 ▐
|
||||
▙▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▟
|
||||
```
|
||||
|
||||
146
docs/tutorial/C_API/Cell-and-table-properties.md
Normal file
146
docs/tutorial/C_API/Cell-and-table-properties.md
Normal file
@@ -0,0 +1,146 @@
|
||||
- [Cell properties](#cell-properties)
|
||||
- [Table properties](#table-properties)
|
||||
|
||||
## Cell properties
|
||||
By default all cells created in **libfort** tables will have the same properties. So for example if you want your first row to be a header for your table you should explicitly specify corresponding options.
|
||||
|
||||
To change cell properties one should use functions `ft_set_cell_prop` and `ft_set_default_cell_prop`:
|
||||
```C
|
||||
/* Change cell properties for all new tables */
|
||||
int ft_set_default_cell_prop(uint32_t property, int value);
|
||||
/* Change cell properties for the particular table */
|
||||
int ft_set_cell_prop(ft_table_t *table, size_t row, size_t col, uint32_t property, int value);
|
||||
```
|
||||
To change cell properties for all cells in the row, in the column or for the entire table use macros `FT_ANY_COLUMN` and `FT_ANY_ROW`:
|
||||
|
||||
| Example | Use case |
|
||||
| --------------------------------------------------------------------- |:-----------------------------------------|
|
||||
| `ft_set_cell_prop(table, row, FT_ANY_COLUMN, property, value)` | Set property for all cells in the row |
|
||||
| `ft_set_cell_prop(table, FT_ANY_ROW, col, property, value)` | Set property for all cells in the column |
|
||||
| `ft_set_cell_prop(table, FT_ANY_ROW, FT_ANY_COLUMN, property, value)` | Set property for all cells in the table |
|
||||
|
||||
Here is a simple example:
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
|
||||
|
||||
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
|
||||
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
|
||||
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
|
||||
/* Set right text alignment for cell(0, 1) */
|
||||
ft_set_cell_prop(table, 0, 1, FT_CPROP_TEXT_ALIGN, FT_ALIGNED_RIGHT);
|
||||
/* Set minimum cell width to 30 for cell(0, 1) */
|
||||
ft_set_cell_prop(table, 0, 1, FT_CPROP_MIN_WIDTH, 30);
|
||||
/* Set left padding = 3 for all cells in the 3rd column */
|
||||
ft_set_cell_prop(table, FT_ANY_ROW, 3, FT_CPROP_LEFT_PADDING, 3);
|
||||
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
|
||||
```
|
||||
+---+------------------------------+----------+-------------+
|
||||
| N | Driver | Time | Avg Speed |
|
||||
+---+------------------------------+----------+-------------+
|
||||
| 1 | Ricciardo | 1:25.945 | 222.128 |
|
||||
| 2 | Hamilton | 1:26.373 | 221.027 |
|
||||
| 3 | Verstappen | 1:26.469 | 220.782 |
|
||||
+---+------------------------------+----------+-------------+
|
||||
```
|
||||
|
||||
List of all possible cell properties:
|
||||
|
||||
| Property | Description | Possible values |
|
||||
| ------------------------- |--------------------------------| ------------------------|
|
||||
| FT_CPROP_MIN_WIDTH | Minimum width | Non negative int |
|
||||
| FT_CPROP_TEXT_ALIGN | Text alignment | `enum ft_text_alignment`|
|
||||
| FT_CPROP_TOP_PADDING | Top padding for cell content | Non negative int |
|
||||
| FT_CPROP_BOTTOM_PADDING | Bottom padding for cell content| Non negative int |
|
||||
| FT_CPROP_LEFT_PADDING | Left padding for cell content | Non negative int |
|
||||
| FT_CPROP_EMPTY_STR_HEIGHT | Right padding for cell content | Non negative int |
|
||||
| FT_CPROP_ROW_TYPE | Row type | `enum ft_row_type` |
|
||||
| FT_CPROP_CONT_FG_COLOR | Content foreground color | `enum ft_color` |
|
||||
| FT_CPROP_CELL_BG_COLOR | Cell background color | `enum ft_color` |
|
||||
| FT_CPROP_CONT_BG_COLOR | Content background color | `enum ft_color` |
|
||||
| FT_CPROP_CELL_TEXT_STYLE | Cell text style | `enum ft_text_style` |
|
||||
| FT_CPROP_CONT_TEXT_STYLE | Content text style | `enum ft_text_style` |
|
||||
|
||||
where
|
||||
```C
|
||||
enum ft_text_alignment {
|
||||
FT_ALIGNED_LEFT = 0, /**< Align left */
|
||||
FT_ALIGNED_CENTER, /**< Align center */
|
||||
FT_ALIGNED_RIGHT /**< Align right */
|
||||
};
|
||||
|
||||
enum ft_row_type {
|
||||
FT_ROW_COMMON = 0, /**< Common row */
|
||||
FT_ROW_HEADER /**< Header row */
|
||||
};
|
||||
|
||||
enum ft_color {
|
||||
FT_COLOR_DEFAULT = 0,
|
||||
FT_COLOR_BLACK = 1,
|
||||
FT_COLOR_RED = 2,
|
||||
FT_COLOR_GREEN = 3,
|
||||
FT_COLOR_YELLOW = 4,
|
||||
FT_COLOR_BLUE = 5,
|
||||
FT_COLOR_MAGENTA = 6,
|
||||
FT_COLOR_CYAN = 7,
|
||||
FT_COLOR_LIGHT_GRAY = 8,
|
||||
FT_COLOR_DARK_GRAY = 9,
|
||||
FT_COLOR_LIGHT_RED = 10,
|
||||
FT_COLOR_LIGHT_GREEN = 11,
|
||||
FT_COLOR_LIGHT_YELLOW = 12,
|
||||
FT_COLOR_LIGHT_BLUE = 13,
|
||||
FT_COLOR_LIGHT_MAGENTA = 15,
|
||||
FT_COLOR_LIGHT_CYAN = 16,
|
||||
FT_COLOR_LIGHT_WHYTE = 17
|
||||
};
|
||||
|
||||
enum ft_text_style {
|
||||
FT_TSTYLE_DEFAULT = (1U << 0),
|
||||
FT_TSTYLE_BOLD = (1U << 1),
|
||||
FT_TSTYLE_DIM = (1U << 2),
|
||||
FT_TSTYLE_ITALIC = (1U << 3),
|
||||
FT_TSTYLE_UNDERLINED = (1U << 4),
|
||||
FT_TSTYLE_BLINK = (1U << 5),
|
||||
FT_TSTYLE_INVERTED = (1U << 6),
|
||||
FT_TSTYLE_HIDDEN = (1U << 7)
|
||||
};
|
||||
```
|
||||
|
||||
## Table properties
|
||||
To change table properties use functions `ft_set_tbl_prop` and `ft_set_default_tbl_prop`:
|
||||
```C
|
||||
/* Change table properties for all new tables */
|
||||
int ft_set_default_tbl_prop(uint32_t property, int value);
|
||||
/* Change table properties for the particular table */
|
||||
int ft_set_tbl_prop(ft_table_t *table, uint32_t property, int value);
|
||||
```
|
||||
List of all possible table properties:
|
||||
|
||||
| Property | Description | Possible values |
|
||||
| ------------------------- |---------------| ------------------|
|
||||
| FT_TPROP_LEFT_MARGIN | Left margin | Non negative int |
|
||||
| FT_TPROP_TOP_MARGIN | Top margin | Non negative int |
|
||||
| FT_TPROP_RIGHT_MARGIN | Right margin | Non negative int |
|
||||
| FT_TPROP_BOTTOM_MARGIN | Bottom margin | Non negative int |
|
||||
|
||||
Table margins are used during conversion to string representation:
|
||||
```
|
||||
M ^ M
|
||||
L a | Top margin R a
|
||||
e r v i r
|
||||
f g ╔═══════╤════════╗ g g
|
||||
t i ║ Cell │ Cell ║ h i
|
||||
n ╠═══════╪════════╣ t n
|
||||
<----->║ Cell │ Cell ║<------------>
|
||||
╚═══════╧════════╝
|
||||
^
|
||||
| Bottom margin
|
||||
v
|
||||
```
|
||||
|
||||
135
docs/tutorial/C_API/Filling-tables-with-data.md
Normal file
135
docs/tutorial/C_API/Filling-tables-with-data.md
Normal file
@@ -0,0 +1,135 @@
|
||||
At each moment of time a **libfort** table has a current cell - cell to which data will be written in the next write operation.
|
||||
Functions `ft_set_cur_cell` and `ft_ln` can be used to change current cell:
|
||||
```C
|
||||
/* Set current cell to the cell with coordinates (row, col) */
|
||||
void ft_set_cur_cell(ft_table_t *table, size_t row, size_t col);
|
||||
/* Set current cell to the first cell of the next row(line) */
|
||||
void ft_ln(ft_table_t *table);
|
||||
```
|
||||
|
||||
There are a lot of functions that can be used to fill tables with data.
|
||||
All write functions are grouped in pairs (**_function_**, **_function_ln_**), where **function** writes data to a group of consecutive cells, **function_ln** does the same and moves _current-cell_ pointer to the first cell of the next row(line).
|
||||
|
||||
### ft_write, ft_write_ln
|
||||
`ft_write`, `ft_write_ln` macros can be used to write an arbitrary number of strings to the table cells.
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
|
||||
|
||||
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
|
||||
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
|
||||
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
Output:
|
||||
```text
|
||||
+---+------------+----------+-----------+
|
||||
| N | Driver | Time | Avg Speed |
|
||||
+---+------------+----------+-----------+
|
||||
| 1 | Ricciardo | 1:25.945 | 47.362 |
|
||||
| 2 | Hamilton | 1:26.373 | 35.02 |
|
||||
| 3 | Verstappen | 1:26.469 | 29.78 |
|
||||
+---+------------+----------+-----------+
|
||||
```
|
||||
|
||||
### ft_printf, ft_printf_ln
|
||||
`ft_printf`, `ft_printf_ln` functions provide habitual **printf**-like interface.
|
||||
```C
|
||||
int ft_printf(ft_table_t *table, const char *fmt, ...);
|
||||
int ft_printf_ln(ft_table_t *table, const char *fmt, ...);
|
||||
```
|
||||
By default vertical line character '|' in the format string is treated as a cell separator.
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
|
||||
|
||||
ft_printf_ln(table, "%d|%s|%s|%7.3f", 1, "Ricciardo", "1:25.945", 222.128);
|
||||
ft_printf_ln(table, "%d|%s|%s|%d.%d", 2, "Hamilton", "1:26.373", 221, 027);
|
||||
ft_printf_ln(table, "%d|%s|%s|%s.%d", 3, "Verstappen", "1:26.469", "220", 782);
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
Output:
|
||||
```text
|
||||
+---+------------+----------+-----------+
|
||||
| N | Driver | Time | Avg Speed |
|
||||
+---+------------+----------+-----------+
|
||||
| 1 | Ricciardo | 1:25.945 | 222.128 |
|
||||
| 2 | Hamilton | 1:26.373 | 221.027 |
|
||||
| 3 | Verstappen | 1:26.469 | 220.782 |
|
||||
+---+------------+----------+-----------+
|
||||
```
|
||||
|
||||
### ft_row_write, ft_row_write_ln
|
||||
`ft_row_write`, `ft_row_write_ln` functions provide means to copy string data from the string arrays to the table.
|
||||
```C
|
||||
int ft_row_write(ft_table_t *table, size_t cols, const char *row_cells[]);
|
||||
int ft_row_write_ln(ft_table_t *table, size_t cols, const char *row_cells[]);
|
||||
```
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
|
||||
const char *header[] = {"N", "Driver", "Time", "Avg Speed"};
|
||||
|
||||
const char *line_1[] = {"1", "Ricciardo", "1:25.945", "222.128"};
|
||||
const char *line_2[] = {"2", "Hamilton", "1:26.373", "221.027"};
|
||||
const char *line_3[] = {"3", "Verstappen", "1:26.469", "220.782"};
|
||||
|
||||
ft_row_write_ln(table, 4, header);
|
||||
ft_row_write_ln(table, 4, line_1);
|
||||
ft_row_write_ln(table, 4, line_2);
|
||||
ft_row_write_ln(table, 4, line_3);
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
Output:
|
||||
```text
|
||||
+---+------------+----------+-----------+
|
||||
| N | Driver | Time | Avg Speed |
|
||||
+---+------------+----------+-----------+
|
||||
| 1 | Ricciardo | 1:25.945 | 222.128 |
|
||||
| 2 | Hamilton | 1:26.373 | 221.027 |
|
||||
| 3 | Verstappen | 1:26.469 | 220.782 |
|
||||
+---+------------+----------+-----------+
|
||||
```
|
||||
|
||||
### ft_table_write, ft_table_write_ln
|
||||
`ft_table_write`, `ft_table_write_ln` functions provide means to copy string data from the 2D array to the table.
|
||||
```C
|
||||
int ft_table_write(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]);
|
||||
int ft_table_write_ln(ft_table_t *table, size_t rows, size_t cols, const char *table_cells[]);
|
||||
```
|
||||
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
|
||||
const char *data[4][4] = {
|
||||
{"N", "Driver", "Time", "Avg Speed"},
|
||||
{"1", "Ricciardo", "1:25.945", "222.128"},
|
||||
{"2", "Hamilton", "1:26.373", "221.027"},
|
||||
{"3", "Verstappen", "1:26.469", "220.782"}};
|
||||
|
||||
ft_table_write_ln(table, 4, 4, (const char **)data);
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
Output:
|
||||
```text
|
||||
+---+------------+----------+-----------+
|
||||
| N | Driver | Time | Avg Speed |
|
||||
+---+------------+----------+-----------+
|
||||
| 1 | Ricciardo | 1:25.945 | 222.128 |
|
||||
| 2 | Hamilton | 1:26.373 | 221.027 |
|
||||
| 3 | Verstappen | 1:26.469 | 220.782 |
|
||||
+---+------------+----------+-----------+
|
||||
```
|
||||
|
||||
77
docs/tutorial/C_API/Misc.md
Normal file
77
docs/tutorial/C_API/Misc.md
Normal file
@@ -0,0 +1,77 @@
|
||||
- [Row separators](#row-separators)
|
||||
- [Cell span](#cell-span)
|
||||
- [Custom memory allocators](#custom-memory-allocators)
|
||||
|
||||
## Row separators
|
||||
Explicit row separators are useful in styles without horizontal borders between rows to emphasize content. To add row separator use function `ft_add_separator`:
|
||||
```C
|
||||
int ft_add_separator(ft_table_t *table);
|
||||
```
|
||||
|
||||
Example:
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
|
||||
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
|
||||
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
|
||||
ft_add_separator(table);
|
||||
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
+---+------------+----------+---------+
|
||||
| 1 | Ricciardo | 1:25.945 | 222.128 |
|
||||
| 2 | Hamilton | 1:26.373 | 221.027 |
|
||||
+---+------------+----------+---------+
|
||||
| 3 | Verstappen | 1:26.469 | 220.782 |
|
||||
+---+------------+----------+---------+
|
||||
```
|
||||
|
||||
|
||||
## Cell span
|
||||
Cells can span two or more columns. To specify cell span use `ft_set_cell_span`:
|
||||
```C
|
||||
/* Set horizontal span for cell (row, col) */
|
||||
int ft_set_cell_span(ft_table_t *table, size_t row, size_t col, size_t hor_span);
|
||||
```
|
||||
Example:
|
||||
```C
|
||||
ft_table_t *table = ft_create_table();
|
||||
/* Change border style */
|
||||
ft_set_border_style(table, FT_DOUBLE2_STYLE);
|
||||
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "Sed", "Aenean", "Text");
|
||||
|
||||
ft_write_ln(table, "Duis", "Aliquam", "Lorem ipsum dolor");
|
||||
ft_write_ln(table, "Mauris", "Curabitur", "Proin condimentum");
|
||||
ft_write_ln(table, "Summary", "", "Sed tempor est eget odio varius dignissim.");
|
||||
|
||||
/* Set cell span */
|
||||
ft_set_cell_span(table, 3, 0, 2);
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
╔════════╤═══════════╤════════════════════════════════════════════╗
|
||||
║ Sed │ Aenean │ Text ║
|
||||
╠════════╪═══════════╪════════════════════════════════════════════╣
|
||||
║ Duis │ Aliquam │ Lorem ipsum dolor ║
|
||||
╟────────┼───────────┼────────────────────────────────────────────╢
|
||||
║ Mauris │ Curabitur │ Proin condimentum ║
|
||||
╟────────┴───────────┼────────────────────────────────────────────╢
|
||||
║ Summary │ Sed tempor est eget odio varius dignissim. ║
|
||||
╚════════════════════╧════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
## Custom memory allocators
|
||||
**libfort** actively uses memory allocation functions (by default standard `malloc`, `free` ...). If your application uses custom memory allocators you can provide appropriate functions to **libfort**:
|
||||
```C
|
||||
void ft_set_memory_funcs(void *(*f_malloc)(size_t size), void (*f_free)(void *ptr));
|
||||
```
|
||||
44
docs/tutorial/C_API/Table-life-cycle.md
Normal file
44
docs/tutorial/C_API/Table-life-cycle.md
Normal file
@@ -0,0 +1,44 @@
|
||||
The common **libfort table** life cycle:
|
||||
- create a table (`ft_create_table`);
|
||||
- fill it with data (`ft_write_ln, fr_ptrintf_ln, ft_row_write, ...`);
|
||||
- modify basic table appearance (`ft_set_cell_prop, ft_set_border_style ...`)
|
||||
- convert table to string representation (`ft_to_string`) and print it;
|
||||
- destroy the table (`ft_destroy_table`).
|
||||
|
||||
Here is a simple example:
|
||||
|
||||
```C
|
||||
/* C API */
|
||||
#include <stdio.h>
|
||||
#include "fort.h"
|
||||
int main(void)
|
||||
{
|
||||
ft_table_t *table = ft_create_table();
|
||||
/* Set "header" type for the first row */
|
||||
ft_set_cell_prop(table, 0, FT_ANY_COLUMN, FT_CPROP_ROW_TYPE, FT_ROW_HEADER);
|
||||
ft_write_ln(table, "N", "Driver", "Time", "Avg Speed");
|
||||
|
||||
ft_write_ln(table, "1", "Ricciardo", "1:25.945", "222.128");
|
||||
ft_write_ln(table, "2", "Hamilton", "1:26.373", "221.027");
|
||||
ft_write_ln(table, "3", "Verstappen", "1:26.469", "220.782");
|
||||
|
||||
printf("%s\n", ft_to_string(table));
|
||||
ft_destroy_table(table);
|
||||
}
|
||||
```
|
||||
Output:
|
||||
```text
|
||||
+---+------------+----------+-----------+
|
||||
| N | Driver | Time | Avg Speed |
|
||||
+---+------------+----------+-----------+
|
||||
| 1 | Ricciardo | 1:25.945 | 47.362 |
|
||||
| 2 | Hamilton | 1:26.373 | 35.02 |
|
||||
| 3 | Verstappen | 1:26.469 | 29.78 |
|
||||
+---+------------+----------+-----------+
|
||||
```
|
||||
|
||||
To copy table and all its internal data use `ft_copy_table`:
|
||||
```C
|
||||
ft_table_t *ft_copy_table(ft_table_t *table);
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user