summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorJonas M. Gastal <jgastal@profusion.mobi>2012-12-20 20:42:45 +0000
committerJonas M. Gastal <jgastal@profusion.mobi>2012-12-20 20:42:45 +0000
commit55845c5a3ed0d867e204f5a311e5c7c3f370963b (patch)
tree756a4cf7d7f526e4758304780502691fad4667d4 /src
parentac598a94f8e4579f7b7cb45183494ec44b2a2d54 (diff)
efl: Adding much improved textblock style documentation.
SVN revision: 81485
Diffstat (limited to 'src')
-rw-r--r--src/lib/evas/Evas.h2
-rw-r--r--src/lib/evas/canvas/evas_object_textblock.c600
2 files changed, 600 insertions, 2 deletions
diff --git a/src/lib/evas/Evas.h b/src/lib/evas/Evas.h
index 2edbf55e5d..bf58ec5c2b 100644
--- a/src/lib/evas/Evas.h
+++ b/src/lib/evas/Evas.h
@@ -10504,6 +10504,8 @@ EAPI Evas_BiDi_Direction evas_object_text_direction_get(const Evas_Object *obj)
10504 * additional format directives using "tags" that can be set in the style see 10504 * additional format directives using "tags" that can be set in the style see
10505 * @ref evas_textblock_style_set . 10505 * @ref evas_textblock_style_set .
10506 * 10506 *
10507 * For more details see @ref evas_textblock_style_page
10508 *
10507 * Textblock supports the following formats: 10509 * Textblock supports the following formats:
10508 * @li font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold". 10510 * @li font - Font description in fontconfig like format, e.g: "Sans:style=Italic:lang=hi". or "Serif:style=Bold".
10509 * @li font_weight - Overrides the weight defined in "font". E.g: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack". 10511 * @li font_weight - Overrides the weight defined in "font". E.g: "font_weight=Bold" is the same as "font=:style=Bold". Supported weights: "normal", "thin", "ultralight", "light", "book", "medium", "semibold", "bold", "ultrabold", "black", and "extrablack".
diff --git a/src/lib/evas/canvas/evas_object_textblock.c b/src/lib/evas/canvas/evas_object_textblock.c
index 8ce1a6dfb8..ac0c1e9c2a 100644
--- a/src/lib/evas/canvas/evas_object_textblock.c
+++ b/src/lib/evas/canvas/evas_object_textblock.c
@@ -1,6 +1,6 @@
1/** 1/**
2 * @internal 2 * @internal
3 * @section Evas_Object_Textblock_Internal Internal Textblock Object Tutorial 3 * @subsection Evas_Object_Textblock_Internal Internal Textblock Object Tutorial
4 * 4 *
5 * This explains the internal design of the Evas Textblock Object, it's assumed 5 * This explains the internal design of the Evas Textblock Object, it's assumed
6 * that the reader of this section has already read @ref Evas_Object_Textblock_Tutorial "Textblock's usage docs.". 6 * that the reader of this section has already read @ref Evas_Object_Textblock_Tutorial "Textblock's usage docs.".
@@ -1100,6 +1100,12 @@ static const char *underline_dash_widthstr = NULL;
1100static const char *underline_dash_gapstr = NULL; 1100static const char *underline_dash_gapstr = NULL;
1101 1101
1102/** 1102/**
1103 * @page evas_textblock_style_page Evas Textblock Style Options
1104 *
1105 * @brief This page describes how to style text in an Evas Text Block.
1106 */
1107
1108/**
1103 * @internal 1109 * @internal
1104 * Init the format strings. 1110 * Init the format strings.
1105 */ 1111 */
@@ -1108,6 +1114,53 @@ _format_command_init(void)
1108{ 1114{
1109 if (format_refcount == 0) 1115 if (format_refcount == 0)
1110 { 1116 {
1117 /**
1118 * @page evas_textblock_style_page Evas Textblock Style Options
1119 *
1120 * @section evas_textblock_style_index Index
1121 *
1122 * The following styling commands are accepted:
1123 * @li @ref evas_textblock_style_font
1124 * @li @ref evas_textblock_style_font_fallback
1125 * @li @ref evas_textblock_style_font_size
1126 * @li @ref evas_textblock_style_font_source
1127 * @li @ref evas_textblock_style_font_weight
1128 * @li @ref evas_textblock_style_font_style
1129 * @li @ref evas_textblock_style_font_width
1130 * @li @ref evas_textblock_style_lang
1131 * @li @ref evas_textblock_style_color
1132 * @li @ref evas_textblock_style_underline_color
1133 * @li @ref evas_textblock_style_underline2_color
1134 * @li @ref evas_textblock_style_underline_dash_color
1135 * @li @ref evas_textblock_style_outline_color
1136 * @li @ref evas_textblock_style_shadow_color
1137 * @li @ref evas_textblock_style_glow_color
1138 * @li @ref evas_textblock_style_glow2_color
1139 * @li @ref evas_textblock_style_backing_color
1140 * @li @ref evas_textblock_style_strikethrough_color
1141 * @li @ref evas_textblock_style_align
1142 * @li @ref evas_textblock_style_valign
1143 * @li @ref evas_textblock_style_wrap
1144 * @li @ref evas_textblock_style_left_margin
1145 * @li @ref evas_textblock_style_right_margin
1146 * @li @ref evas_textblock_style_underline
1147 * @li @ref evas_textblock_style_strikethrough
1148 * @li @ref evas_textblock_style_backing
1149 * @li @ref evas_textblock_style_style
1150 * @li @ref evas_textblock_style_tabstops
1151 * @li @ref evas_textblock_style_linesize
1152 * @li @ref evas_textblock_style_linerelsize
1153 * @li @ref evas_textblock_style_linegap
1154 * @li @ref evas_textblock_style_linerelgap
1155 * @li @ref evas_textblock_style_item
1156 * @li @ref evas_textblock_style_linefill
1157 * @li @ref evas_textblock_style_ellipsis
1158 * @li @ref evas_textblock_style_password
1159 * @li @ref evas_textblock_style_underline_dash_width
1160 * @li @ref evas_textblock_style_underline_dash_gap
1161 *
1162 * @section evas_textblock_style_contents Contents
1163 */
1111 fontstr = eina_stringshare_add("font"); 1164 fontstr = eina_stringshare_add("font");
1112 font_fallbacksstr = eina_stringshare_add("font_fallbacks"); 1165 font_fallbacksstr = eina_stringshare_add("font_fallbacks");
1113 font_sizestr = eina_stringshare_add("font_size"); 1166 font_sizestr = eina_stringshare_add("font_size");
@@ -1261,14 +1314,45 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1261 1314
1262 if (cmd == fontstr) 1315 if (cmd == fontstr)
1263 { 1316 {
1317 /**
1318 * @page evas_textblock_style_page Evas Textblock Style Options
1319 *
1320 * @subsection evas_textblock_style_font Font
1321 *
1322 * This sets the name of the font to be used.
1323 * @code
1324 * font=<font name>
1325 * @endcode
1326 */
1264 evas_font_name_parse(fmt->font.fdesc, tmp_param); 1327 evas_font_name_parse(fmt->font.fdesc, tmp_param);
1265 } 1328 }
1266 else if (cmd == font_fallbacksstr) 1329 else if (cmd == font_fallbacksstr)
1267 { 1330 {
1331 /**
1332 * @page evas_textblock_style_page Evas Textblock Style Options
1333 *
1334 * @subsection evas_textblock_style_font_fallback Font fallback
1335 *
1336 * This sets the name of the fallback font to be used. This font will
1337 * be used if the primary font is not available.
1338 * @code
1339 * font_fallbacks=<font name>
1340 * @endcode
1341 */
1268 eina_stringshare_replace(&(fmt->font.fdesc->fallbacks), tmp_param); 1342 eina_stringshare_replace(&(fmt->font.fdesc->fallbacks), tmp_param);
1269 } 1343 }
1270 else if (cmd == font_sizestr) 1344 else if (cmd == font_sizestr)
1271 { 1345 {
1346 /**
1347 * @page evas_textblock_style_page Evas Textblock Style Options
1348 *
1349 * @subsection evas_textblock_style_font_size Font size
1350 *
1351 * This sets the the size of font in points to be used.
1352 * @code
1353 * font_size=<size>
1354 * @endcode
1355 */
1272 int v; 1356 int v;
1273 1357
1274 v = atoi(tmp_param); 1358 v = atoi(tmp_param);
@@ -1279,6 +1363,16 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1279 } 1363 }
1280 else if (cmd == font_sourcestr) 1364 else if (cmd == font_sourcestr)
1281 { 1365 {
1366 /**
1367 * @page evas_textblock_style_page Evas Textblock Style Options
1368 *
1369 * @subsection evas_textblock_style_font_source Font source
1370 *
1371 * Specify an object from which to search for the font.
1372 * @code
1373 * font_source=<source>
1374 * @endcode
1375 */
1282 if ((!fmt->font.source) || 1376 if ((!fmt->font.source) ||
1283 ((fmt->font.source) && (strcmp(fmt->font.source, tmp_param)))) 1377 ((fmt->font.source) && (strcmp(fmt->font.source, tmp_param))))
1284 { 1378 {
@@ -1288,65 +1382,295 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1288 } 1382 }
1289 else if (cmd == font_weightstr) 1383 else if (cmd == font_weightstr)
1290 { 1384 {
1385 /**
1386 * @page evas_textblock_style_page Evas Textblock Style Options
1387 *
1388 * @subsection evas_textblock_style_font_weight Font weight
1389 *
1390 * Sets the weight of the font. The value must be one of:
1391 * @li "normal"
1392 * @li "thin"
1393 * @li "ultralight"
1394 * @li "light"
1395 * @li "book"
1396 * @li "medium"
1397 * @li "semibold"
1398 * @li "bold"
1399 * @li "ultrabold"
1400 * @li "black"
1401 * @li "extrablack"
1402 * @code
1403 * font_weight=<weight>
1404 * @endcode
1405 */
1291 fmt->font.fdesc->weight = evas_font_style_find(tmp_param, 1406 fmt->font.fdesc->weight = evas_font_style_find(tmp_param,
1292 tmp_param + strlen(tmp_param), EVAS_FONT_STYLE_WEIGHT); 1407 tmp_param + strlen(tmp_param), EVAS_FONT_STYLE_WEIGHT);
1293 } 1408 }
1294 else if (cmd == font_stylestr) 1409 else if (cmd == font_stylestr)
1295 { 1410 {
1411 /**
1412 * @page evas_textblock_style_page Evas Textblock Style Options
1413 *
1414 * @subsection evas_textblock_style_font_style Font style
1415 *
1416 * Sets the style of the font. The value must be one of:
1417 * @li "normal"
1418 * @li "oblique"
1419 * @li "italic"
1420 * @code
1421 * font_style=<style>
1422 * @endcode
1423 */
1296 fmt->font.fdesc->slant = evas_font_style_find(tmp_param, 1424 fmt->font.fdesc->slant = evas_font_style_find(tmp_param,
1297 tmp_param + strlen(tmp_param), EVAS_FONT_STYLE_SLANT); 1425 tmp_param + strlen(tmp_param), EVAS_FONT_STYLE_SLANT);
1298 } 1426 }
1299 else if (cmd == font_widthstr) 1427 else if (cmd == font_widthstr)
1300 { 1428 {
1429 /**
1430 * @page evas_textblock_style_page Evas Textblock Style Options
1431 *
1432 * @subsection evas_textblock_style_font_width Font width
1433 *
1434 * Sets the width of the font. The value must be one of:
1435 * @li "normal"
1436 * @li "ultracondensed"
1437 * @li "extracondensed"
1438 * @li "condensed"
1439 * @li "semicondensed"
1440 * @li "semiexpanded"
1441 * @li "expanded"
1442 * @li "extraexpanded"
1443 * @li "ultraexpanded"
1444 * @code
1445 * font_width=<width>
1446 * @endcode
1447 */
1301 fmt->font.fdesc->width = evas_font_style_find(tmp_param, 1448 fmt->font.fdesc->width = evas_font_style_find(tmp_param,
1302 tmp_param + strlen(tmp_param), EVAS_FONT_STYLE_WIDTH); 1449 tmp_param + strlen(tmp_param), EVAS_FONT_STYLE_WIDTH);
1303 } 1450 }
1304 else if (cmd == langstr) 1451 else if (cmd == langstr)
1305 { 1452 {
1453 /**
1454 * @page evas_textblock_style_page Evas Textblock Style Options
1455 *
1456 * @subsection evas_textblock_style_lang Language
1457 *
1458 * Sets the language of the text for FontConfig.
1459 * @code
1460 * lang=<language>
1461 * @endcode
1462 */
1306 eina_stringshare_replace(&(fmt->font.fdesc->lang), tmp_param); 1463 eina_stringshare_replace(&(fmt->font.fdesc->lang), tmp_param);
1307 } 1464 }
1308 else if (cmd == colorstr) 1465 else if (cmd == colorstr)
1466 /**
1467 * @page evas_textblock_style_page Evas Textblock Style Options
1468 *
1469 * @subsection evas_textblock_style_color Color
1470 *
1471 * Sets the color of the text. The following formats are accepted:
1472 * @li "#RRGGBB"
1473 * @li "#RRGGBBAA"
1474 * @li "#RGB"
1475 * @li "#RGBA"
1476 * @code
1477 * color=<color>
1478 * @endcode
1479 */
1309 _format_color_parse(tmp_param, 1480 _format_color_parse(tmp_param,
1310 &(fmt->color.normal.r), &(fmt->color.normal.g), 1481 &(fmt->color.normal.r), &(fmt->color.normal.g),
1311 &(fmt->color.normal.b), &(fmt->color.normal.a)); 1482 &(fmt->color.normal.b), &(fmt->color.normal.a));
1312 else if (cmd == underline_colorstr) 1483 else if (cmd == underline_colorstr)
1484 /**
1485 * @page evas_textblock_style_page Evas Textblock Style Options
1486 *
1487 * @subsection evas_textblock_style_underline_color Underline Color
1488 *
1489 * Sets the color of the underline. The following formats are accepted:
1490 * @li "#RRGGBB"
1491 * @li "#RRGGBBAA"
1492 * @li "#RGB"
1493 * @li "#RGBA"
1494 * @code
1495 * underline_color=<color>
1496 * @endcode
1497 */
1313 _format_color_parse(tmp_param, 1498 _format_color_parse(tmp_param,
1314 &(fmt->color.underline.r), &(fmt->color.underline.g), 1499 &(fmt->color.underline.r), &(fmt->color.underline.g),
1315 &(fmt->color.underline.b), &(fmt->color.underline.a)); 1500 &(fmt->color.underline.b), &(fmt->color.underline.a));
1316 else if (cmd == underline2_colorstr) 1501 else if (cmd == underline2_colorstr)
1502 /**
1503 * @page evas_textblock_style_page Evas Textblock Style Options
1504 *
1505 * @subsection evas_textblock_style_underline2_color Second Underline Color
1506 *
1507 * Sets the color of the second line of underline(when using underline
1508 * mode "double"). The following formats are accepted:
1509 * @li "#RRGGBB"
1510 * @li "#RRGGBBAA"
1511 * @li "#RGB"
1512 * @li "#RGBA"
1513 * @code
1514 * underline2_color=<color>
1515 * @endcode
1516 */
1317 _format_color_parse(tmp_param, 1517 _format_color_parse(tmp_param,
1318 &(fmt->color.underline2.r), &(fmt->color.underline2.g), 1518 &(fmt->color.underline2.r), &(fmt->color.underline2.g),
1319 &(fmt->color.underline2.b), &(fmt->color.underline2.a)); 1519 &(fmt->color.underline2.b), &(fmt->color.underline2.a));
1320 else if (cmd == underline_dash_colorstr) 1520 else if (cmd == underline_dash_colorstr)
1521 /**
1522 * @page evas_textblock_style_page Evas Textblock Style Options
1523 *
1524 * @subsection evas_textblock_style_underline_dash_color Underline Dash Color
1525 *
1526 * Sets the color of dashed underline. The following formats are accepted:
1527 * @li "#RRGGBB"
1528 * @li "#RRGGBBAA"
1529 * @li "#RGB"
1530 * @li "#RGBA"
1531 * @code
1532 * underline_dash_color=<color>
1533 * @endcode
1534 */
1321 _format_color_parse(tmp_param, 1535 _format_color_parse(tmp_param,
1322 &(fmt->color.underline_dash.r), &(fmt->color.underline_dash.g), 1536 &(fmt->color.underline_dash.r), &(fmt->color.underline_dash.g),
1323 &(fmt->color.underline_dash.b), &(fmt->color.underline_dash.a)); 1537 &(fmt->color.underline_dash.b), &(fmt->color.underline_dash.a));
1324 else if (cmd == outline_colorstr) 1538 else if (cmd == outline_colorstr)
1539 /**
1540 * @page evas_textblock_style_page Evas Textblock Style Options
1541 *
1542 * @subsection evas_textblock_style_outline_color Outline Color
1543 *
1544 * Sets the color of the outline of the text. The following formats are
1545 * accepted:
1546 * @li "#RRGGBB"
1547 * @li "#RRGGBBAA"
1548 * @li "#RGB"
1549 * @li "#RGBA"
1550 * @code
1551 * outline_color=<color>
1552 * @endcode
1553 */
1325 _format_color_parse(tmp_param, 1554 _format_color_parse(tmp_param,
1326 &(fmt->color.outline.r), &(fmt->color.outline.g), 1555 &(fmt->color.outline.r), &(fmt->color.outline.g),
1327 &(fmt->color.outline.b), &(fmt->color.outline.a)); 1556 &(fmt->color.outline.b), &(fmt->color.outline.a));
1328 else if (cmd == shadow_colorstr) 1557 else if (cmd == shadow_colorstr)
1558 /**
1559 * @page evas_textblock_style_page Evas Textblock Style Options
1560 *
1561 * @subsection evas_textblock_style_shadow_color Shadow Color
1562 *
1563 * Sets the color of the shadow of the text. The following formats are
1564 * accepted:
1565 * @li "#RRGGBB"
1566 * @li "#RRGGBBAA"
1567 * @li "#RGB"
1568 * @li "#RGBA"
1569 * @code
1570 * shadow_color=<color>
1571 * @endcode
1572 */
1329 _format_color_parse(tmp_param, 1573 _format_color_parse(tmp_param,
1330 &(fmt->color.shadow.r), &(fmt->color.shadow.g), 1574 &(fmt->color.shadow.r), &(fmt->color.shadow.g),
1331 &(fmt->color.shadow.b), &(fmt->color.shadow.a)); 1575 &(fmt->color.shadow.b), &(fmt->color.shadow.a));
1332 else if (cmd == glow_colorstr) 1576 else if (cmd == glow_colorstr)
1577 /**
1578 * @page evas_textblock_style_page Evas Textblock Style Options
1579 *
1580 * @subsection evas_textblock_style_glow_color First Glow Color
1581 *
1582 * Sets the first color of the glow of text. The following formats are
1583 * accepted:
1584 * @li "#RRGGBB"
1585 * @li "#RRGGBBAA"
1586 * @li "#RGB"
1587 * @li "#RGBA"
1588 * @code
1589 * glow_color=<color>
1590 * @endcode
1591 */
1333 _format_color_parse(tmp_param, 1592 _format_color_parse(tmp_param,
1334 &(fmt->color.glow.r), &(fmt->color.glow.g), 1593 &(fmt->color.glow.r), &(fmt->color.glow.g),
1335 &(fmt->color.glow.b), &(fmt->color.glow.a)); 1594 &(fmt->color.glow.b), &(fmt->color.glow.a));
1336 else if (cmd == glow2_colorstr) 1595 else if (cmd == glow2_colorstr)
1596 /**
1597 * @page evas_textblock_style_page Evas Textblock Style Options
1598 *
1599 * @subsection evas_textblock_style_glow2_color Second Glow Color
1600 *
1601 * Sets the second color of the glow of text. The following formats are
1602 * accepted:
1603 * @li "#RRGGBB"
1604 * @li "#RRGGBBAA"
1605 * @li "#RGB"
1606 * @li "#RGBA"
1607 * @code
1608 * glow2_color=<color>
1609 * @endcode
1610 */
1337 _format_color_parse(tmp_param, 1611 _format_color_parse(tmp_param,
1338 &(fmt->color.glow2.r), &(fmt->color.glow2.g), 1612 &(fmt->color.glow2.r), &(fmt->color.glow2.g),
1339 &(fmt->color.glow2.b), &(fmt->color.glow2.a)); 1613 &(fmt->color.glow2.b), &(fmt->color.glow2.a));
1340 else if (cmd == backing_colorstr) 1614 else if (cmd == backing_colorstr)
1341 _format_color_parse(tmp_param, 1615 /**
1616 * @page evas_textblock_style_page Evas Textblock Style Options
1617 *
1618 * @subsection evas_textblock_style_backing_color Backing Color
1619 *
1620 * Sets a background color for text. The following formats are
1621 * accepted:
1622 * @li "#RRGGBB"
1623 * @li "#RRGGBBAA"
1624 * @li "#RGB"
1625 * @li "#RGBA"
1626 * @code
1627 * backing_color=<color>
1628 * @endcode
1629 */
1630 _format_color_parse(tmp_param,11
1342 &(fmt->color.backing.r), &(fmt->color.backing.g), 1631 &(fmt->color.backing.r), &(fmt->color.backing.g),
1343 &(fmt->color.backing.b), &(fmt->color.backing.a)); 1632 &(fmt->color.backing.b), &(fmt->color.backing.a));
1344 else if (cmd == strikethrough_colorstr) 1633 else if (cmd == strikethrough_colorstr)
1634 /**
1635 * @page evas_textblock_style_page Evas Textblock Style Options
1636 *
1637 * @subsection evas_textblock_style_strikethrough_color Strikethrough Color
1638 *
1639 * Sets the color of text that is striked through. The following formats
1640 * are accepted:
1641 * @li "#RRGGBB"
1642 * @li "#RRGGBBAA"
1643 * @li "#RGB"
1644 * @li "#RGBA"
1645 * @code
1646 * strikethrough_color=<color>
1647 * @endcode
1648 */
1345 _format_color_parse(tmp_param, 1649 _format_color_parse(tmp_param,
1346 &(fmt->color.strikethrough.r), &(fmt->color.strikethrough.g), 1650 &(fmt->color.strikethrough.r), &(fmt->color.strikethrough.g),
1347 &(fmt->color.strikethrough.b), &(fmt->color.strikethrough.a)); 1651 &(fmt->color.strikethrough.b), &(fmt->color.strikethrough.a));
1348 else if (cmd == alignstr) 1652 else if (cmd == alignstr)
1349 { 1653 {
1654 /**
1655 * @page evas_textblock_style_page Evas Textblock Style Options
1656 *
1657 * @subsection evas_textblock_style_align Horizontal Align
1658 *
1659 * Sets the horizontal alignment of the text. The value can either be
1660 * a number, a percentage or one of several presets:
1661 * @li "auto" - Respects LTR/RTL settings
1662 * @li "center" - Centers the text in the line
1663 * @li "middle" - Alias for "center"
1664 * @li "left" - Puts the text at the left of the line
1665 * @li "right" - Puts the text at the right of the line
1666 * @li <number> - A number between 0.0 and 1.0 where 0.0 represents
1667 * "left" and 1.0 represents "right"
1668 * @li <number>% - A percentage between 0% and 100% where 0%
1669 * represents "left" and 100% represents "right"
1670 * @code
1671 * align=<value or preset>
1672 * @endcode
1673 */
1350 if (!strcmp(tmp_param, "auto")) 1674 if (!strcmp(tmp_param, "auto"))
1351 { 1675 {
1352 fmt->halign_auto = EINA_TRUE; 1676 fmt->halign_auto = EINA_TRUE;
@@ -1377,6 +1701,30 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1377 } 1701 }
1378 else if (cmd == valignstr) 1702 else if (cmd == valignstr)
1379 { 1703 {
1704 /**
1705 * @page evas_textblock_style_page Evas Textblock Style Options
1706 *
1707 * @subsection evas_textblock_style_valign Vertical Align
1708 *
1709 * Sets the vertical alignment of the text. The value can either be
1710 * a number or one of the following presets:
1711 * @li "top" - Puts text at the top of the line
1712 * @li "center" - Centers the text in the line
1713 * @li "middle" - Alias for "center"
1714 * @li "bottom" - Puts the text at the bottom of the line
1715 * @li "baseline" - Baseline
1716 * @li "base" - Alias for "baseline"
1717 * @li <number> - A number between 0.0 and 1.0 where 0.0 represents
1718 * "top" and 1.0 represents "bottom"
1719 * @li <number>% - A percentage between 0% and 100% where 0%
1720 * represents "top" and 100% represents "bottom"
1721 * @code
1722 * valign=<value or preset>
1723 * @endcode
1724 *
1725 * See explanation of baseline at:
1726 * https://en.wikipedia.org/wiki/Baseline_%28typography%29
1727 */
1380 if (!strcmp(tmp_param, "top")) fmt->valign = 0.0; 1728 if (!strcmp(tmp_param, "top")) fmt->valign = 0.0;
1381 else if (!strcmp(tmp_param, "middle")) fmt->valign = 0.5; 1729 else if (!strcmp(tmp_param, "middle")) fmt->valign = 0.5;
1382 else if (!strcmp(tmp_param, "center")) fmt->valign = 0.5; 1730 else if (!strcmp(tmp_param, "center")) fmt->valign = 0.5;
@@ -1401,6 +1749,21 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1401 } 1749 }
1402 else if (cmd == wrapstr) 1750 else if (cmd == wrapstr)
1403 { 1751 {
1752 /**
1753 * @page evas_textblock_style_page Evas Textblock Style Options
1754 *
1755 * @subsection evas_textblock_style_wrap Wrap
1756 *
1757 * Sets the wrap policy of the text. The value must be one of the
1758 * following:
1759 * @li "word" - Only wraps lines at word boundaries
1760 * @li "char" - Wraps at any character
1761 * @li "mixed" - Wrap at words if possible, if not at any character
1762 * @li "" - Don't wrap
1763 * @code
1764 * wrap=<value or preset>
1765 * @endcode
1766 */
1404 if (!strcmp(tmp_param, "word")) 1767 if (!strcmp(tmp_param, "word"))
1405 { 1768 {
1406 fmt->wrap_word = 1; 1769 fmt->wrap_word = 1;
@@ -1423,6 +1786,21 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1423 } 1786 }
1424 else if (cmd == left_marginstr) 1787 else if (cmd == left_marginstr)
1425 { 1788 {
1789 /**
1790 * @page evas_textblock_style_page Evas Textblock Style Options
1791 *
1792 * @subsection evas_textblock_style_left_margin Left margin
1793 *
1794 * Sets the left margin of the text. The value can be a number, an
1795 * increment, decrement or "reset":
1796 * @li +<number> - Increments existing left margin by <number>
1797 * @li -<number> - Decrements existing left margin by <number>
1798 * @li <number> - Sets left margin to <number>
1799 * @li "reset" - Sets left margin to 0
1800 * @code
1801 * left_margin=<value or reset>
1802 * @endcode
1803 */
1426 if (!strcmp(tmp_param, "reset")) 1804 if (!strcmp(tmp_param, "reset"))
1427 fmt->margin.l = 0; 1805 fmt->margin.l = 0;
1428 else 1806 else
@@ -1438,6 +1816,21 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1438 } 1816 }
1439 else if (cmd == right_marginstr) 1817 else if (cmd == right_marginstr)
1440 { 1818 {
1819 /**
1820 * @page evas_textblock_style_page Evas Textblock Style Options
1821 *
1822 * @subsection evas_textblock_style_right_margin Right margin
1823 *
1824 * Sets the right margin of the text. The value can be a number, an
1825 * increment, decrement or "reset":
1826 * @li +<number> - Increments existing right margin by <number>
1827 * @li -<number> - Decrements existing right margin by <number>
1828 * @li <number> - Sets left margin to <number>
1829 * @li "reset" - Sets left margin to 0
1830 * @code
1831 * right_margin=<value or reset>
1832 * @endcode
1833 */
1441 if (!strcmp(tmp_param, "reset")) 1834 if (!strcmp(tmp_param, "reset"))
1442 fmt->margin.r = 0; 1835 fmt->margin.r = 0;
1443 else 1836 else
@@ -1453,6 +1846,22 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1453 } 1846 }
1454 else if (cmd == underlinestr) 1847 else if (cmd == underlinestr)
1455 { 1848 {
1849 /**
1850 * @page evas_textblock_style_page Evas Textblock Style Options
1851 *
1852 * @subsection evas_textblock_style_underline Underline
1853 *
1854 * Sets if and how a text will be underlined. The value must be one of
1855 * the following:
1856 * @li "off" - No underlining
1857 * @li "single" - A single line under the text
1858 * @li "on" - Alias for "single"
1859 * @li "double" - Two lines under the text
1860 * @li "dashed" - A dashed line under the text
1861 * @code
1862 * underline=off/single/on/double/dashed
1863 * @endcode
1864 */
1456 if (!strcmp(tmp_param, "off")) 1865 if (!strcmp(tmp_param, "off"))
1457 { 1866 {
1458 fmt->underline = 0; 1867 fmt->underline = 0;
@@ -1474,6 +1883,19 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1474 } 1883 }
1475 else if (cmd == strikethroughstr) 1884 else if (cmd == strikethroughstr)
1476 { 1885 {
1886 /**
1887 * @page evas_textblock_style_page Evas Textblock Style Options
1888 *
1889 * @subsection evas_textblock_style_strikethrough Strikethrough
1890 *
1891 * Sets if the text will be striked through. The value must be one of
1892 * the following:
1893 * @li "off" - No strikethrough
1894 * @li "on" - Strikethrough
1895 * @code
1896 * strikethrough=on/off
1897 * @endcode
1898 */
1477 if (!strcmp(tmp_param, "off")) 1899 if (!strcmp(tmp_param, "off"))
1478 fmt->strikethrough = 0; 1900 fmt->strikethrough = 0;
1479 else if (!strcmp(tmp_param, "on")) 1901 else if (!strcmp(tmp_param, "on"))
@@ -1481,6 +1903,19 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1481 } 1903 }
1482 else if (cmd == backingstr) 1904 else if (cmd == backingstr)
1483 { 1905 {
1906 /**
1907 * @page evas_textblock_style_page Evas Textblock Style Options
1908 *
1909 * @subsection evas_textblock_style_backing Backing
1910 *
1911 * Sets if the text will have backing. The value must be one of
1912 * the following:
1913 * @li "off" - No backing
1914 * @li "on" - Backing
1915 * @code
1916 * backing=on/off
1917 * @endcode
1918 */
1484 if (!strcmp(tmp_param, "off")) 1919 if (!strcmp(tmp_param, "off"))
1485 fmt->backing = 0; 1920 fmt->backing = 0;
1486 else if (!strcmp(tmp_param, "on")) 1921 else if (!strcmp(tmp_param, "on"))
@@ -1488,6 +1923,41 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1488 } 1923 }
1489 else if (cmd == stylestr) 1924 else if (cmd == stylestr)
1490 { 1925 {
1926 /**
1927 * @page evas_textblock_style_page Evas Textblock Style Options
1928 *
1929 * @subsection evas_textblock_style_style Style
1930 *
1931 * Sets the style of the text. The value must be a string composed of
1932 * two comma separated parts. The first part of the value sets the
1933 * appearance of the text, the second the position.
1934 *
1935 * The first part may be any of the following values:
1936 * @li "plain"
1937 * @li "off" - Alias for "plain"
1938 * @li "none" - Alias for "plain"
1939 * @li "shadow"
1940 * @li "outline"
1941 * @li "soft_outline"
1942 * @li "outline_shadow"
1943 * @li "outline_soft_shadow"
1944 * @li "glow"
1945 * @li "far_shadow"
1946 * @li "soft_shadow"
1947 * @li "far_soft_shadow"
1948 * The second part may be any of the following values:
1949 * @li "bottom_right"
1950 * @li "bottom"
1951 * @li "bottom_left"
1952 * @li "left"
1953 * @li "top_left"
1954 * @li "top"
1955 * @li "top_right"
1956 * @li "right"
1957 * @code
1958 * style=<appearance>,<position>
1959 * @endcode
1960 */
1491 char *p1, *p2, *p, *pp; 1961 char *p1, *p2, *p, *pp;
1492 1962
1493 p1 = alloca(len + 1); 1963 p1 = alloca(len + 1);
@@ -1545,16 +2015,50 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1545 } 2015 }
1546 else if (cmd == tabstopsstr) 2016 else if (cmd == tabstopsstr)
1547 { 2017 {
2018 /**
2019 * @page evas_textblock_style_page Evas Textblock Style Options
2020 *
2021 * @subsection evas_textblock_style_tabstops Tabstops
2022 *
2023 * Sets the size of the tab character. The value must be a number
2024 * greater than one.
2025 * @code
2026 * tabstops=<number>
2027 * @endcode
2028 */
1548 fmt->tabstops = atoi(tmp_param); 2029 fmt->tabstops = atoi(tmp_param);
1549 if (fmt->tabstops < 1) fmt->tabstops = 1; 2030 if (fmt->tabstops < 1) fmt->tabstops = 1;
1550 } 2031 }
1551 else if (cmd == linesizestr) 2032 else if (cmd == linesizestr)
1552 { 2033 {
2034 /**
2035 * @page evas_textblock_style_page Evas Textblock Style Options
2036 *
2037 * @subsection evas_textblock_style_linesize Line size
2038 *
2039 * Sets the size of line of text. The value should be a number.
2040 * @warning Setting this value sets linerelsize to 0%!
2041 * @code
2042 * linesize=<number>
2043 * @endcode
2044 */
1553 fmt->linesize = atoi(tmp_param); 2045 fmt->linesize = atoi(tmp_param);
1554 fmt->linerelsize = 0.0; 2046 fmt->linerelsize = 0.0;
1555 } 2047 }
1556 else if (cmd == linerelsizestr) 2048 else if (cmd == linerelsizestr)
1557 { 2049 {
2050 /**
2051 * @page evas_textblock_style_page Evas Textblock Style Options
2052 *
2053 * @subsection evas_textblock_style_linerelsize Relative line size
2054 *
2055 * Sets the relative size of line of text. The value must be a
2056 * percentage.
2057 * @warning Setting this value sets linesize to 0!
2058 * @code
2059 * linerelsize=<number>%
2060 * @endcode
2061 */
1558 char *endptr = NULL; 2062 char *endptr = NULL;
1559 double val = strtod(tmp_param, &endptr); 2063 double val = strtod(tmp_param, &endptr);
1560 if (endptr) 2064 if (endptr)
@@ -1571,11 +2075,35 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1571 } 2075 }
1572 else if (cmd == linegapstr) 2076 else if (cmd == linegapstr)
1573 { 2077 {
2078 /**
2079 * @page evas_textblock_style_page Evas Textblock Style Options
2080 *
2081 * @subsection evas_textblock_style_linegap Line gap
2082 *
2083 * Sets the size of the line gap in text. The value should be a
2084 * number.
2085 * @warning Setting this value sets linerelgap to 0%!
2086 * @code
2087 * linegap=<number>
2088 * @endcode
2089 */
1574 fmt->linegap = atoi(tmp_param); 2090 fmt->linegap = atoi(tmp_param);
1575 fmt->linerelgap = 0.0; 2091 fmt->linerelgap = 0.0;
1576 } 2092 }
1577 else if (cmd == linerelgapstr) 2093 else if (cmd == linerelgapstr)
1578 { 2094 {
2095 /**
2096 * @page evas_textblock_style_page Evas Textblock Style Options
2097 *
2098 * @subsection evas_textblock_style_linerelgap Relative line gap
2099 *
2100 * Sets the relative size of the line gap in text. The value must be
2101 * a percentage.
2102 * @warning Setting this value sets linegap to 0!
2103 * @code
2104 * linerelgap=<number>%
2105 * @endcode
2106 */
1579 char *endptr = NULL; 2107 char *endptr = NULL;
1580 double val = strtod(tmp_param, &endptr); 2108 double val = strtod(tmp_param, &endptr);
1581 if (endptr) 2109 if (endptr)
@@ -1592,11 +2120,32 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1592 } 2120 }
1593 else if (cmd == itemstr) 2121 else if (cmd == itemstr)
1594 { 2122 {
2123 /**
2124 * @page evas_textblock_style_page Evas Textblock Style Options
2125 *
2126 * @subsection evas_textblock_style_item Item
2127 *
2128 * Not implemented! Does nothing!
2129 * @code
2130 * item=<anything>
2131 * @endcode
2132 */
1595 // itemstr == replacement object items in textblock - inline imges 2133 // itemstr == replacement object items in textblock - inline imges
1596 // for example 2134 // for example
1597 } 2135 }
1598 else if (cmd == linefillstr) 2136 else if (cmd == linefillstr)
1599 { 2137 {
2138 /**
2139 * @page evas_textblock_style_page Evas Textblock Style Options
2140 *
2141 * @subsection evas_textblock_style_linefill Line fill
2142 *
2143 * Sets the size of the line fill in text. The value must be a
2144 * percentage.
2145 * @code
2146 * linefill=<number>%
2147 * @endcode
2148 */
1600 char *endptr = NULL; 2149 char *endptr = NULL;
1601 double val = strtod(tmp_param, &endptr); 2150 double val = strtod(tmp_param, &endptr);
1602 if (endptr) 2151 if (endptr)
@@ -1612,6 +2161,19 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1612 } 2161 }
1613 else if (cmd == ellipsisstr) 2162 else if (cmd == ellipsisstr)
1614 { 2163 {
2164 /**
2165 * @page evas_textblock_style_page Evas Textblock Style Options
2166 *
2167 * @subsection evas_textblock_style_ellipsis Ellipsis
2168 *
2169 * Sets ellipsis mode. The value should be a number. Any value smaller
2170 * than 0.0 or greater than 1.0 disables ellipsis.
2171 * A value of 0 means ellipsizing the leftmost portion of the text
2172 * first, 1 on the other hand the rightmost portion.
2173 * @code
2174 * ellipsis=<number>
2175 * @endcode
2176 */
1615 char *endptr = NULL; 2177 char *endptr = NULL;
1616 fmt->ellipsis = strtod(tmp_param, &endptr); 2178 fmt->ellipsis = strtod(tmp_param, &endptr);
1617 if ((fmt->ellipsis < 0.0) || (fmt->ellipsis > 1.0)) 2179 if ((fmt->ellipsis < 0.0) || (fmt->ellipsis > 1.0))
@@ -1624,6 +2186,20 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1624 } 2186 }
1625 else if (cmd == passwordstr) 2187 else if (cmd == passwordstr)
1626 { 2188 {
2189 /**
2190 * @page evas_textblock_style_page Evas Textblock Style Options
2191 *
2192 * @subsection evas_textblock_style_password Password
2193 *
2194 * Sets if the text is being used for passwords. Enabling this causes
2195 * all characters to be substituted for '*'.
2196 * Value must be one of the following:
2197 * @li "on" - Enable
2198 * @li "off" - Disable
2199 * @code
2200 * password=<number>
2201 * @endcode
2202 */
1627 if (!strcmp(tmp_param, "off")) 2203 if (!strcmp(tmp_param, "off"))
1628 fmt->password = 0; 2204 fmt->password = 0;
1629 else if (!strcmp(tmp_param, "on")) 2205 else if (!strcmp(tmp_param, "on"))
@@ -1631,11 +2207,31 @@ _format_command(Evas_Object *eo_obj, Evas_Object_Textblock_Format *fmt, const ch
1631 } 2207 }
1632 else if (cmd == underline_dash_widthstr) 2208 else if (cmd == underline_dash_widthstr)
1633 { 2209 {
2210 /**
2211 * @page evas_textblock_style_page Evas Textblock Style Options
2212 *
2213 * @subsection evas_textblock_style_underline_dash_width Underline dash width
2214 *
2215 * Sets the width of the underline dash. The value should be a number.
2216 * @code
2217 * underline_dash_width=<number>
2218 * @endcode
2219 */
1634 fmt->underline_dash_width = atoi(tmp_param); 2220 fmt->underline_dash_width = atoi(tmp_param);
1635 if (fmt->underline_dash_width <= 0) fmt->underline_dash_width = 1; 2221 if (fmt->underline_dash_width <= 0) fmt->underline_dash_width = 1;
1636 } 2222 }
1637 else if (cmd == underline_dash_gapstr) 2223 else if (cmd == underline_dash_gapstr)
1638 { 2224 {
2225 /**
2226 * @page evas_textblock_style_page Evas Textblock Style Options
2227 *
2228 * @subsection evas_textblock_style_underline_dash_gap Underline dash gap
2229 *
2230 * Sets the gap of the underline dash. The value should be a number.
2231 * @code
2232 * underline_dash_gap=<number>
2233 * @endcode
2234 */
1639 fmt->underline_dash_gap = atoi(tmp_param); 2235 fmt->underline_dash_gap = atoi(tmp_param);
1640 if (fmt->underline_dash_gap <= 0) fmt->underline_dash_gap = 1; 2236 if (fmt->underline_dash_gap <= 0) fmt->underline_dash_gap = 1;
1641 } 2237 }