PWStyleHTMLField class The PWStyleHTMLField class has a number of events and methods that are publicly exposed so that you can incorporate them in a REALbasic/REALStudio project. Methods and Functions AddLinkRef: Parameters: ref As PWLinkRef. You can use this method to pass in your own link info for rendering in HTML. It is mostly practical for situations where you are not entering your text directly in the PWStyleHTMLField instance (i.e., when copying styled text from another control). ClearAllLinks: No parameters. Removes all links that have been added to the PWStyleHTMLField instance, and resets all text formatted in link style to plain text. GetFontMap: No parameters. Returns: A dictionary that maps a font name (as dictionary entry key) to a font list (as the entry's value). This map is used when the HTML is created to output font lists for non-base font styles. You can use the HTMLFldExtensions.MapFontListToFont method to set up font mapping. HasLink: Parameters: linkText As String Returns: A Boolean representing whether there is a link for the linkText parameter passed in. You can use this function to determine whether or not to allow creating a new link for selected text. PWStyleHTMLField allows only one link for any unique link text. You should ensure that any link’s text is used only once in the document. HTML: No parameters. Returns: A string with the complete page of raw HTML for the styled text in the PWStyleHTMLField instance. HTMLEmailMessage: No parameters. Returns: An EmailMessage instance with its BodyHTML property set to the raw HTML you would get from using the GetHTML function and adjusting it for HTML email's requirements. In addition, the EmailMessage instance's BodyPlainText property is set to a Quoted-Printable-encoded rendition of the field text. If you set the field's DisplayLinkDestinationInPlainText property to true, PWStyleHTMLField inserts the destination for each link in the field within parentheses, after each link text instance, in the BodyPlainText. HTMLEntities: No parameters. Returns: A dictionary of the non-ASCII characters that PWStyleHTMLField escapes for email messages. The dictionary's keys are the characters to be encoded, and the values are the HTML entity equivalents for each character. Any changes you make to this dictionary will be stored in the class instance. HTML encoding is only performed on the HTML portion of email messages created with the HTMLEmailMessage function. IsLinkStyle: No parameters. Returns: A Boolean representing whether the cursor is within text formatted in PWStyleHTMLField class's link style. It is not guaranteed to be a valid link, but in most cases it should be. You can use this to block typing in a link to prevent problems with breaking links. LinkDictionary: No parameters. Returns: A dictionary containing all links in the document, represented as instances of PWLinkRef. Keys for the dictionary are the link text for each link (i.e. the unique page text that appears formatted as a link). You can use these link references to save links for the page. MakeLinkFromSelection: Parameters: url As String. Use this method to create a link to the provided URL. If it successfully creates the link, PWStyleHTMLField sets the selected text to a pre-defined link style: bold, underlined in blue (&c000FF). PageTitle: No parameters. Returns: A string representing the page title set with the SetPageTitle method. PlainTextWithConvertedLinks: Parameters: s As String. Returns: A string with any link URLs in the string passed via the parameter "s" converted to a plain-text version composed of the link text followed by the link’s URL in parentheses. Typically you would pass in the text of the PWStyleHTMLField instance, but you can pre-process it if you like. ProtectLinks: Parameter: doProtect As Boolean. Toggles the PWStyledHTMLField instance’s link protection. Link protection is on by default, protecting link text from being invalidated by inserting or deleting text, or changing its style. It can cause a slowdown in text operations, so this method allows you to turn it off or back on. In order for link protection to work, you must use the SetStyle method to set link styles and colors. RemoveLink: Parameters: linkText As String. Use this method to remove a link added with MakeLinkFromSelection for the link text passed in. If the link is successfully removed, PWStyleHTMLField sets the link text to plain style. SelectFullLink: No parameters. If the cursor is within a link this method selects the entire link text. SelLink: No parameters. Returns: A string with the URL for a selection with a selection. If the selection is not within a link, returns an empty string. SetBGColor: Parameter: A color to set as the background color for the page. SetBGImage: Parameter: ImageURL As String, an URL to a background image for the page. This should be an URL to an image file that can be downloaded when the page or email is viewed. It's particularly important for emails that this be an absolute URL. SetBodyFont: Parameter: fontList As String. Lets you set a text font for the HTML body, which serves as the base font for the document. This can be different than the font the PWStyleHTMLField instance is set to. The fontList parameter can be a comma-delimited list of font or family names, allowing you to CSS-style font specifier such as "Helvetica, Arial, Sans-Serif". The PWStyleHTMLField sets the body text size to the same value as the field's TextSize property, measured in pixels. For example, if the field's TextSize is set to 10 points, the body text size is set to 10 pixels. Likewise, if you were to change a line's text size to 14 points, it would be formatted in HTML as 14 pixels. SetFontMap: Parameter: fontMap As Dictionary, a dictionary mapping font names (as dictionary entry key) to a font list (as the entry's value). This map is used when the HTML is created to output font lists for non-base font styles. You can use the HTMLFldExtensions.MapFontListToFont method to set up font mapping. SetLinkStyleAttributes: Parameters: linkColor As Color = &c0000FF, bold As Boolean = True, underline As Boolean = True, UseCustomLinkInHTML As Boolean = False. Lets you set the Color, Bold and Underline attributes of rendered HTML links with the first three parameters. These settings always affect the appearance of link text in the editing control. The final parameter tells your PWStyleHTMLField instance whether to render HTML using the same style. If you want links to appear in their default style when displayed as HTML, leave the last parameter off or set to False. Otherwise, you must add the final parameter with a value of True. SetModified: Parameter: how As String. This method should be called if you are using Undo functionality and alter the state of the PWHTMLField instance, but not if you let the PWHTMLField make the change. For example, if you call SourceFld.SelBold = True, you need to call SetModified to inform the Undo system that a change in state occurred. If you instead use the PWStyleHTMLField's SetStyle method to set the selected text's to bold, you should not call SetModified as the change in state will already have been recorded. The how parameter provides the term that will appear in the Undo and Redo menus for whatever action was performed. SetPlain: No parameters. Returns: A Boolean indicating success of the operation. You can call this function to set the selected text in a PWStyleHTML field instance to plain text (base font and size with no style formating). SetPageTitle: Parameters: title As String. Lets you specify a page title. SetStyle: Parameters: styleName As String, apply As Variant. Returns: Boolean representing whether or not the operation was completed. This function executes the style change on the selected text, unless there is text formatted as a link within the selection. This prevents changes to text that would invalidate the link. It works in conjunction with link protection (see ProtectLinks above) to safely change text styles. If it encounters link text in the selection it beeps and returns false. (Unless the requested change is to alter the text's Italic state, which does not invalidate the link.) The styleName parameter must be one of "Bold", "Italic", "Underline", or "TextColor". The apply parameter should be True or False for any of the first three variations of styleName. It should be a color that you want to set the text color to for the textColor styleName variation. Events AboutToRenderHTML: No parameters. This event fires after the PWStyleHTMLField instance has been initialized, but before it goes through the process of converting styled text to HTML. This is your last chance to call any of the built-in methods or functions before rendering. EditSource: Parameters: source As String. Returns: Boolean. This is a powerful feature added to version 2.0.2. It allows you to access the HTML source that is about to be rendered, and change it as you see fit. This means you can easily enhance a PWStyleHTMLField instance with your own extra features (see the demo project's CSS Demo as a simple example). Likewise, you can easily abuse this capability and alter the source in such a way that it doesn't render. So be careful when using this feature. NOTE: This returns the same text that the HTML event does. You may find this event makes it easier to create a subclass. To edit the HTML source, make your changes to the source as needed, and return True from the event handler. PWStyleHTMLField will not act on your changes if you do not return True. LinkWasSet: No parameters. Alerts you when a link has been set so that you can follow up as desired. LinkWasSet: No parameters. Alerts you when a link has been set so that you can follow up as desired. Open: No parameters. Extends the PWStyleHTMLField class's Open event handler, giving you an opportunity to set up fonts and the page title if desired. SelChange: Parameters: isLinkStyle As Boolean. Extends PWStyleHTMLField class's SelChange event handler with a parameter that tells you whether or not the cursor is within a link. You can use this in conjunction with the SelLink method to display a URL for the link. Constants kCurrentVersion: A string value representing the version of PWStyleHTMLField you're using. Properties Note: As of version 2.0.2, these properties are exposed in the IDE's Properties pane. AlwaysEncode: Boolean. Tells PWStyleHTMLField to apply HTMLEncoding to output obtained from the HTML function. HTMLEmailMessage.BodyHTML is already HTML-encoded. DisableBackgroundTasks: Boolean. Turns the DisableBackgroundTasks pragma on or off in methods and functions with loops. Setting it to True makes operation speedier but makes your application's user interface less responsive. DisplayLinkDestinationInPlainText: Boolean. Lets you set whether or not the PWStyleHTMLField instance should add link destinations in parentheses after link text in the BodyPlainText of the EmailMessage returned by the HTMLEmailMessage function. EncodeSpaces: Boolean. Tells PWStyleHTMLField to encode spaces as their HTML entity  so that they'll be displayed in the output (HTML strips plain spaces). It only encodes spaces when there is more than one in a row or it comes after a Return character. ListDelimiter: String. Please see the Handling Lists section of the documentation for a complete explanation. TableWidth: Integer. Lets you define a width for a table that contains your page content. PWStyleHTMLField uses the value you specify as a percentage in the HTML source. The default is 98 (i.e. 98%). If you set the value to 0 the table is omitted. This value only applies to HTML derived via the HTML function. BodyTextHTML of the EmailMessage instance returned by the HTMLEmail function is always placed within a table whose width value is set to the default, 98%. TabSpaces: Integer. Lets you define the number of spaces to replace Tab characters with in the output. There is no Tab character defined in HTML, so PWStyleHTMLField uses a series of spaces to replace Tab characters. The default value is 4. You must have the PWStyleHTMLField instance's AcceptTabs property set to True in order for users to be able to enter tabs. UseWindowsAlignmentWorkaround: Boolean. Tells PWStyleHTMLField to pre-process the field's RTFData when running in Windows to produce alignment data that is omitted in Windows. This property is set to True by default. Setting it to False will break text alignment in Windows in most cases, but would eliminate the extra processing required. If this bug is fixed in a future version of Real Studio, setting it to False would allow you to safely eliminate the extra processing. |