Table of Contents
Requirements
| Operating System | Information |
|---|---|
| MacOS | 10.10.5 or above |
| Windows | WebKit Renderer |
Enumerations
| Name | Values |
|---|---|
| ToolbarItems | SectionFont |
| SectionDecoration | |
| SectionColor | |
| SectionScript | |
| SectionBlock | |
| SectionList | |
| SectionIndent | |
| SectionPosition | |
| SectionInsert | |
| SectionClean | |
| SectionCustom | |
| MenuFontName | |
| MenuFontSize | |
| MenuColor | |
| MenuBackground | |
| ButtonBold | |
| ButtonItalic | |
| ButtonUnderline | |
| ButtonStrike | |
| ButtonSubscript | |
| ButtonSuperscript | |
| ButtonHeader1 | |
| ButtonHeader2 | |
| ButtonQuote | |
| ButtonCode | |
| ButtonListOrdered | |
| ButtonListUnordered | |
| ButtonListCheck | |
| ButtonIndent | |
| ButtonOutdent | |
| ButtonDirection | |
| ButtonAlignLeft | |
| ButtonAlignRight | |
| ButtonAlignCenter | |
| ButtonHorizontalRule | |
| ButtonLink | |
| ButtonImage | |
| ButtonVideo | |
| ButtonClean | |
| ButtonCustom |
Constants
| Name | Type | Value | Description |
|---|---|---|---|
| AlignLeft | Integer | 0 | Left alignment of text. |
| AlignCenter | Integer | 1 | Center alignment of text. |
| AlignRight | Integer | 2 | Right alignment of text. |
| HeaderNone | Integer | 0 | No header tag. |
| Header1 | Integer | 1 | Corresponds to <H1> |
| Header2 | Integer | 2 | Corresponds to <H2> |
| Header3 | Integer | 2 | Corresponds to <H3> |
| Header4 | Integer | 2 | Corresponds to <H4> |
| jsTwitter_Preview | String | Script Tag | Script tag to enable Twitter previews in your generated documents. |
Events
| Definition | Description |
|---|---|
| ContextClick( X as Integer, Y as Integer ) | Raised when the user right-clicks the editor area. |
| EditorDefaults( byRef DefaultFontFace as String, _ byRef DefaultFontSize as Integer, _ byRef allowNesting as Boolean, _\\lineHeight as Double ) | Raised during initialization to set font defaults for the editor. allowNesting controls whether lists can be nested. |
| FontsImport() as String | Raised when the editor is preparing to display, allowing you to supply <link> tags to Google or other web-based fonts. |
| FontsInitialize( byRef CurrentFonts() as String, allowedLineHeights() as Double ) | Raised when the editor is preparing to display, giving you the opportunity to add or remove fonts. |
| KeyPress( keyChar as String, _ AltKey as Boolean, _ CtrlKey as Boolean, _ MetaKey as Boolean, _ ShiftKey as Boolean) | Raised when the user presses a key or key combination. |
| LinkPreview( URL as String ) as Boolean | Fired when the user clicks the “Preview” link when selecting a link in the text. Return True to indicate that the event has been handled. |
| MenuClear() as Boolean | This event is fired when the user has selected Clear from the edit menu. Return True to override default. |
| MenuCopy() as Boolean | Fired when user selects Copy from the edit menu. Return True to override default. |
| MenuCut() as Boolean | Fired when user selects Cut from the edit menu. Return True to override default. |
| MenuPaste() as Boolean | Fired when user selects Paste from the edit menu. Return True to override default. |
| MenuRedo() as Boolean | Fired when user selects Redo from the edit menu. Return True to override default. |
| MenuSelectAll() as Boolean | Fired when user selects Select All from the edit menu. Return True to override default. |
| MenuUndo() as Boolean | Fired when user selects Undo from the edit menu. Return True to override default. |
| MouseWheel( X as Integer, _ Y as Integer, _ deltaX as Integer, _ deltaY as Integer ) | Raised when the user attempts to scroll the component's display area using the mouse wheel. |
| SelChange() | Fired when the user changes the current selection in the editor. |
| TextChanged | This event triggers when the text changes. |
| Toolbar_BackgroundClick() | Fired when the user clicks the Background Color button on the toolbar. |
| Toolbar_ButtonClick(buttonID as String | Fired when the user clicks a custom button on the toolbar. |
| Toolbar_ColorClick() | Fired when the user clicks the Foreground Color button on the toolbar. |
| Toolbar_ImageClick() | Fired when the user clicks the Insert Image button on the toolbar. |
| Toolbar_InsertTableClick() | Fired when the user clicks the Insert Table button on the toolbar. |
| Toolbar_LinkClick() | Fired when the user clicks the Insert Link button on the toolbar. |
| Toolbar_VideoClick() | Fired when the user clicks the Insert Video button on the toolbar. |
| UIReady() | Raised when loading has completed. |
Methods
| Definition | Description |
|---|---|
| AddHashTag(HashValue as String) | Adds a new hashtag. |
| AddHashTags(Values() as String) | Appends the contents of Values to the current HashTags. |
| AddMention(MentionValue as String) | Adds a new mention. |
| AddMentions(Values() as String) | Appends the contents of Values to the current Mentions. |
| ClearUndoHistory() | Clears the Undo/Redo stack. |
| Copy() | Copies the currently selected text to the clipboard. |
| CurrentLine() as Integer | Current line containing the cursor relative to PlainText. |
| Cut() | Copies the currently selected text to the clipboard, then removes it from the editor. |
| Delete() | Deletes the currently selected text from the editor. This has the same effect as GraffitiHTMLEditor.SelText = "" |
| ExportCSS() as String | Returns a string containing all CSS styles that could not be made inline. |
| ForceUpdate() | Forces the instance to update the Selection, Content, and Format properties from the display. |
| HashTag(tagID as Integer) as String | Returns the HashTag at the specified index. |
| HashTagCount() as Integer | Returns the total number of HashTags (UBOUND + 1). |
| InsertAudio(SourceURL as String) | Inserts an audio player element. Note that the element will not be usable in the editor. |
| InsertDeltas( theDelta as JSONItem ) | (Advanced Use Only) Allows the insertion of QuillJS deltas directly in to the editor instance. |
| InsertFile(f as FolderItem, optional atPosition as Integer) | If F points to an image file, the image is inserted via a call to InsertImage, otherwise a link is inserted in to the document using the local URL path type. |
| InsertHorizontalRule() | Inserts a Horizontal Rule in to the document. |
| InsertHTML( htmlString as String ) | Inserts the specified HTML at current selection. |
| InsertImage(URL as String, _ altText as String = “”, _ atPos as Integer = 0, _ imageWidth as Integer = -1, _ imageHeight as Integer = -1, _ hasAlt as Boolean = False) | Insert an image into the content area. atPosition is optional, and if omitted the current cursor location will be used as an insertion point. Note that if you insert an image on the internet your application will attempt to connect to the internet. |
| InsertImage(f as FolderItem, _ altText as String = “”, _ atPos as Integer = 0, _ imageWidth as Integer = -1, _ imageHeight as Integer = -1, _ hasAlt as Boolean = False) |
|
| InsertLineBreak() | Inserts a soft carriage return at the specified position. |
| InsertLink(url as String, title as String = “”, atPosition as Integer = 0) | Inserts a link into the content area. atPosition is optional, and if omitted the current cursor location will be used as an insertion point. |
| InsertTable(Rows as Integer, Columns as Integer) | Inserts a table in to the document. |
| InsertTableColumn() | Adds a column to the current table. |
| InsertTableRow() | Adds a row to the current table. |
| InsertVideo(URL as String) | Inserts a video element in to the document. |
| LoaderHide() | Hides the loading spinner. |
| LoaderShow() | Shows a loading spinner that covers the entire component. |
| Mention(mentionID as Integer) | Returns the value of the mention at the specified index. |
| MentionCount() as Integer | Returns the total number of current mentions (UBOUND + 1). |
| Paste() | Pastes the current clipboard text at the currently selected area of the editor. Note that if there is text selected, this will replace that selected text. |
| Redo() | Steps forward in the change stack, if a change has previously been undone. |
| RemoveAllHashTags() | Removes all HashTags. |
| RemoveAllMentions() | Removes all Mentions. |
| RemoveHashTag(tagID as Integer) | Removes the HashTag at the specified index. |
| RemoveMention(mentionID as Integer) | Removes the Mention at the specified index. |
| SelectAll() | Select all contents. |
| ToolbarAddButton(ButtonID as String, ButtonCaption as String, ButtonTooltip as String = “”) | Adds a custom button to the toolbar, in the Custom section. |
| ToolbarItemVisible(ParamArray theItem as ToolbarItems, assigns value as Boolean) | Sets the visibility of one or more toolbar buttons. |
| ToolbarItemVisible_Custom(CustomID as String, Value as Boolean) | Sets the visibility of a custom button in the toolbar. |
| ToolbarRemoveButton(ButtonID as String) | Removes a custom button from the toolbar. |
| ToolbarTooltip(theItem as ToolbarItems, theTooltip as String, CustomButtonID as String = “” | Sets the tooltip of a toolbar item. |
| toPage(pageTitle as String, includeStyleBlock as Boolean = False, additionalCSS as String = “”) as String | Creates a standalone HTML page from the content. |
| Undo() | Steps backward in the change stack to remove a previous change. |
Properties
| Name | Type | Default Value | Description |
|---|---|---|---|
| AutoHeight | Boolean | False | When True, the component will automatically alter its height to fit the contents. |
CanRedo Read-Only | Boolean | False | Whether Redo is currently available. |
CanUndo Read-Only | Boolean | False | Whether Undo is currently available. |
| DarkMode | Boolean | False | When True, the control is restyled to more closely match the new OS dark modes. |
| EditorBackground | Color | &cFFFFFF | Controls the background color of the entire editor (not toolbar). |
| Enabled | Boolean | True | Whether or not the edit field is enabled. Due to current limitations one cannot disable the rich text toolbar, however formatting conditions may not be changed by the user while enabled is false. |
| EnforceHTTPS | Boolean | True | When True, URls will be automatically converted to HTTPS. |
| HTML | String | “” | Get and set the HTML contents. |
| IsDirty | Boolean | False | When True, the component is still waiting for a data update and the Xojo property values may not match the actual values. |
| Length | Integer | 0 | The number of characters in the editor. |
| MaximumHeight | Integer | 1000 | Maximum height to allow when AutoHeight = True. |
| MinimumHeight | Integer | 100 | Minimum height to allow when AutoHeight = True. |
| PlainText | String | “” | The current content of the editor with all HTML removed. |
| SelAlign | Integer | AlignLeft | Current alignment of text within the editor. |
| SelBold | Boolean | False | Get and set the bold property for currently selected text. If any portion of the selected text is bold this will return true. |
| SelFont | String | System | Text font of the currently selected text. |
| SelHeader | Integer | HeaderNone | Header style of currently selected text. |
| SelItalic | Boolean | False | Get and set the italic property for currently selected text. If any portion of the selected text is italic this will return true. |
| SelLength | Integer | 0 | The number of highlighted characters. |
| SelLineHeight | Double | 1.5 | Sets the line-height applied to the current block element in EM CSS length units. IE: 1.5 = 1.5em |
| SelLink | Boolean | False | Returns True when the user has selected all or part of a link. |
| SelLinkURL | String | “” | Returns the currently selected link's URL. |
| SelListChecked | Boolean | False | Determines if current selection is a checked list. |
| SelListOrdered | Boolean | False | Determines if current selection is an ordered list. |
| SelListUnordered | Boolean | False | Determines if current selection is an ordered list. |
| SelPlain | Boolean | False | If true the selected text is all plain. When setting it will make all selected text plain (unformatted) |
| SelStart | Integer | 0 | The position of the insertion point. A value of zero is before the first character. |
| SelStrike | Boolean | False | Get and set the strikethrough property for currently selected text. If any portion of the selected text is struck this will return true. |
| SelSubscript | Boolean | False | Subscript setting of current text. |
| SelSuperscript | Boolean | False | Superscript setting of current text. |
| SelTable | Boolean | False | Returns True when the user has selected all or part of a table. |
| SelText | String | “” | The currently highlighted text. Setting this inserts text into the content. |
| SelTextBackground | Color | &cFFFFFF | Get and set the color property for currently selected text's background color. When getting this value the control will return the first color it encounters in the selected text. If no color is encountered, white is returned. |
| SelTextColor | Color | &c000000 | Get and set the color property for currently selected text. When getting this value the control will return the first color it encounters in the selected text. If no color is encountered, black is returned. |
| SelTextSize | Integer | 12 | Get and set the text size in pixels for currently selected text. The pixels limitation is from Quill (I prefer setting things in point.) When getting this value, the control will return the first size change it encounters in the selected text. If no size change is encountered the default font size of 12px is returned. |
| SelUnderline | Boolean | False | Get and set the underline property for currently selected text. If any portion of the selected text is underlined this will return true. |
| ShowLoaderOnEvents | Boolean | False | If true, the loading spinner will be shown to denote that the control is busy when communicating. |
| SpellCheck | Boolean | False | Controls whether the OS/Browser spelling checker is enabled on the editor. |
| ToolbarBackgroundColor | Color | &cFFFFFF | Controls the background color of the toolbar and buttons. |
| ToolbarVisible | Boolean | True | Controls the visibility of the toolbar. |
| UseXHR | Boolean | False | When True, will use XmlHttpRequests to return data rather than length-constrained packets. |
| WordWrap | Boolean | True | If False, content will not wrap lines. |
Examples
Default PushButton
When using GraffitiHTMLEditor with a PushButton that has Default set to True, Xojo will fire the PushButton's action event when pressing Enter or Return in the GraffitiHTMLEditor. To workaround this, at the top of your PushButton's action code, add the following line:
If me.Window.Focus IsA GraffitiHTMLEditor Then Return
Adding Google Fonts
To add Google or other web-based fonts to this component, two things are required:
- The
<link>tag to the specified font - The Name of the font
For this example, we'll be using Roboto from Google.
The first step is to implement the FontsInitialize event. This event has a parameter that contains all fonts currently installed on the system. All we want to do is add Roboto, and we'll make it the first font listed for this example:
Sub FontsInitialize(byRef CurrentFonts() as String) Handles FontsInitialize CurrentFonts.AddAt( 0, "Roboto" ) End Sub
Next we need to implement the FontsImport event to return all of the <link> tags for our additional fonts. I recommend storing these in a constant to avoid dealing with double-and single quotes. I added a constant to my window called kRoboto:
Private Const kRoboto as String = <link rel="preconnect" href="https://fonts.gstatic.com"> <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@100&display=swap" rel="stylesheet">
Finally, we'll return our constant's value in FontsImport:
Function FontsImport() Handles FontsImport as String Return kRoboto End Function
Notes
HTML Formatting
As HTMLEditor is a restricted editor for HTML, some tags will not carry over. As an example, <div> tags are converted to <p> and <span> tags with the styling applied to the new tag.
HTTP Embed Origins on MacOS
With recent changes to Xojo on MacOS, NSAppTransportSecurity is now an issue when embedding images, audio, or video in GraffitiHTMLEditor. To cope with this you can add information to your info.plist to allow either specific hosts to bypass enforcement of the HTTPS protocol requirement or allow all hosts. For more information on this, please review this page in the Xojo Documentation.
As of R29 the property EnforceHTTPS as Boolean = True has been added to aid in coping with this. When True any resource URI (with the exception of data, file, ftp, or smb) that a user attempts to embed will be required to use HTTPS by replacing the protocol identifier (HTTP becomes HTTPS).