Struct IMKInputController

#[repr(C)]
pub struct IMKInputController { /* private fields */ }

Available on crate feature IMKInputController only.

The basic class that controls input on the input method side.

IMKInputController implements fully implements the protocols defined above. Typically a developer does not override this class, but provides a delegate object that implements the methods that developer is interested in. The IMKInputController versions of the protocol methods check if the delegate object implements a method, and call the delegate version if it exists.

The IMKServer class which is allocated in an input method’s main function creates a controller class for each input session created by a client application. Therefore for every input session there is a corresponding IMKInputController.

See also Apple’s documentation

Implementations

impl IMKInputController

pub unsafe fn initWithServer_delegate_client( this: Allocated<Self>, server: Option<&IMKServer>, delegate: Option<&AnyObject>, input_client: Option<&AnyObject>, ) -> Option<Retained<Self>>

Available on crate feature IMKServer only.

Initializes the controller class setting the delegate.

The inputClient parameter is the client side object that will be sending messages to the controller via the IMKServer. The client object always conforms to the IMKTextInput protocol.

Methods in the protocols that are implemented by the delegate object always include a client parameter. Methods in the IMKInputController class do not take a client. This is because the client is stored as an ivar in the IMKInputController.

pub unsafe fn updateComposition(&self)

Called to inform the controller that the composition has changed.

This method will call the protocol method composedString: to obtain the current composition. The current composition will be sent to the client by a call to the method setMarkedText:

pub unsafe fn cancelComposition(&self)

Stops the current composition and replaces marked text with the original text.

Calls the method originalString to obtain the original text and sends that to the client via a call to IMKInputSession protocol method insertText:

pub unsafe fn compositionAttributesAtRange( &self, range: NSRange, ) -> Option<Retained<NSMutableDictionary>>

Called to obtain a dictionary of text attributes.

The default implementation returns an empty dictionary. You should override this method if your input method wants to provide font or glyphInformation. The returned object should be an autoreleased object.

pub unsafe fn selectionRange(&self) -> NSRange

Returns where the selection should be placed inside markedText.

This method is called by updateComposition: to obtain the selection range for markedText. The default implementation sets the selection range at the end of the marked text.

pub unsafe fn replacementRange(&self) -> NSRange

Returns the range in the client document that text should replace.

This method is called by updateComposition to obtain the range in the client’s document where markedText should be placed. The default implementation returns an NSRange whose location and length are NSNotFound. That indicates that the marked text should be placed at the current insertion point. Input methods that wish to insert marked text somewhere other than at the current insertion point should override this method.

An example of an input method that might override this method would be one replaced words with synonyms. That input method would watch for certain words and when one of those words was seen it would be replaced by marked text that was a synonym of the word.

pub unsafe fn markForStyle_atRange( &self, style: NSInteger, range: NSRange, ) -> Option<Retained<NSDictionary>>

Returns a dictionary of text attributes that can be used to mark a range of an attributed string that is going to be sent to a client.

This utility function can be called by input methods to mark each range (i.e. clause ) of marked text. The style parameter should be one of the following values: kTSMHiliteSelectedRawText, kTSMHiliteConvertedText or kTSMHiliteSelectedConvertedText. See AERegistry.h for the definition of these values.

The default implementation begins by calling compositionAttributesAtRange: to obtain extra attributes that an input method wants to include such as font or glyph information. Then the appropriate underline and underline color information is added to the attributes dictionary for the style parameter.

Finally the style value is added as dictionary value. The key for the style value is NSMarkedClauseSegment. The returned object should be an autoreleased object.

pub unsafe fn doCommandBySelector_commandDictionary( &self, a_selector: Option<Sel>, info_dictionary: Option<&NSDictionary>, )

Called to pass commands that are not generated as part of the text input.

The default implementation checks if the controller object (i.e. self) responds to the selector. If that is true the message performSelector:withObject is sent to the controller class. The object parameter in that case is the infoDictionary.

This method is called when a user selects a command item from the text input menu. To support this an input method merely needs to provide actions for each menu item that will be placed in the menu.

i.e. -(void)menuAction:(id)sender

Note that the sender in this instance will be the infoDictionary. The dictionary contains two values:

kIMKCommandMenuItemName NSMenuItem – the NSMenuItem that was selected kIMKCommandClientName id <IMKTextInput , NSObject> - the current client

pub unsafe fn hidePalettes(&self)

Called to inform an input method that any visible UI should be closed.

pub unsafe fn menu(&self, mtm: MainThreadMarker) -> Option<Retained<NSMenu>>

