-
Notifications
You must be signed in to change notification settings - Fork 104
Mentions APIs
Mentions supports a large number of APIs and options.
HKWMentionsPlugin comes with a number of factory methods and configuration options. A discussion of what the various options means follows.
HKWMentionsChooserPositionMode is an enum describing the positioning of the chooser view. There are two main categories of options:
-
Enclosedplaces the chooser view completely within the bounds of the text view. (EnclosedTopleaves a gap at the top of the text view where user input occurs;EnclosedBottomleaves a gap at the bottom.) -
Customallows your app to specify the exact position, size, and constraints on the chooser view.
If you choose an 'enclosed' positioning, the plug-in handles sizing and placing the chooser view; no further effort is required.
If you choose a custom positioning, you must call setChooserTopLevelView:attachmentBlock:. Call this method after you've registered the plug-in to the text view, but before any mentions are created (in practice, you will usually call this method during setup). The top level view serves as the superview for the chooser view when it is created and attached. The attachment block takes in an argument representing the chooser view, and within it you can resize and reposition the chooser view and set up any layout constraints.
Some factories take in a controlCharacterSet argument. This is an NSCharacterSet containing any characters which should be treated as control characters for the purpose of starting explicit mentions. Note that the plug-in may not function correctly if set to use whitespace, newlines, or other such characters as control characters.
This argument can be set to nil or the empty character set if you don't wish to enable explicit mentions.
Some factories take in a searchLength argument. This is the number of consecutive non-whitespace or newline characters that must be entered before an implicit mention is started. Note that setting this argument to 1 or 2 may adversely affect your app's performance.
This argument can be set to 0 or a negative number if you don't wish to enable implicit mentions.
Some factories take in UIColor arguments. The unselectedColor attribute is a color used to style mentions text that is 'unselected' (user cursor is not within the mention string). selectedColor and selectedBackgroundColor are colors used to style mentions text that is selected.
Some factories take in dictionaries of attributes. unselectedAttributes is a dictionary of attributes used to style mentions text that is unselected. selectedAttributes is a dictionary of attributes used to style mentions text that is selected.
The resumeMentionsCreationEnabled property can be set to YES to allow mentions creation to continue if editing in the text view is stopped while the chooser view was up, and then later resumed.
delegate is a delegate object conforming to HKWMentionsDelegate that must be set for the plug-in to function correctly.
stateChangeDelegate is an optional delegate object conforming to HKWMentionsStateChangeDelegate. This delegate allows your application to know when the state of the mentions plug-in changes, as well as when the chooser view is activated or deactivated, allowing you to perform additional UI adjustments or other tasks.
mentions returns an array of HKWMentionsAttribute objects corresponding to the mentions within the text view's current text. Each object contains both information about the mentions entity as well as a NSRange describing its position within the text.
addMention: allows the host application to add a mention programmatically to the text view's text. In order for this to work, the mention must be configured properly: the mention object's range must be valid, the length of the range must match the length of the mentionText property, and the text at the range in the text view must equal mentionText. Calling this method with an improperly configured mention object is a no-op.
addMentions: calls addMention: on an array of mentions objects.
mentionsAttributesInAttributedString: returns an array of mentions objects extracted from an NSAttributedString. This array is suitable for passing directly into the addMentions: method. These APIs are intended primarily for cases in which mentions-enabled text must be saved and restored.
chooserViewClass can be used to specify a completely bespoke chooser view to use instead of the included chooser view. Any chooser view class must be a UIView subclass and conform to HKWChooserViewProtocol. If you don't want to use a custom chooser view, leave this property alone or set it to nil.