XUITagCanvas
Inherits DesktopTextInputCanvas
Implements XUINotificationListener
Description
XUITagCanvas is a really useful, highly customisable and good looking UI control for accepting and
presenting "tags".
You will most likely have seen examples of this type of control in the address field of email clients or perhaps in the search fields of applications such as the Finder on macOS.
The XUITagCanvas is a fully functioning DesktopTextInputCanvas subclass so you can type freely
into it.
The control supports autocompletion of tags using a flexible "parselet" system. What does this mean?
Well, let's say you want to replicate the functionality commonly seen in the "To:" field of an email
client (where if the user types a valid email address a tag is created or if the user types a known
contact's name into the field a tag is created). This is natively supported with the included
XUIEmailTagParselet and an example is provided in the demo app of how easy this is to implement.
Properties
Methods
| Name | Parameters | Returns |
|---|---|---|
| AcceptCurrentAutocompleteOption | ||
| AddTag | tag As XUITag |
|
| CaretBlinkerAction | caretBlinker As Timer |
|
| Clear | ||
| ComputeBufferWidth | ||
| Constructor | ||
| FetchAutocompleteData | ||
| HandleDeleteBackwards | ||
| HandleEscKey | ||
| HideAutocompletePopup | shouldSetFocus As Boolean |
|
| InsertCharacter | char As String, range As TextRange |
|
| InsertString | s As String |
|
| IsTrigger | char As String |
Boolean |
| LineWidth | line As XUITagCanvasLine |
Double |
| MaxVisibleLines | lineHeight As Double |
Integer |
| NotificationReceived | n As XUINotification |
|
| PaintCaret | g As Graphics |
|
| Parse | Boolean |
|
| RebuildBuffer | ||
| RegisterForNotifications | ||
| RemoveTagInstance | tag As XUITag |
|
| ScrollDown | linesToScroll As Integer |
|
| ScrollToCaret | ||
| ScrollUp | linesToScroll As Integer |
|
| ShowAutocompletePopup | ||
| TagAtXY | x As Integer, y As Integer |
XUITag |
| UpdateLayout | ||
| XYAtCaretPos | x As Double, y As Double |
Events
| Name | Parameters | Returns |
|---|---|---|
| AddedTag | tag As XUITag |
|
| AutocompleteDataForPrefix | prefix As String |
XUITagAutocompleteData |
| ClickedTag | tag As XUITag, isContextualClick As Boolean |
|
| Opening | ||
| RemovedTag | tag As XUITag, viaWidget As Boolean |
Constants
| Name | Type |
|---|---|
| LEFT_PADDING | Double |
| LEFT_SCROLL_PADDING | Double |
| POPUP_PADDING | Double |
| RIGHT_SCROLL_PADDING | Double |
| TYPING_SPEED_TICKS | Double |
| UNDO_EVENT_BLOCK_SECONDS | Double |
| VSCROLL_SENSITIVITY | Double |
LEFT_PADDING As Double The number of pixels to pad content from the left edge of the canvas.
LEFT_SCROLL_PADDING As Double The number of pixels to pad left when scrolling leftwards.
POPUP_PADDING As Double The number of pixels between the autocomplete popup and the edge of the canvas.
RIGHT_SCROLL_PADDING As Double Fudge factor for padding the right of lines when horizontal scrolling.
TYPING_SPEED_TICKS As Double The number of ticks between keystrokes to still be considered as actively typing.
UNDO_EVENT_BLOCK_SECONDS As Double The number of seconds within which undoable action will be grouped together as a single undoable action.
VSCROLL_SENSITIVITY As Double Higher number = more lines scrolled when quickly scrolling vertically. Values between 1 - 3 work well.
Property Descriptions
AllowAutocomplete As Boolean
True if the tag canvas supports autocomplete.
AutocompleteData As XUITagAutocompleteData
The autocomplete options for the unparsed text. May be Nil.
CaretBlinkPeriod As Integer
The interval (in ms) between caret blinks.
CaretLineNumber As Integer
The number of the line the caret is currently on.
CaretXCoordinate As Integer
The absolute X coordinate of the caret at its current position (computed and expensive).
CurrentLine As XUITagCanvasLine
The line that the caret is currently on.
HasBorder As Boolean
True if a border should be drawn around the control.
HasFocus As Boolean
Returns True if this tag canvas currently has the focus.
LineHeight As Integer
The height (in pixels) of a line.
mAutocompletePopup As XUITagCanvasAutocompletePopup
This tag canvas' autocomplete popup control.
mBuffer As Picture
The buffer we draw the contents to and then blit to the screen each frame.
mCaretBlinker As Timer
The timer responsible for blinking the caret.
mCaretVisible As Boolean
True if the caret has blinked visible, False if not.
mCurrentLine As XUITagCanvasLine
Backing field for the CurrentLine computed property.
mHasBorder As Boolean
True if a border should be drawn around the control.
mHasFocus As Boolean
Backing field for the HasFocus computed property.
MinimumAutocompletionLength As Integer
The minimum number of characters required before autocompletion is offered. Must be >= 2.
mLastClickWasContextual As Boolean
True if the mouse click that just occurred in the MouseDown event was a contextual click.
mLastPaintHeight As Integer
The height of the canvas at the beginning of the last Paint event.
mLastPaintWidth As Integer
The width of the canvas at the beginning of the last Paint event.
mLineHeight As Double
Internal cache of the current line height.
mLines() As XUITagCanvasLine
The lines in this canvas.
mMinimumAutocompletionLength As Integer
The minimum number of characters required before autocompletion is offered. Backs the MinimumAutocompletionLength computed property.
mReadOnly As Boolean
Backing store for the ReadOnly computed property.
mRequiredBufferWidth As Integer
The width the buffer should be. Set in ComputeBufferWidth.
mScrollPosX As Integer
The horizontal scroll offset. 0 is baseline. Positive indicates scrolling to the right. Backs the ScrollPosX computed property.
mScrollPosY As Integer
The vetical scroll offset. 0 is baseline. Positive indicates scrolling down. Backs the ScrollPosY computed property.
mStyle As XUITagCanvasStyle
The colour style to use for the tag canvas and tags.
mSuppressAutocompletePopup As Boolean
If True then the autocomplete popup is suppressed even if there is autocomplete data available. Set after the user has cancelled autocomplete.
mTriggers() As String
Additional characters that trigger tag parsing. Set with the ParseTriggers computed property.
Multiline As Boolean
If True then tags will wrap to new lines.
Parselet As XUITagParselet
The parselet to use to parse text entered in the tag canvas.
ParseOnComma As Boolean
If True then the comma key triggers the parsing of any contiguous text not yet parsed as a tag.
ParseOnReturn As Boolean
If True then the return key triggers the parsing of any contiguous text not yet parsed as a tag.
ParseOnTab As Boolean
If True then the tag key triggers the parsing of any contiguous text not yet parsed as a tag.
ParseTriggers As String
A comma delimited list of characters that will trigger tag parsing. Return, tab and comma characters are stipulated by the ParseOn... properties.
ReadOnly As Boolean
If True then the canvas is read-only (i.e. not editable).
Renderer As XUITagCanvasRenderer
The renderer to use to draw the tags in the canvas.
ScrollPosX As Integer
The horizontal scroll offset. 0 is baseline. Positive indicates scrolling to the right. Refreshes the canvas.
ScrollPosY As Integer
The vertical scroll offset. 0 is baseline. Positive indicates scrolling down. Refreshes the canvas.
Style As XUITagCanvasStyle
The colour style to use for the tag canvas and tags.
TagsHaveWidget As Boolean
If True then tags will be drawn with a clickable dingus.
Method Descriptions
AcceptCurrentAutocompleteOption()
Accepts the currently selected option in the autocomplete popup.
AddTag(tag As XUITag)
Adds tag to the end of the current line, clearing any unparsed text. Refreshes the canvas.
CaretBlinkerAction(caretBlinker As Timer)
Toggles the visibility of the caret. Called by mCaretBlinker.Action.
Clear()
Clears the contents of the tag canvas.
ComputeBufferWidth()
Computes the width of the buffer. Sets mRequiredBufferWidth.
The buffer will always be at least as wide as the tag canvas' current width.
Constructor()
Default constructor.
FetchAutocompleteData()
Requests autocomplete data for the unparsed text immediately in front of the caret.
HandleDeleteBackwards()
Deletes the character or tag immediately in front of the caret.
HandleEscKey()
Handles the pressing of the Esc key.
HideAutocompletePopup(shouldSetFocus As Boolean)
Hides the autocomplete popup.
InsertCharacter(char As String, range As TextRange)
Inserts a single character at the current caret position.
Assumes char is only one character.
InsertString(s As String)
Inserts text of arbitrary length at the current caret position.
IsTrigger(char As String) As Boolean
True if char is a trigger character.
LineWidth(line As XUITagCanvasLine) As Double
Returns the total width of the specified line (including its contents and all padding).
MaxVisibleLines(lineHeight As Double) As Integer
The maximum number of lines that are visible in the canvas.
Will never be more than the maximum number of lines in existence.
NotificationReceived(n As XUINotification)
A notification has been received from the Notification Center.
Part of the XUINotificationListener interface.
PaintCaret(g As Graphics)
Paints the caret at the end of the current line.
Parse() As Boolean
Attempts to parse the unparsed text on the current line into a tag. Returns False if unable. Refreshes the canvas if successful.
RebuildBuffer()
Rebuilds the entire buffer by drawing all visible content to it.
RegisterForNotifications()
Registers the canvas for desired notifications.
RemoveTagInstance(tag As XUITag)
Removes tag from the tag canvas. Refreshes the canvas but does not raise the RemovedTag event.
ScrollDown(linesToScroll As Integer)
Scrolls the canvas down linesToScroll lines. Refreshes the canvas.
ScrollToCaret()
Scrolls the canvas (if necessary) to the caret. Refreshes the canvas.
ScrollUp(linesToScroll As Integer)
Scrolls the canvas up linesToScroll lines. Refreshes the canvas.
ShowAutocompletePopup()
Shows the autocomplete popup at the caret position.
TagAtXY(x As Integer, y As Integer) As XUITag
Returns the tag at (x, y) or Nil if there isn't one.
UpdateLayout()
This method forces a deep redraw of all tags, re-computing the line they should be on. Does not refresh the canvas.
Expensive but is called whenever the canvas is resized.
XYAtCaretPos(x As Double, y As Double)
Computes (ByRef) the canvas x, y coordinates at the current caret position.
y is the top of the caret.
Event Descriptions
AddedTag(tag As XUITag)
Added tag to the tag canvas.
AutocompleteDataForPrefix(prefix As String) As XUITagAutocompleteData
The tag canvas is asking for autocompletion options for the specified prefix. You should return Nil if there are none.
ClickedTag(tag As XUITag, isContextualClick As Boolean) A tag has been clicked.
Opening() The control is opening.
RemovedTag(tag As XUITag, viaWidget As Boolean)
A tag has been removed from the tag canvas. If viaDingus is True then the tag was removed because the dingus was clicked.