Available on crate feature objc2-app-kit only.

Returns a menu of input method specific commands.

This method is called whenever the menu needs to be drawn so that input methods can update the menu to reflect their current state. The returned NSMenu is an autoreleased object.

pub unsafe fn delegate(&self) -> Option<Retained<AnyObject>>

Returns the input controller’s delegate object. The returned id is an autoreleased object.

pub unsafe fn setDelegate(&self, new_delegate: Option<&AnyObject>)

Set the input controller’s delegate object.

pub unsafe fn server(&self) -> Option<Retained<IMKServer>>

Available on crate feature IMKServer only.

Return the server object which is managing this input controller. The returned IMKServer is an autoreleased object.

pub unsafe fn inputControllerWillClose(&self)

Called to notify an input controller that it is about to be closed.

pub unsafe fn annotationSelected_forCandidate( &self, annotation_string: Option<&NSAttributedString>, candidate_string: Option<&NSAttributedString>, )

Called when a user has selected a annotation in a candidate window.

When a candidate window is displayed and the user selects an annotation the selected annotation is sent to the input controller via this method. The currently selected candidateString is also sent to the input method.

pub unsafe fn candidateSelectionChanged( &self, candidate_string: Option<&NSAttributedString>, )

Informs an input controller that the current candidate selection in the candidate window has changed.

The candidate parameter is the candidate string that the selection changed to. Note this method is called to indicate that the user is moving around in the candidate window. The candidate object is not a final selection.

pub unsafe fn candidateSelected( &self, candidate_string: Option<&NSAttributedString>, )

Called when a new candidate has been finally selected.

The candidate parameter is the users final choice from the candidate window. The candidate window will have been closed before this method is called.

impl IMKInputController

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for IMKInputController

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<IMKInputController> for IMKInputController

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for IMKInputController

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for IMKInputController

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for IMKInputController

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for IMKInputController

const NAME: &'static str = "IMKInputController"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<IMKInputController as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for IMKInputController

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for IMKInputController

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for IMKInputController

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl IMKMouseHandling for IMKInputController

unsafe fn mouseDownOnCharacterIndex_coordinate_withModifier_continueTracking_client( &self, index: NSUInteger, point: NSPoint, flags: NSUInteger, keep_tracking: *mut Bool, sender: Option<&AnyObject>, ) -> bool

where Self: Sized + Message,

Sends a mouseDown to an input method.

unsafe fn mouseUpOnCharacterIndex_coordinate_withModifier_client( &self, index: NSUInteger, point: NSPoint, flags: NSUInteger, sender: Option<&AnyObject>, ) -> bool

where Self: Sized + Message,

Sends a mouseUp to an input method.

unsafe fn mouseMovedOnCharacterIndex_coordinate_withModifier_client( &self, index: NSUInteger, point: NSPoint, flags: NSUInteger, sender: Option<&AnyObject>, ) -> bool

where Self: Sized + Message,

Passes a mouseMoved event to the input method.

impl IMKStateSetting for IMKInputController

unsafe fn activateServer(&self, sender: Option<&AnyObject>)

where Self: Sized + Message,

Activates the input method.

unsafe fn deactivateServer(&self, sender: Option<&AnyObject>)

where Self: Sized + Message,

Deactivate the input method.

unsafe fn valueForTag_client( &self, tag: c_long, sender: Option<&AnyObject>, ) -> Option<Retained<AnyObject>>

where Self: Sized + Message,

Return a object value whose key is tag. The returned object should be autoreleased.

unsafe fn setValue_forTag_client( &self, value: Option<&AnyObject>, tag: c_long, sender: Option<&AnyObject>, )

where Self: Sized + Message,

Set the tagged value to the object specified by value.

unsafe fn modes( &self, sender: Option<&AnyObject>, ) -> Option<Retained<NSDictionary>>

where Self: Sized + Message,

This is called to obtain the input method’s modes dictionary.

unsafe fn recognizedEvents(&self, sender: Option<&AnyObject>) -> NSUInteger

where Self: Sized + Message,

Returns an unsigned integer containing a union of event masks (see NSEvent.h)

unsafe fn showPreferences(&self, sender: Option<&AnyObject>)

where Self: Sized + Message,

Looks for a nib file containing a windowController class and a preferences utility. If found the panel is displayed.

impl Message for IMKInputController

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for IMKInputController

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for IMKInputController

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for IMKInputController

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for IMKInputController

impl Eq for IMKInputController