`)
117 | - Removed Tab and Float Tags (`
`, ``, ``) - *please use new Div tag*
118 | - New Header Tag (``)
119 | - New Custom Style Tag (` - Custom style, according to CustomStyles collection property (name must be the same as Custom Style "Ident" property - case insensitive)
452 |
- Line Break (Use "cont" parameter to a continous line. If parameter not specified, a new paragraph will be considered)
453 | - Prevent new line if used after a line break sequence
454 | - Align Left
455 | - Align Center
456 | - Align Right
457 | - Image from ImageList where 'index' is image index
458 | - PNG image from Resource where 'name' is the resource name
459 | - Unordered list
460 |
- Ordered list
461 | - List item
462 | - Spoiler Title (use "exp" param to show spoiler already expanded)
463 | - Spoiler Detail
464 | - Line spacing where 'aaa' is the height in pixels, and 'bbb' is the height when a new paragraph (plus original line space)
465 | - Paragraph Indent - left margin of a new paragraph in pixels
466 | - Superscript
467 | - Subscript
468 | - Horizontal single or dual color line
469 | "full" option only works when AutoWidth of parent div is disabled
470 | Default values:
471 | width = 100
472 | height = 1
473 | color = Current font color
474 | coloralt = No value (specify a color to draw dual color line, otherwise it will draw a single color line)
475 | - Aligning content vertically to the line
476 | - Content margin spacing
477 | Offset margins are memorized if a new offset tag is specifyed without same parameter name
478 |
479 | OBSOLETE TAGS:
480 | - Tab - left margin offset
481 | - Tab with continuous lines aligned
482 | - Floating div area
483 |
484 | ----------
485 |
486 | * COLOR_VALUE - clColor(VCL)|Color(FMX)|$00GGBBRR|#AARRGGBB|#RRGGBB
487 | * When FMX, all sizes (TPixels) use the "." notation as a decimal separator
488 | ```
489 |
490 | > The tags notation is case-insensitive, so you can use `Text` or `Text`.
491 |
492 | Tags must follow the hierarchy as they were opened:
493 |
494 | - `text` = CORRECT
495 | - `text` = WRONG
496 |
497 | 
498 |
499 | ## Installing
500 |
501 | > If you are using Lazarus: go to the Package menu; Open Package File (.lpk); locate LazDzHTMLText.lpk; open the package; Compile it and Install it.
502 |
503 | ### Autoinstall
504 |
505 | 1. Download Component Installer from: https://github.com/digao-dalpiaz/CompInstall/releases/latest
506 | 2. Put **CompInstall.exe** into the component repository sources folder.
507 | 3. Close Delphi IDE and run **CompInstall.exe** app.
508 |
509 | ### Manual install
510 |
511 | 1. Open **DzHTMLText.groupproj** project in Delphi.
512 | 2. Choose desired platform and ensure **Release** config are selected in all packages (Design packages must be compiled in Win32 platform).
513 | 3. Right-click at root item in the tree and choose **Build All**.
514 | 4. Right-click at **DzHTMLTextDesign_VCL** / **DzHTMLTextDesign_FMX** and choose **Install**.
515 | 5. Add Library Path according to the platform in Tools\Options. Example: If you are using Win32, set path = `Lib\Win32\Release`.
516 |
517 | Supports Delphi XE3..Delphi 12
518 |
519 | ## Component Properties
520 |
521 | > **TPixels** represents `Integer` in **VCL**, or `Single` in **FMX**.
522 |
523 | `AutoBreak: Boolean` = When enabled, the component automatically converts Line Break sequence into a new line. If you don't want the line break in a specific sequence, you can use the `` tag after Line Break sequence.
524 |
525 | `AutoHeight: Boolean` = Auto set height of control when Text property changed
526 |
527 | `AutoWidth: Boolean` = Auto set width of control when Text property changed.
528 | If you are using AutoWidth, the text never wraps to a new line unless a line break is specified at text or there is a value specified in MaxWidth property.
529 |
530 | `AutoOpenLink: Boolean` = Open links automatically on click over, without set event OnLinkClick.
531 |
532 | `Borders: TDHBorders` = Defines `Left`, `Top`, `Right` and `Bottom` sub-properties, specifying the text area margins.
533 |
534 | `Color: TColor` = Background color of control. In FMX environment, `Null` represents transparent background.
535 |
536 | `CustomStyles: TDHHeaderStyles` = Collection of header styles to use with tag ``, where `ident` is Ident property of a header style in collection list.
537 |
538 | `Font: TFont` = Determines the base font. When no tag is specified on text, this base font is used.
539 |
540 | `Images: TCustomImageList` = When using `
` tag, you should set this property to specify the ImageList where the images are stored. In FMX environment, this property is only available using Delphi XE8 or higher.
541 |
542 | `LineCount: Integer` = Returns the total lines of text, according to the bounds of control. This property is read-only.
543 |
544 | `Lines: TStrings` = The text you want to show at label control. You can use `
` tag to break lines. The default Line Break sequence breaks lines either when AutoBreak property is enabled.
545 |
546 | `LineSpacing: TPixels` = Specify the default line spacing in overall text. You can use `` tag to determine line spacing at specific lines.
547 |
548 | `LineHorzAlign: TDHHorzAlign (haLeft, haCenter, haRight)` = Allows you to specify the horizontal alignment of each element in the line. Default is `haLeft`.
549 |
550 | `LineVertAlign: TDHVertAlign (vaTop, vaCenter, vaBottom)` = Allows you to specify the vertical alignment of each element in the line. This property only take effects when the elements have different heights at same line. Default is `vaTop`.
551 |
552 | `ListLevelPadding: TPixels` = Determines the width of each list level in pixels, when using HTML list tags.
553 |
554 | `MaxWidth: TPixels` = Specify the maximum width of text, when using AutoWidth property.
555 |
556 | `Offset: TDHOffset` = Sets Top and Bottom offset (spacing in Pixels) for each line. When using `` tag, it will replace this setting, according to the specified attribute (top and/or bottom).
557 |
558 | `OverallHorzAlign: TDHHorzAlign (haLeft, haCenter, haRight)` = Determines overall text horizontal alignment. This property only take effects if `AutoWidth` is false.
559 |
560 | `OverallVertAlign: TDHVertAlign (vaTop, vaCenter, vaBottom)` = Determines overall text vertical alignment. This property only take effects if `AutoHeight` is false.
561 |
562 | `ParagraphCount: Integer` = Returns the total paragraphs of text. This property is read-only.
563 |
564 | `ParagraphIndent: TPixels` = Default left margin of a new paragraph.
565 |
566 | `ParagraphSpacing: TPixels` = Specify the default paragraph spacing in overall text. The paragraph spacing is added to original line spacing. You can use `` tag to determine paragraph spacing at specific lines.
567 |
568 | `RightToLeftText: Boolean` = Enables Right-to-left text notation.
569 |
570 | `StyleLinkNormal: TDHStyleLinkProp` = Properties to format a link when is not selected by mouse.
571 |
572 | `StyleLinkHover: TDHStyleLinkProp` = Properties to format a link when is selected by mouse.
573 |
574 | `SyntaxErrors: TDHSyntaxErrorList` (public) = List of syntax errors. Right click on component and choose "Show Syntax Errors" at design time to show syntax errors. **When any syntax error, at design time the border of the component will be draw with red color.**
575 |
576 | `Text: string` (public) = This property is a shortcut to `Lines` property. At run-time, you can read and write this property directly, but the component will store the text at `Lines` property.
577 |
578 | `TextHeight: TPixels` = Returns the total text height. This property is read-only.
579 |
580 | `TextWidth: TPixels` = Returns the total text width. This property is read-only.
581 |
582 | `Transparent: Boolean` (only in VCL) = Enables component transparency. **Warning: When using with links, it will cause flickering when redrawing component.**
583 |
584 | ## Events
585 |
586 | ```delphi
587 | procedure OnLinkEnter(Sender: TObject; Link: TDHBaseLink);
588 | ```
589 | This event is fired when the mouse enters a link area
590 |
591 | ```delphi
592 | procedure OnLinkLeave(Sender: TObject; Link: TDHBaseLink);
593 | ```
594 | This event is fired when the mouse leaves a link area
595 |
596 | ```delphi
597 | procedure OnLinkClick(Sender: TObject; Link: TDHBaseLink; var Handled: Boolean);
598 | ```
599 | This event is fired when a link is left-clicked by the mouse. You can use Handled var to by-pass the AutoOpenLink property (the handled value is False at method start).
600 |
601 | ```delphi
602 | procedure OnLinkRightClick(Sender: TObject; Link: TDHBaseLink; var Handled: Boolean);
603 | ```
604 | This event is fired when a link is right-clicked by the mouse. You can use Handled var to by-pass the AutoOpenLink property (the handled value is False at method start).
605 |
606 | ```delphi
607 | procedure OnRetrieveImgRes(Sender: TObject; const ResourceName: string; Picture: TAnyPicture; var Handled: Boolean);
608 | ```
609 | If you are using `` tag, this event will fire on every image tag, allowing you to manually load a image from anywhere, in any image format, assigning it to Picture object. Be sure to set `Handled := True` when you manually load an image.
610 | *Not using this event causes the component to automatically load the image from application resources by name, and must be in PNG format when using VCL environment. In FMX environment you can use any image format supported by Delphi.*
611 |
612 | Example:
613 |
614 | ```delphi
615 | procedure TForm1.DzHTMLText1RetrieveImgRes(Sender: TObject; const ResourceName: string;
616 | Picture: TAnyPicture; var Handled: Boolean);
617 | var JPG: TJpegImage;
618 | begin
619 | if ResourceName='TEST' then
620 | begin
621 | JPG := TJpegImage.Create;
622 | try
623 | JPG.LoadFromFile('C:\Test.jpg');
624 | Picture.Assign(JPG);
625 | finally
626 | JPG.Free;
627 | end;
628 |
629 | Handled := True;
630 | end;
631 | end;
632 | ```
633 |
634 | ## Procedures/Functions
635 |
636 | ```delphi
637 | function IsLinkHover: Boolean;
638 | ```
639 | This function returns true when the mouse is over a link
640 |
641 | ```delphi
642 | function SelectedLink: TDHBaseLink;
643 | ```
644 | This function returns the object of the selected link. A link is selected when the mouse is over it. If there is no link selected, this property is `nil`.
645 |
646 | ```delphi
647 | procedure Rebuild;
648 | ```
649 | This method rebuilds all internal text elements to get component ready to paint. Call this method if you want to get some calculated property, like TextWidth and TextHeight. Otherwise, you don't need to call this procedure directly.
650 |
651 | ```delphi
652 | procedure BeginUpdate;
653 | ```
654 | Increments internal update semaphore, so while reference counting is bigger than zero, the component will not repaint automatically when the properties are changed, like changing Text or Font property.
655 |
656 | ```delphi
657 | procedure EndUpdate(ForceRepaint: Boolean = True);
658 | ```
659 | Decrements internal update semaphore, so when reference counting is zero, if `ForceRepaint` parameter is True, then the component will repaint the HTML Text.
660 |
661 | *BeginUpdate/EndUpdate example:*
662 | ```delphi
663 | DzHTMLText1.BeginUpdate;
664 | try
665 | DzHTMLText1.Text := 'Text test 1234';
666 | DzHTMLText1.Font.Color := clRed;
667 | DzHTMLText1.Font.Size := 20;
668 | finally
669 | DzHTMLText1.EndUpdate;
670 | end;
671 | ```
672 |
673 | > Do not use `Lines.BeginUpdate/Lines.EndUpdate`. These methods are not controlled by the component.
674 |
675 | ## Link Reference Tag
676 |
677 | There are two ways to use link tag:
678 |
679 | 1. Declaring internal link and the text do display:
680 |
681 | `Open Google Search`
682 |
683 | *This will display: [Open Google Search](http://www.google.com)*
684 |
685 | 2. Just using the display text:
686 |
687 | `www.google.com`
688 |
689 | *This will display: www.google.com*
690 |
691 | > You can use any text as internal link code. Then you can handle this code at *link events*, reading `Link` parameter.
692 |
693 | > Do not use link tags (``, ``, ``) inside a `` tag!
694 |
695 | ## Spoiler Tag
696 |
697 | This tag allows you to create a link and a detail div, where the detail is automatically expanded or collapsed when the mouse clicks on the link.
698 |
699 | To create the spoiler link: `This is the spoiler link text`
700 |
701 | To create the detail div: `This is the detail div that will be expanded when the spoiler link is clicked.`
702 |
703 | The spoiler name is **case insensitive**.
704 |
705 | > You can handle spoiler link at *link events*. It's possible to bypass expand/collapse behavior using `Handled` property.
706 |
707 | > You can use another spoilers inside a spoiler detail div.
708 |
709 | > It's allowed to create multiple links pointing to a single detail div, and it's allowed to create a single link pointing to multiple detail divs.
710 |
711 | > Do not use link tags (``, ``, ``) inside a `` tag!
712 |
713 | ## Link object
714 |
715 | **TDHBaseLink has two child classes possible:**
716 | - TDHLinkRef: It's a link created by `` tag.
717 | - TDHSpoiler: It's a spoiler created by `` tag.
718 |
719 | **Properties:**
720 |
721 | - `Kind: TDHLinkKind` = The link kind (lkLinkRef or lkSpoiler).
722 |
723 | - `LinkRef: TDHLinkRef` = References the TDHLinkRef object when link kind is a `` tag.
724 |
725 | **TDHLinkRef object:**
726 | - `Target: string` = The link target specified at `` tag.
727 | - `Text: TStringBuilder` = The link display text specified at `Display Text` inner text.
728 |
729 | - `Spoiler: TDHSpoiler` = References the TDHSpoiler object when link kind is a `` tag.
730 |
731 | **TDHSpoiler object:**
732 | - `Name: string` = The spoiler name.
733 | - `Expanded: Boolean` = If the spoiler details is expanded.
734 |
735 | **Link events**
736 |
737 | You can retrieve this object using OnLinkClick / OnLinkRightClick / OnLinkEnter / OnLinkLeave events. Also you can call `GetSelectedLink` or reading `LinkRefs` and `Spoilers` lists.
738 |
739 | ## Image Tag
740 |
741 | You can use the tags:
742 |
743 | - `` to show an image of a TImageList component. Just assign the Images property to the ImageList. Then use the `index` parameter to indicate the index of the image in the ImageList component. *In FMX environment, this is only available using Delphi XE8 or higher.*
744 |
745 | - `` to show an image of a resource. Include an image into application resources and then use the `name` parameter to indicate the name of the resource. In VCL environment, the image must be in PNG format. In FMX environment, all Delphi supported images are allowed. **Important: the image will be displayed only at runtime.**
746 |
747 | Example:
748 |
749 | 
750 |
751 | In this example, the image tag should be ``
752 |
753 | ## Div Tag
754 |
755 | 
756 |
757 | Syntax of the image above:
758 |
759 | ```html
760 | Some text inside a div
768 | ```
769 |
770 | The component is based in Div areas. This mean the main area of component is a Div, and you can insert sub divs, and another divs inside divs, and so on. The div tag allows you to work with alignment, colors, borders, margin, and you can even make a table using multiple divs.
771 |
772 | The div tag may be floating, using specific X and Y position, or docked to the current text, when not specifying any position.
773 |
774 | Please, refer to all possible parameters in [Available tags](#available-tags).
775 |
776 | ## Tab Tag
777 |
778 | There are two **tab** tags you can use:
779 |
780 | - `