1 /* 2 * libxlsxwriter 3 * 4 * Copyright 2014-2021, John McNamara, jmcnamara@cpan.org. See LICENSE.txt. 5 */ 6 7 /** 8 * @page format_page The Format object 9 * 10 * The Format object represents an the formatting properties that can be 11 * applied to a cell including: fonts, colors, patterns, 12 * borders, alignment and number formatting. 13 * 14 * See @ref format.h for full details of the functionality. 15 * 16 * @file format.h 17 * 18 * @brief Functions and properties for adding formatting to cells in Excel. 19 * 20 * This section describes the functions and properties that are available for 21 * formatting cells in Excel. 22 * 23 * The properties of a cell that can be formatted include: fonts, colors, 24 * patterns, borders, alignment and number formatting. 25 * 26 * @image html formats_intro.png 27 * 28 * Formats in `libxlsxwriter` are accessed via the lxw_format 29 * struct. Throughout this document these will be referred to simply as 30 * *Formats*. 31 * 32 * Formats are created by calling the workbook_add_format() method as 33 * follows: 34 * 35 * @code 36 * lxw_format *format = workbook_add_format(workbook); 37 * @endcode 38 * 39 * The members of the lxw_format struct aren't modified directly. Instead the 40 * format properties are set by calling the functions shown in this section. 41 * For example: 42 * 43 * @code 44 * // Create the Format. 45 * lxw_format *format = workbook_add_format(workbook); 46 * 47 * // Set some of the format properties. 48 * format_set_bold(format); 49 * format_set_font_color(format, LXW_COLOR_RED); 50 * 51 * // Use the format to change the text format in a cell. 52 * worksheet_write_string(worksheet, 0, 0, "Hello", format); 53 * 54 * @endcode 55 * 56 * The full range of formatting options that can be applied using 57 * `libxlsxwriter` are shown below. 58 * 59 */ 60 #ifndef __LXW_FORMAT_H__ 61 #define __LXW_FORMAT_H__ 62 63 #include <stdint.h> 64 #include <string.h> 65 #include "hash_table.h" 66 67 #include "common.h" 68 69 /** 70 * @brief The type for RGB colors in libxlsxwriter. 71 * 72 * The type for RGB colors in libxlsxwriter. The valid range is `0x000000` 73 * (black) to `0xFFFFFF` (white). See @ref working_with_colors. 74 */ 75 typedef uint32_t lxw_color_t; 76 77 #define LXW_FORMAT_FIELD_LEN 128 78 #define LXW_DEFAULT_FONT_NAME "Calibri" 79 #define LXW_DEFAULT_FONT_FAMILY 2 80 #define LXW_DEFAULT_FONT_THEME 1 81 #define LXW_PROPERTY_UNSET -1 82 #define LXW_COLOR_UNSET 0x000000 83 #define LXW_COLOR_MASK 0xFFFFFF 84 #define LXW_MIN_FONT_SIZE 1.0 85 #define LXW_MAX_FONT_SIZE 409.0 86 87 #define LXW_FORMAT_FIELD_COPY(dst, src) \ 88 do{ \ 89 strncpy(dst, src, LXW_FORMAT_FIELD_LEN -1); \ 90 dst[LXW_FORMAT_FIELD_LEN - 1] = '\0'; \ 91 } while (0) 92 93 /** Format underline values for format_set_underline(). */ 94 enum lxw_format_underlines { 95 LXW_UNDERLINE_NONE = 0, 96 97 /** Single underline */ 98 LXW_UNDERLINE_SINGLE, 99 100 /** Double underline */ 101 LXW_UNDERLINE_DOUBLE, 102 103 /** Single accounting underline */ 104 LXW_UNDERLINE_SINGLE_ACCOUNTING, 105 106 /** Double accounting underline */ 107 LXW_UNDERLINE_DOUBLE_ACCOUNTING 108 }; 109 110 /** Superscript and subscript values for format_set_font_script(). */ 111 enum lxw_format_scripts { 112 113 /** Superscript font */ 114 LXW_FONT_SUPERSCRIPT = 1, 115 116 /** Subscript font */ 117 LXW_FONT_SUBSCRIPT 118 }; 119 120 /** Alignment values for format_set_align(). */ 121 enum lxw_format_alignments { 122 /** No alignment. Cell will use Excel's default for the data type */ 123 LXW_ALIGN_NONE = 0, 124 125 /** Left horizontal alignment */ 126 LXW_ALIGN_LEFT, 127 128 /** Center horizontal alignment */ 129 LXW_ALIGN_CENTER, 130 131 /** Right horizontal alignment */ 132 LXW_ALIGN_RIGHT, 133 134 /** Cell fill horizontal alignment */ 135 LXW_ALIGN_FILL, 136 137 /** Justify horizontal alignment */ 138 LXW_ALIGN_JUSTIFY, 139 140 /** Center Across horizontal alignment */ 141 LXW_ALIGN_CENTER_ACROSS, 142 143 /** Left horizontal alignment */ 144 LXW_ALIGN_DISTRIBUTED, 145 146 /** Top vertical alignment */ 147 LXW_ALIGN_VERTICAL_TOP, 148 149 /** Bottom vertical alignment */ 150 LXW_ALIGN_VERTICAL_BOTTOM, 151 152 /** Center vertical alignment */ 153 LXW_ALIGN_VERTICAL_CENTER, 154 155 /** Justify vertical alignment */ 156 LXW_ALIGN_VERTICAL_JUSTIFY, 157 158 /** Distributed vertical alignment */ 159 LXW_ALIGN_VERTICAL_DISTRIBUTED 160 }; 161 162 /** 163 * Diagonal border types. 164 * 165 */ 166 enum lxw_format_diagonal_types { 167 168 /** Cell diagonal border from bottom left to top right. */ 169 LXW_DIAGONAL_BORDER_UP = 1, 170 171 /** Cell diagonal border from top left to bottom right. */ 172 LXW_DIAGONAL_BORDER_DOWN, 173 174 /** Cell diagonal border in both directions. */ 175 LXW_DIAGONAL_BORDER_UP_DOWN 176 }; 177 178 /** Predefined values for common colors. */ 179 enum lxw_defined_colors { 180 /** Black */ 181 LXW_COLOR_BLACK = 0x1000000, 182 183 /** Blue */ 184 LXW_COLOR_BLUE = 0x0000FF, 185 186 /** Brown */ 187 LXW_COLOR_BROWN = 0x800000, 188 189 /** Cyan */ 190 LXW_COLOR_CYAN = 0x00FFFF, 191 192 /** Gray */ 193 LXW_COLOR_GRAY = 0x808080, 194 195 /** Green */ 196 LXW_COLOR_GREEN = 0x008000, 197 198 /** Lime */ 199 LXW_COLOR_LIME = 0x00FF00, 200 201 /** Magenta */ 202 LXW_COLOR_MAGENTA = 0xFF00FF, 203 204 /** Navy */ 205 LXW_COLOR_NAVY = 0x000080, 206 207 /** Orange */ 208 LXW_COLOR_ORANGE = 0xFF6600, 209 210 /** Pink */ 211 LXW_COLOR_PINK = 0xFF00FF, 212 213 /** Purple */ 214 LXW_COLOR_PURPLE = 0x800080, 215 216 /** Red */ 217 LXW_COLOR_RED = 0xFF0000, 218 219 /** Silver */ 220 LXW_COLOR_SILVER = 0xC0C0C0, 221 222 /** White */ 223 LXW_COLOR_WHITE = 0xFFFFFF, 224 225 /** Yellow */ 226 LXW_COLOR_YELLOW = 0xFFFF00 227 }; 228 229 /** Pattern value for use with format_set_pattern(). */ 230 enum lxw_format_patterns { 231 /** Empty pattern */ 232 LXW_PATTERN_NONE = 0, 233 234 /** Solid pattern */ 235 LXW_PATTERN_SOLID, 236 237 /** Medium gray pattern */ 238 LXW_PATTERN_MEDIUM_GRAY, 239 240 /** Dark gray pattern */ 241 LXW_PATTERN_DARK_GRAY, 242 243 /** Light gray pattern */ 244 LXW_PATTERN_LIGHT_GRAY, 245 246 /** Dark horizontal line pattern */ 247 LXW_PATTERN_DARK_HORIZONTAL, 248 249 /** Dark vertical line pattern */ 250 LXW_PATTERN_DARK_VERTICAL, 251 252 /** Dark diagonal stripe pattern */ 253 LXW_PATTERN_DARK_DOWN, 254 255 /** Reverse dark diagonal stripe pattern */ 256 LXW_PATTERN_DARK_UP, 257 258 /** Dark grid pattern */ 259 LXW_PATTERN_DARK_GRID, 260 261 /** Dark trellis pattern */ 262 LXW_PATTERN_DARK_TRELLIS, 263 264 /** Light horizontal Line pattern */ 265 LXW_PATTERN_LIGHT_HORIZONTAL, 266 267 /** Light vertical line pattern */ 268 LXW_PATTERN_LIGHT_VERTICAL, 269 270 /** Light diagonal stripe pattern */ 271 LXW_PATTERN_LIGHT_DOWN, 272 273 /** Reverse light diagonal stripe pattern */ 274 LXW_PATTERN_LIGHT_UP, 275 276 /** Light grid pattern */ 277 LXW_PATTERN_LIGHT_GRID, 278 279 /** Light trellis pattern */ 280 LXW_PATTERN_LIGHT_TRELLIS, 281 282 /** 12.5% gray pattern */ 283 LXW_PATTERN_GRAY_125, 284 285 /** 6.25% gray pattern */ 286 LXW_PATTERN_GRAY_0625 287 }; 288 289 /** Cell border styles for use with format_set_border(). */ 290 enum lxw_format_borders { 291 /** No border */ 292 LXW_BORDER_NONE, 293 294 /** Thin border style */ 295 LXW_BORDER_THIN, 296 297 /** Medium border style */ 298 LXW_BORDER_MEDIUM, 299 300 /** Dashed border style */ 301 LXW_BORDER_DASHED, 302 303 /** Dotted border style */ 304 LXW_BORDER_DOTTED, 305 306 /** Thick border style */ 307 LXW_BORDER_THICK, 308 309 /** Double border style */ 310 LXW_BORDER_DOUBLE, 311 312 /** Hair border style */ 313 LXW_BORDER_HAIR, 314 315 /** Medium dashed border style */ 316 LXW_BORDER_MEDIUM_DASHED, 317 318 /** Dash-dot border style */ 319 LXW_BORDER_DASH_DOT, 320 321 /** Medium dash-dot border style */ 322 LXW_BORDER_MEDIUM_DASH_DOT, 323 324 /** Dash-dot-dot border style */ 325 LXW_BORDER_DASH_DOT_DOT, 326 327 /** Medium dash-dot-dot border style */ 328 LXW_BORDER_MEDIUM_DASH_DOT_DOT, 329 330 /** Slant dash-dot border style */ 331 LXW_BORDER_SLANT_DASH_DOT 332 }; 333 334 /** 335 * @brief Struct to represent the formatting properties of an Excel format. 336 * 337 * Formats in `libxlsxwriter` are accessed via this struct. 338 * 339 * The members of the lxw_format struct aren't modified directly. Instead the 340 * format properties are set by calling the functions shown in format.h. 341 * 342 * For example: 343 * 344 * @code 345 * // Create the Format. 346 * lxw_format *format = workbook_add_format(workbook); 347 * 348 * // Set some of the format properties. 349 * format_set_bold(format); 350 * format_set_font_color(format, LXW_COLOR_RED); 351 * 352 * // Use the format to change the text format in a cell. 353 * worksheet_write_string(worksheet, 0, 0, "Hello", format); 354 * 355 * @endcode 356 * 357 */ 358 typedef struct lxw_format { 359 360 FILE *file; 361 362 lxw_hash_table *xf_format_indices; 363 lxw_hash_table *dxf_format_indices; 364 uint16_t *num_xf_formats; 365 uint16_t *num_dxf_formats; 366 367 int32_t xf_index; 368 int32_t dxf_index; 369 int32_t xf_id; 370 371 char num_format[LXW_FORMAT_FIELD_LEN]; 372 char font_name[LXW_FORMAT_FIELD_LEN]; 373 char font_scheme[LXW_FORMAT_FIELD_LEN]; 374 uint16_t num_format_index; 375 uint16_t font_index; 376 uint8_t has_font; 377 uint8_t has_dxf_font; 378 double font_size; 379 uint8_t bold; 380 uint8_t italic; 381 lxw_color_t font_color; 382 uint8_t underline; 383 uint8_t font_strikeout; 384 uint8_t font_outline; 385 uint8_t font_shadow; 386 uint8_t font_script; 387 uint8_t font_family; 388 uint8_t font_charset; 389 uint8_t font_condense; 390 uint8_t font_extend; 391 uint8_t theme; 392 uint8_t hyperlink; 393 394 uint8_t hidden; 395 uint8_t locked; 396 397 uint8_t text_h_align; 398 uint8_t text_wrap; 399 uint8_t text_v_align; 400 uint8_t text_justlast; 401 int16_t rotation; 402 403 lxw_color_t fg_color; 404 lxw_color_t bg_color; 405 lxw_color_t dxf_fg_color; 406 lxw_color_t dxf_bg_color; 407 uint8_t pattern; 408 uint8_t has_fill; 409 uint8_t has_dxf_fill; 410 int32_t fill_index; 411 int32_t fill_count; 412 413 int32_t border_index; 414 uint8_t has_border; 415 uint8_t has_dxf_border; 416 int32_t border_count; 417 418 uint8_t bottom; 419 uint8_t diag_border; 420 uint8_t diag_type; 421 uint8_t left; 422 uint8_t right; 423 uint8_t top; 424 lxw_color_t bottom_color; 425 lxw_color_t diag_color; 426 lxw_color_t left_color; 427 lxw_color_t right_color; 428 lxw_color_t top_color; 429 430 uint8_t indent; 431 uint8_t shrink; 432 uint8_t merge_range; 433 uint8_t reading_order; 434 uint8_t just_distrib; 435 uint8_t color_indexed; 436 uint8_t font_only; 437 438 STAILQ_ENTRY (lxw_format) list_pointers; 439 } lxw_format; 440 441 /* 442 * Struct to represent the font component of a format. 443 */ 444 typedef struct lxw_font { 445 446 char font_name[LXW_FORMAT_FIELD_LEN]; 447 double font_size; 448 uint8_t bold; 449 uint8_t italic; 450 uint8_t underline; 451 uint8_t theme; 452 uint8_t font_strikeout; 453 uint8_t font_outline; 454 uint8_t font_shadow; 455 uint8_t font_script; 456 uint8_t font_family; 457 uint8_t font_charset; 458 uint8_t font_condense; 459 uint8_t font_extend; 460 lxw_color_t font_color; 461 } lxw_font; 462 463 /* 464 * Struct to represent the border component of a format. 465 */ 466 typedef struct lxw_border { 467 468 uint8_t bottom; 469 uint8_t diag_border; 470 uint8_t diag_type; 471 uint8_t left; 472 uint8_t right; 473 uint8_t top; 474 475 lxw_color_t bottom_color; 476 lxw_color_t diag_color; 477 lxw_color_t left_color; 478 lxw_color_t right_color; 479 lxw_color_t top_color; 480 481 } lxw_border; 482 483 /* 484 * Struct to represent the fill component of a format. 485 */ 486 typedef struct lxw_fill { 487 488 lxw_color_t fg_color; 489 lxw_color_t bg_color; 490 uint8_t pattern; 491 492 } lxw_fill; 493 494 495 /* *INDENT-OFF* */ 496 #ifdef __cplusplus 497 extern "C" { 498 #endif 499 /* *INDENT-ON* */ 500 501 lxw_format *lxw_format_new(void); 502 void lxw_format_free(lxw_format *format); 503 int32_t lxw_format_get_xf_index(lxw_format *format); 504 int32_t lxw_format_get_dxf_index(lxw_format *format); 505 lxw_font *lxw_format_get_font_key(lxw_format *format); 506 lxw_border *lxw_format_get_border_key(lxw_format *format); 507 lxw_fill *lxw_format_get_fill_key(lxw_format *format); 508 509 /** 510 * @brief Set the font used in the cell. 511 * 512 * @param format Pointer to a Format instance. 513 * @param font_name Cell font name. 514 * 515 * Specify the font used used in the cell format: 516 * 517 * @code 518 * format_set_font_name(format, "Avenir Black Oblique"); 519 * @endcode 520 * 521 * @image html format_set_font_name.png 522 * 523 * Excel can only display fonts that are installed on the system that it is 524 * running on. Therefore it is generally best to use the fonts that come as 525 * standard with Excel such as Calibri, Times New Roman and Courier New. 526 * 527 * The default font in Excel 2007, and later, is Calibri. 528 */ 529 void format_set_font_name(lxw_format *format, const char *font_name); 530 531 /** 532 * @brief Set the size of the font used in the cell. 533 * 534 * @param format Pointer to a Format instance. 535 * @param size The cell font size. 536 * 537 * Set the font size of the cell format: 538 * 539 * @code 540 * format_set_font_size(format, 30); 541 * @endcode 542 * 543 * @image html format_font_size.png 544 * 545 * Excel adjusts the height of a row to accommodate the largest font 546 * size in the row. You can also explicitly specify the height of a 547 * row using the worksheet_set_row() function. 548 */ 549 void format_set_font_size(lxw_format *format, double size); 550 551 /** 552 * @brief Set the color of the font used in the cell. 553 * 554 * @param format Pointer to a Format instance. 555 * @param color The cell font color. 556 * 557 * 558 * Set the font color: 559 * 560 * @code 561 * format = workbook_add_format(workbook); 562 * format_set_font_color(format, LXW_COLOR_RED); 563 * 564 * worksheet_write_string(worksheet, 0, 0, "Wheelbarrow", format); 565 * @endcode 566 * 567 * @image html format_font_color.png 568 * 569 * The color should be an RGB integer value, see @ref working_with_colors. 570 * 571 * @note 572 * The format_set_font_color() method is used to set the font color in a 573 * cell. To set the color of a cell background use the format_set_bg_color() 574 * and format_set_pattern() methods. 575 */ 576 void format_set_font_color(lxw_format *format, lxw_color_t color); 577 578 /** 579 * @brief Turn on bold for the format font. 580 * 581 * @param format Pointer to a Format instance. 582 * 583 * Set the bold property of the font: 584 * 585 * @code 586 * format = workbook_add_format(workbook); 587 * format_set_bold(format); 588 * 589 * worksheet_write_string(worksheet, 0, 0, "Bold Text", format); 590 * @endcode 591 * 592 * @image html format_font_bold.png 593 */ 594 void format_set_bold(lxw_format *format); 595 596 /** 597 * @brief Turn on italic for the format font. 598 * 599 * @param format Pointer to a Format instance. 600 * 601 * Set the italic property of the font: 602 * 603 * @code 604 * format = workbook_add_format(workbook); 605 * format_set_italic(format); 606 * 607 * worksheet_write_string(worksheet, 0, 0, "Italic Text", format); 608 * @endcode 609 * 610 * @image html format_font_italic.png 611 */ 612 void format_set_italic(lxw_format *format); 613 614 /** 615 * @brief Turn on underline for the format: 616 * 617 * @param format Pointer to a Format instance. 618 * @param style Underline style. 619 * 620 * Set the underline property of the format: 621 * 622 * @code 623 * format_set_underline(format, LXW_UNDERLINE_SINGLE); 624 * @endcode 625 * 626 * @image html format_font_underlined.png 627 * 628 * The available underline styles are: 629 * 630 * - #LXW_UNDERLINE_SINGLE 631 * - #LXW_UNDERLINE_DOUBLE 632 * - #LXW_UNDERLINE_SINGLE_ACCOUNTING 633 * - #LXW_UNDERLINE_DOUBLE_ACCOUNTING 634 * 635 */ 636 void format_set_underline(lxw_format *format, uint8_t style); 637 638 /** 639 * @brief Set the strikeout property of the font. 640 * 641 * @param format Pointer to a Format instance. 642 * 643 * @image html format_font_strikeout.png 644 * 645 */ 646 void format_set_font_strikeout(lxw_format *format); 647 648 /** 649 * @brief Set the superscript/subscript property of the font. 650 * 651 * @param format Pointer to a Format instance. 652 * @param style Superscript or subscript style. 653 * 654 * Set the superscript o subscript property of the font. 655 * 656 * @image html format_font_script.png 657 * 658 * The available script styles are: 659 * 660 * - #LXW_FONT_SUPERSCRIPT 661 * - #LXW_FONT_SUBSCRIPT 662 */ 663 void format_set_font_script(lxw_format *format, uint8_t style); 664 665 /** 666 * @brief Set the number format for a cell. 667 * 668 * @param format Pointer to a Format instance. 669 * @param num_format The cell number format string. 670 * 671 * This method is used to define the numerical format of a number in 672 * Excel. It controls whether a number is displayed as an integer, a 673 * floating point number, a date, a currency value or some other user 674 * defined format. 675 * 676 * The numerical format of a cell can be specified by using a format 677 * string: 678 * 679 * @code 680 * format = workbook_add_format(workbook); 681 * format_set_num_format(format, "d mmm yyyy"); 682 * @endcode 683 * 684 * Format strings can control any aspect of number formatting allowed by Excel: 685 * 686 * @dontinclude format_num_format.c 687 * @skipline set_num_format 688 * @until 1209 689 * 690 * @image html format_set_num_format.png 691 * 692 * To set a number format that matches an Excel format category such as "Date" 693 * or "Currency" see @ref ww_formats_categories. 694 * 695 * The number system used for dates is described in @ref working_with_dates. 696 * 697 * For more information on number formats in Excel refer to the 698 * [Microsoft documentation on cell formats](http://office.microsoft.com/en-gb/assistance/HP051995001033.aspx). 699 */ 700 void format_set_num_format(lxw_format *format, const char *num_format); 701 702 /** 703 * @brief Set the Excel built-in number format for a cell. 704 * 705 * @param format Pointer to a Format instance. 706 * @param index The built-in number format index for the cell. 707 * 708 * This function is similar to format_set_num_format() except that it takes an 709 * index to a limited number of Excel's built-in number formats instead of a 710 * user defined format string: 711 * 712 * @code 713 * format = workbook_add_format(workbook); 714 * format_set_num_format_index(format, 0x0F); // d-mmm-yy 715 * @endcode 716 * 717 * @note 718 * Unless you need to specifically access one of Excel's built-in number 719 * formats the format_set_num_format() function above is a better 720 * solution. The format_set_num_format_index() function is mainly included for 721 * backward compatibility and completeness. 722 * 723 * The Excel built-in number formats as shown in the table below: 724 * 725 * | Index | Index | Format String | 726 * | ----- | ----- | ---------------------------------------------------- | 727 * | 0 | 0x00 | `General` | 728 * | 1 | 0x01 | `0` | 729 * | 2 | 0x02 | `0.00` | 730 * | 3 | 0x03 | `#,##0` | 731 * | 4 | 0x04 | `#,##0.00` | 732 * | 5 | 0x05 | `($#,##0_);($#,##0)` | 733 * | 6 | 0x06 | `($#,##0_);[Red]($#,##0)` | 734 * | 7 | 0x07 | `($#,##0.00_);($#,##0.00)` | 735 * | 8 | 0x08 | `($#,##0.00_);[Red]($#,##0.00)` | 736 * | 9 | 0x09 | `0%` | 737 * | 10 | 0x0a | `0.00%` | 738 * | 11 | 0x0b | `0.00E+00` | 739 * | 12 | 0x0c | `# ?/?` | 740 * | 13 | 0x0d | `# ??/??` | 741 * | 14 | 0x0e | `m/d/yy` | 742 * | 15 | 0x0f | `d-mmm-yy` | 743 * | 16 | 0x10 | `d-mmm` | 744 * | 17 | 0x11 | `mmm-yy` | 745 * | 18 | 0x12 | `h:mm AM/PM` | 746 * | 19 | 0x13 | `h:mm:ss AM/PM` | 747 * | 20 | 0x14 | `h:mm` | 748 * | 21 | 0x15 | `h:mm:ss` | 749 * | 22 | 0x16 | `m/d/yy h:mm` | 750 * | ... | ... | ... | 751 * | 37 | 0x25 | `(#,##0_);(#,##0)` | 752 * | 38 | 0x26 | `(#,##0_);[Red](#,##0)` | 753 * | 39 | 0x27 | `(#,##0.00_);(#,##0.00)` | 754 * | 40 | 0x28 | `(#,##0.00_);[Red](#,##0.00)` | 755 * | 41 | 0x29 | `_(* #,##0_);_(* (#,##0);_(* "-"_);_(@_)` | 756 * | 42 | 0x2a | `_($* #,##0_);_($* (#,##0);_($* "-"_);_(@_)` | 757 * | 43 | 0x2b | `_(* #,##0.00_);_(* (#,##0.00);_(* "-"??_);_(@_)` | 758 * | 44 | 0x2c | `_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)` | 759 * | 45 | 0x2d | `mm:ss` | 760 * | 46 | 0x2e | `[h]:mm:ss` | 761 * | 47 | 0x2f | `mm:ss.0` | 762 * | 48 | 0x30 | `##0.0E+0` | 763 * | 49 | 0x31 | `@` | 764 * 765 * @note 766 * - Numeric formats 23 to 36 are not documented by Microsoft and may differ 767 * in international versions. The listed date and currency formats may also 768 * vary depending on system settings. 769 * - The dollar sign in the above format appears as the defined local currency 770 * symbol. 771 * - These formats can also be set via format_set_num_format(). 772 * - See also @ref ww_formats_categories. 773 */ 774 void format_set_num_format_index(lxw_format *format, uint8_t index); 775 776 /** 777 * @brief Set the cell unlocked state. 778 * 779 * @param format Pointer to a Format instance. 780 * 781 * This property can be used to allow modification of a cell in a protected 782 * worksheet. In Excel, cell locking is turned on by default for all 783 * cells. However, it only has an effect if the worksheet has been protected 784 * using the worksheet worksheet_protect() function: 785 * 786 * @code 787 * format = workbook_add_format(workbook); 788 * format_set_unlocked(format); 789 * 790 * // Enable worksheet protection, without password or options. 791 * worksheet_protect(worksheet, NULL, NULL); 792 * 793 * // This cell cannot be edited. 794 * worksheet_write_formula(worksheet, 0, 0, "=1+2", NULL); 795 * 796 * // This cell can be edited. 797 * worksheet_write_formula(worksheet, 1, 0, "=1+2", format); 798 * @endcode 799 */ 800 void format_set_unlocked(lxw_format *format); 801 802 /** 803 * @brief Hide formulas in a cell. 804 * 805 * @param format Pointer to a Format instance. 806 * 807 * This property is used to hide a formula while still displaying its 808 * result. This is generally used to hide complex calculations from end users 809 * who are only interested in the result. It only has an effect if the 810 * worksheet has been protected using the worksheet worksheet_protect() 811 * function: 812 * 813 * @code 814 * format = workbook_add_format(workbook); 815 * format_set_hidden(format); 816 * 817 * // Enable worksheet protection, without password or options. 818 * worksheet_protect(worksheet, NULL, NULL); 819 * 820 * // The formula in this cell isn't visible. 821 * worksheet_write_formula(worksheet, 0, 0, "=1+2", format); 822 * @endcode 823 */ 824 void format_set_hidden(lxw_format *format); 825 826 /** 827 * @brief Set the alignment for data in the cell. 828 * 829 * @param format Pointer to a Format instance. 830 * @param alignment The horizontal and or vertical alignment direction. 831 * 832 * This method is used to set the horizontal and vertical text alignment within a 833 * cell. The following are the available horizontal alignments: 834 * 835 * - #LXW_ALIGN_LEFT 836 * - #LXW_ALIGN_CENTER 837 * - #LXW_ALIGN_RIGHT 838 * - #LXW_ALIGN_FILL 839 * - #LXW_ALIGN_JUSTIFY 840 * - #LXW_ALIGN_CENTER_ACROSS 841 * - #LXW_ALIGN_DISTRIBUTED 842 * 843 * The following are the available vertical alignments: 844 * 845 * - #LXW_ALIGN_VERTICAL_TOP 846 * - #LXW_ALIGN_VERTICAL_BOTTOM 847 * - #LXW_ALIGN_VERTICAL_CENTER 848 * - #LXW_ALIGN_VERTICAL_JUSTIFY 849 * - #LXW_ALIGN_VERTICAL_DISTRIBUTED 850 * 851 * As in Excel, vertical and horizontal alignments can be combined: 852 * 853 * @code 854 * format = workbook_add_format(workbook); 855 * 856 * format_set_align(format, LXW_ALIGN_CENTER); 857 * format_set_align(format, LXW_ALIGN_VERTICAL_CENTER); 858 * 859 * worksheet_set_row(0, 30); 860 * worksheet_write_string(worksheet, 0, 0, "Some Text", format); 861 * @endcode 862 * 863 * @image html format_font_align.png 864 * 865 * Text can be aligned across two or more adjacent cells using the 866 * center_across property. However, for genuine merged cells it is better to 867 * use the worksheet_merge_range() worksheet method. 868 * 869 * The vertical justify option can be used to provide automatic text wrapping 870 * in a cell. The height of the cell will be adjusted to accommodate the 871 * wrapped text. To specify where the text wraps use the 872 * format_set_text_wrap() method. 873 */ 874 void format_set_align(lxw_format *format, uint8_t alignment); 875 876 /** 877 * @brief Wrap text in a cell. 878 * 879 * Turn text wrapping on for text in a cell. 880 * 881 * @code 882 * format = workbook_add_format(workbook); 883 * format_set_text_wrap(format); 884 * 885 * worksheet_write_string(worksheet, 0, 0, "Some long text to wrap in a cell", format); 886 * @endcode 887 * 888 * If you wish to control where the text is wrapped you can add newline characters 889 * to the string: 890 * 891 * @code 892 * format = workbook_add_format(workbook); 893 * format_set_text_wrap(format); 894 * 895 * worksheet_write_string(worksheet, 0, 0, "It's\na bum\nwrap", format); 896 * @endcode 897 * 898 * @image html format_font_text_wrap.png 899 * 900 * Excel will adjust the height of the row to accommodate the wrapped text. A 901 * similar effect can be obtained without newlines using the 902 * format_set_align() function with #LXW_ALIGN_VERTICAL_JUSTIFY. 903 */ 904 void format_set_text_wrap(lxw_format *format); 905 906 /** 907 * @brief Set the rotation of the text in a cell. 908 * 909 * @param format Pointer to a Format instance. 910 * @param angle Rotation angle in the range -90 to 90 and 270. 911 * 912 * Set the rotation of the text in a cell. The rotation can be any angle in the 913 * range -90 to 90 degrees: 914 * 915 * @code 916 * format = workbook_add_format(workbook); 917 * format_set_rotation(format, 30); 918 * 919 * worksheet_write_string(worksheet, 0, 0, "This text is rotated", format); 920 * @endcode 921 * 922 * @image html format_font_text_rotated.png 923 * 924 * The angle 270 is also supported. This indicates text where the letters run from 925 * top to bottom. 926 */ 927 void format_set_rotation(lxw_format *format, int16_t angle); 928 929 /** 930 * @brief Set the cell text indentation level. 931 * 932 * @param format Pointer to a Format instance. 933 * @param level Indentation level. 934 * 935 * This method can be used to indent text in a cell. The argument, which should be 936 * an integer, is taken as the level of indentation: 937 * 938 * @code 939 * format1 = workbook_add_format(workbook); 940 * format2 = workbook_add_format(workbook); 941 * 942 * format_set_indent(format1, 1); 943 * format_set_indent(format2, 2); 944 * 945 * worksheet_write_string(worksheet, 0, 0, "This text is indented 1 level", format1); 946 * worksheet_write_string(worksheet, 1, 0, "This text is indented 2 levels", format2); 947 * @endcode 948 * 949 * @image html text_indent.png 950 * 951 * @note 952 * Indentation is a horizontal alignment property. It will override any other 953 * horizontal properties but it can be used in conjunction with vertical 954 * properties. 955 */ 956 void format_set_indent(lxw_format *format, uint8_t level); 957 958 /** 959 * @brief Turn on the text "shrink to fit" for a cell. 960 * 961 * @param format Pointer to a Format instance. 962 * 963 * This method can be used to shrink text so that it fits in a cell: 964 * 965 * @code 966 * format = workbook_add_format(workbook); 967 * format_set_shrink(format); 968 * 969 * worksheet_write_string(worksheet, 0, 0, "Honey, I shrunk the text!", format); 970 * @endcode 971 */ 972 void format_set_shrink(lxw_format *format); 973 974 /** 975 * @brief Set the background fill pattern for a cell 976 * 977 * @param format Pointer to a Format instance. 978 * @param index Pattern index. 979 * 980 * Set the background pattern for a cell. 981 * 982 * The most common pattern is a solid fill of the background color: 983 * 984 * @code 985 * format = workbook_add_format(workbook); 986 * 987 * format_set_pattern (format, LXW_PATTERN_SOLID); 988 * format_set_bg_color(format, LXW_COLOR_YELLOW); 989 * @endcode 990 * 991 * The available fill patterns are: 992 * 993 * Fill Type | Define 994 * ----------------------------- | ----------------------------- 995 * Solid | #LXW_PATTERN_SOLID 996 * Medium gray | #LXW_PATTERN_MEDIUM_GRAY 997 * Dark gray | #LXW_PATTERN_DARK_GRAY 998 * Light gray | #LXW_PATTERN_LIGHT_GRAY 999 * Dark horizontal line | #LXW_PATTERN_DARK_HORIZONTAL 1000 * Dark vertical line | #LXW_PATTERN_DARK_VERTICAL 1001 * Dark diagonal stripe | #LXW_PATTERN_DARK_DOWN 1002 * Reverse dark diagonal stripe | #LXW_PATTERN_DARK_UP 1003 * Dark grid | #LXW_PATTERN_DARK_GRID 1004 * Dark trellis | #LXW_PATTERN_DARK_TRELLIS 1005 * Light horizontal line | #LXW_PATTERN_LIGHT_HORIZONTAL 1006 * Light vertical line | #LXW_PATTERN_LIGHT_VERTICAL 1007 * Light diagonal stripe | #LXW_PATTERN_LIGHT_DOWN 1008 * Reverse light diagonal stripe | #LXW_PATTERN_LIGHT_UP 1009 * Light grid | #LXW_PATTERN_LIGHT_GRID 1010 * Light trellis | #LXW_PATTERN_LIGHT_TRELLIS 1011 * 12.5% gray | #LXW_PATTERN_GRAY_125 1012 * 6.25% gray | #LXW_PATTERN_GRAY_0625 1013 * 1014 */ 1015 void format_set_pattern(lxw_format *format, uint8_t index); 1016 1017 /** 1018 * @brief Set the pattern background color for a cell. 1019 * 1020 * @param format Pointer to a Format instance. 1021 * @param color The cell pattern background color. 1022 * 1023 * The format_set_bg_color() method can be used to set the background color of 1024 * a pattern. Patterns are defined via the format_set_pattern() method. If a 1025 * pattern hasn't been defined then a solid fill pattern is used as the 1026 * default. 1027 * 1028 * Here is an example of how to set up a solid fill in a cell: 1029 * 1030 * @code 1031 * format = workbook_add_format(workbook); 1032 * 1033 * format_set_pattern (format, LXW_PATTERN_SOLID); 1034 * format_set_bg_color(format, LXW_COLOR_GREEN); 1035 * 1036 * worksheet_write_string(worksheet, 0, 0, "Ray", format); 1037 * @endcode 1038 * 1039 * @image html formats_set_bg_color.png 1040 * 1041 * The color should be an RGB integer value, see @ref working_with_colors. 1042 * 1043 */ 1044 void format_set_bg_color(lxw_format *format, lxw_color_t color); 1045 1046 /** 1047 * @brief Set the pattern foreground color for a cell. 1048 * 1049 * @param format Pointer to a Format instance. 1050 * @param color The cell pattern foreground color. 1051 * 1052 * The format_set_fg_color() method can be used to set the foreground color of 1053 * a pattern. 1054 * 1055 * The color should be an RGB integer value, see @ref working_with_colors. 1056 * 1057 */ 1058 void format_set_fg_color(lxw_format *format, lxw_color_t color); 1059 1060 /** 1061 * @brief Set the cell border style. 1062 * 1063 * @param format Pointer to a Format instance. 1064 * @param style Border style index. 1065 * 1066 * Set the cell border style: 1067 * 1068 * @code 1069 * format_set_border(format, LXW_BORDER_THIN); 1070 * @endcode 1071 * 1072 * Individual border elements can be configured using the following functions with 1073 * the same parameters: 1074 * 1075 * - format_set_bottom() 1076 * - format_set_top() 1077 * - format_set_left() 1078 * - format_set_right() 1079 * 1080 * A cell border is comprised of a border on the bottom, top, left and right. 1081 * These can be set to the same value using format_set_border() or 1082 * individually using the relevant method calls shown above. 1083 * 1084 * The following border styles are available: 1085 * 1086 * - #LXW_BORDER_THIN 1087 * - #LXW_BORDER_MEDIUM 1088 * - #LXW_BORDER_DASHED 1089 * - #LXW_BORDER_DOTTED 1090 * - #LXW_BORDER_THICK 1091 * - #LXW_BORDER_DOUBLE 1092 * - #LXW_BORDER_HAIR 1093 * - #LXW_BORDER_MEDIUM_DASHED 1094 * - #LXW_BORDER_DASH_DOT 1095 * - #LXW_BORDER_MEDIUM_DASH_DOT 1096 * - #LXW_BORDER_DASH_DOT_DOT 1097 * - #LXW_BORDER_MEDIUM_DASH_DOT_DOT 1098 * - #LXW_BORDER_SLANT_DASH_DOT 1099 * 1100 * The most commonly used style is the `thin` style. 1101 */ 1102 void format_set_border(lxw_format *format, uint8_t style); 1103 1104 /** 1105 * @brief Set the cell bottom border style. 1106 * 1107 * @param format Pointer to a Format instance. 1108 * @param style Border style index. 1109 * 1110 * Set the cell bottom border style. See format_set_border() for details on the 1111 * border styles. 1112 */ 1113 void format_set_bottom(lxw_format *format, uint8_t style); 1114 1115 /** 1116 * @brief Set the cell top border style. 1117 * 1118 * @param format Pointer to a Format instance. 1119 * @param style Border style index. 1120 * 1121 * Set the cell top border style. See format_set_border() for details on the border 1122 * styles. 1123 */ 1124 void format_set_top(lxw_format *format, uint8_t style); 1125 1126 /** 1127 * @brief Set the cell left border style. 1128 * 1129 * @param format Pointer to a Format instance. 1130 * @param style Border style index. 1131 * 1132 * Set the cell left border style. See format_set_border() for details on the 1133 * border styles. 1134 */ 1135 void format_set_left(lxw_format *format, uint8_t style); 1136 1137 /** 1138 * @brief Set the cell right border style. 1139 * 1140 * @param format Pointer to a Format instance. 1141 * @param style Border style index. 1142 * 1143 * Set the cell right border style. See format_set_border() for details on the 1144 * border styles. 1145 */ 1146 void format_set_right(lxw_format *format, uint8_t style); 1147 1148 /** 1149 * @brief Set the color of the cell border. 1150 * 1151 * @param format Pointer to a Format instance. 1152 * @param color The cell border color. 1153 * 1154 * Individual border elements can be configured using the following methods with 1155 * the same parameters: 1156 * 1157 * - format_set_bottom_color() 1158 * - format_set_top_color() 1159 * - format_set_left_color() 1160 * - format_set_right_color() 1161 * 1162 * Set the color of the cell borders. A cell border is comprised of a border 1163 * on the bottom, top, left and right. These can be set to the same color 1164 * using format_set_border_color() or individually using the relevant method 1165 * calls shown above. 1166 * 1167 * The color should be an RGB integer value, see @ref working_with_colors. 1168 */ 1169 void format_set_border_color(lxw_format *format, lxw_color_t color); 1170 1171 /** 1172 * @brief Set the color of the bottom cell border. 1173 * 1174 * @param format Pointer to a Format instance. 1175 * @param color The cell border color. 1176 * 1177 * See format_set_border_color() for details on the border colors. 1178 */ 1179 void format_set_bottom_color(lxw_format *format, lxw_color_t color); 1180 1181 /** 1182 * @brief Set the color of the top cell border. 1183 * 1184 * @param format Pointer to a Format instance. 1185 * @param color The cell border color. 1186 * 1187 * See format_set_border_color() for details on the border colors. 1188 */ 1189 void format_set_top_color(lxw_format *format, lxw_color_t color); 1190 1191 /** 1192 * @brief Set the color of the left cell border. 1193 * 1194 * @param format Pointer to a Format instance. 1195 * @param color The cell border color. 1196 * 1197 * See format_set_border_color() for details on the border colors. 1198 */ 1199 void format_set_left_color(lxw_format *format, lxw_color_t color); 1200 1201 /** 1202 * @brief Set the color of the right cell border. 1203 * 1204 * @param format Pointer to a Format instance. 1205 * @param color The cell border color. 1206 * 1207 * See format_set_border_color() for details on the border colors. 1208 */ 1209 void format_set_right_color(lxw_format *format, lxw_color_t color); 1210 1211 /** 1212 * @brief Set the diagonal cell border type. 1213 * 1214 * @param format Pointer to a Format instance. 1215 * @param type The #lxw_format_diagonal_types diagonal border type. 1216 * 1217 * Set the diagonal cell border type: 1218 * 1219 * @code 1220 * lxw_format *format1 = workbook_add_format(workbook); 1221 * format_set_diag_type( format1, LXW_DIAGONAL_BORDER_UP); 1222 * 1223 * lxw_format *format2 = workbook_add_format(workbook); 1224 * format_set_diag_type( format2, LXW_DIAGONAL_BORDER_DOWN); 1225 * 1226 * lxw_format *format3 = workbook_add_format(workbook); 1227 * format_set_diag_type( format3, LXW_DIAGONAL_BORDER_UP_DOWN); 1228 * 1229 * lxw_format *format4 = workbook_add_format(workbook); 1230 * format_set_diag_type( format4, LXW_DIAGONAL_BORDER_UP_DOWN); 1231 * format_set_diag_border(format4, LXW_BORDER_HAIR); 1232 * format_set_diag_color( format4, LXW_COLOR_RED); 1233 * 1234 * worksheet_write_string(worksheet, CELL("B3"), "Text", format1); 1235 * worksheet_write_string(worksheet, CELL("B6"), "Text", format2); 1236 * worksheet_write_string(worksheet, CELL("B9"), "Text", format3); 1237 * worksheet_write_string(worksheet, CELL("B12"), "Text", format4); 1238 * @endcode 1239 * 1240 * @image html diagonal_border.png 1241 * 1242 * The allowable border types are defined in #lxw_format_diagonal_types: 1243 * 1244 * - #LXW_DIAGONAL_BORDER_UP: Cell diagonal border from bottom left to top 1245 * right. 1246 * 1247 * - #LXW_DIAGONAL_BORDER_DOWN: Cell diagonal border from top left to bottom 1248 * right. 1249 * 1250 * - #LXW_DIAGONAL_BORDER_UP_DOWN: Cell diagonal border from top left to 1251 * bottom right. A combination of the 2 previous types. 1252 * 1253 * If the border style isn't specified with `format_set_diag_border()` then it 1254 * will default to #LXW_BORDER_THIN. 1255 */ 1256 void format_set_diag_type(lxw_format *format, uint8_t type); 1257 1258 /** 1259 * @brief Set the diagonal cell border style. 1260 * 1261 * @param format Pointer to a Format instance. 1262 * @param style The #lxw_format_borders style. 1263 * 1264 * Set the diagonal border style. This should be a #lxw_format_borders value. 1265 * See the example above. 1266 * 1267 */ 1268 void format_set_diag_border(lxw_format *format, uint8_t style); 1269 1270 /** 1271 * @brief Set the diagonal cell border color. 1272 * 1273 * @param format Pointer to a Format instance. 1274 * @param color The cell diagonal border color. 1275 * 1276 * Set the diagonal border color. The color should be an RGB integer value, 1277 * see @ref working_with_colors and the above example. 1278 */ 1279 void format_set_diag_color(lxw_format *format, lxw_color_t color); 1280 1281 void format_set_font_outline(lxw_format *format); 1282 void format_set_font_shadow(lxw_format *format); 1283 void format_set_font_family(lxw_format *format, uint8_t value); 1284 void format_set_font_charset(lxw_format *format, uint8_t value); 1285 void format_set_font_scheme(lxw_format *format, const char *font_scheme); 1286 void format_set_font_condense(lxw_format *format); 1287 void format_set_font_extend(lxw_format *format); 1288 void format_set_reading_order(lxw_format *format, uint8_t value); 1289 void format_set_theme(lxw_format *format, uint8_t value); 1290 void format_set_hyperlink(lxw_format *format); 1291 void format_set_color_indexed(lxw_format *format, uint8_t value); 1292 void format_set_font_only(lxw_format *format); 1293 1294 /* Declarations required for unit testing. */ 1295 #ifdef TESTING 1296 1297 #endif /* TESTING */ 1298 1299 /* *INDENT-OFF* */ 1300 #ifdef __cplusplus 1301 } 1302 #endif 1303 /* *INDENT-ON* */ 1304 1305 #endif /* __LXW_FORMAT_H__ */ 1306