Struct GCKeyboardInput

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

Available on crate features GCKeyboardInput and GCPhysicalInputProfile only.

Keyboard profile. Contains the current state of buttons specified in GCKeyCodes.h.

GCKeyboardInput is designed primarly for input polling. For the best text input experience, UIKit/AppKit usage is recommended.

See also Apple’s documentation

Implementations

impl GCKeyboardInput

pub unsafe fn keyChangedHandler(&self) -> GCKeyboardValueChangedHandler

Available on crate features GCControllerButtonInput and GCControllerElement and GCKeyCodes and block2 and objc2-core-foundation only.

pub unsafe fn setKeyChangedHandler( &self, key_changed_handler: GCKeyboardValueChangedHandler, )

Available on crate features GCControllerButtonInput and GCControllerElement and GCKeyCodes and block2 and objc2-core-foundation only.

Setter for keyChangedHandler.

pub unsafe fn isAnyKeyPressed(&self) -> bool

Before querying any key for a value it might be useful to check if any key is actually pressed

pub unsafe fn buttonForKeyCode( &self, code: GCKeyCode, ) -> Option<Retained<GCControllerButtonInput>>

Available on crate features GCControllerButtonInput and GCControllerElement and GCKeyCodes and objc2-core-foundation only.

Alongside general subscript notation of GCPhysicalInputProfile keys can be accessed using this method.

Parameter code: is a low level key code that can be used for accessing a keyboard button.

Note: Full list of supported key constants can be found in GCKeyCodes.h and GCKeyNames.h

impl GCKeyboardInput

Methods declared on superclass NSObject.

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

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

Methods from Deref<Target = GCPhysicalInputProfile>

pub unsafe fn device(&self) -> Option<Retained<ProtocolObject<dyn GCDevice>>>

Available on crate feature GCDevice only.

A profile keeps a reference to the device that this profile is mapping input from

pub unsafe fn lastEventTimestamp(&self) -> NSTimeInterval

The last time elements of this profile were updated.

pub unsafe fn hasRemappedElements(&self) -> bool

Whether the user has remapped their physical input controls for this profile at the system level.

On iOS and tvOS, users can remap their game controller inputs in Settings.

pub unsafe fn valueDidChangeHandler( &self, ) -> *mut DynBlock<dyn Fn(NonNull<GCPhysicalInputProfile>, NonNull<GCControllerElement>)>

Available on crate features GCControllerElement and block2 only.

Set this block if you want to be notified when a value on a element changed. If multiple elements have changed this block will be called for each element that changed.

Parameter profile: this profile that is being used to map the raw input data into logical values on controller elements such as the dpad or the buttons.

Parameter element: the element that has been modified.

pub unsafe fn setValueDidChangeHandler( &self, value_did_change_handler: Option<&DynBlock<dyn Fn(NonNull<GCPhysicalInputProfile>, NonNull<GCControllerElement>)>>, )

Available on crate features GCControllerElement and block2 only.

Setter for valueDidChangeHandler.

pub unsafe fn elements( &self, ) -> Retained<NSDictionary<NSString, GCControllerElement>>

Available on crate feature GCControllerElement only.

The following properties allow for runtime lookup of any input element on a profile, when provided with a valid alias.

pub unsafe fn buttons( &self, ) -> Retained<NSDictionary<NSString, GCControllerButtonInput>>

Available on crate features GCControllerButtonInput and GCControllerElement only.

pub unsafe fn axes( &self, ) -> Retained<NSDictionary<NSString, GCControllerAxisInput>>

Available on crate features GCControllerAxisInput and GCControllerElement only.

pub unsafe fn dpads( &self, ) -> Retained<NSDictionary<NSString, GCControllerDirectionPad>>

Available on crate features GCControllerDirectionPad and GCControllerElement only.

pub unsafe fn touchpads( &self, ) -> Retained<NSDictionary<NSString, GCControllerTouchpad>>

Available on crate features GCControllerElement and GCControllerTouchpad only.

pub unsafe fn allElements(&self) -> Retained<NSSet<GCControllerElement>>

Available on crate feature GCControllerElement only.

The following properties allow for dynamic querying of the input elements available on a profile.

pub unsafe fn allButtons(&self) -> Retained<NSSet<GCControllerButtonInput>>

Available on crate features GCControllerButtonInput and GCControllerElement only.

pub unsafe fn allAxes(&self) -> Retained<NSSet<GCControllerAxisInput>>

Available on crate features GCControllerAxisInput and GCControllerElement only.

pub unsafe fn allDpads(&self) -> Retained<NSSet<GCControllerDirectionPad>>

Available on crate features GCControllerDirectionPad and GCControllerElement only.

pub unsafe fn allTouchpads(&self) -> Retained<NSSet<GCControllerTouchpad>>

Available on crate features GCControllerElement and GCControllerTouchpad only.

pub unsafe fn objectForKeyedSubscript( &self, key: &NSString, ) -> Option<Retained<GCControllerElement>>

Available on crate feature GCControllerElement only.

Profile elements can be accessed using keyed subscript notation, with a valid alias of its inputs.

Note: Equivalent to -elements

pub unsafe fn capture(&self) -> Retained<Self>

Polls the state vector of the physical input input and saves it to a new and writable instance of GCPhysicalInputProfile.

If your application is heavily multithreaded this may also be useful to guarantee atomicity of input handling as a snapshot will not change based on user input once it is taken.

See: snapshot

Returns: A new physical input profile with the duplicated state vector of the current physical input

pub unsafe fn setStateFromPhysicalInput( &self, physical_input: &GCPhysicalInputProfile, )

Sets the state vector of the physical input profile to a copy of the passed in physical input profile’s state vector.

Note: If the controller’s snapshot flag is set to NO, this method has no effect.

See: GCController.snapshot

pub unsafe fn mappedElementAliasForPhysicalInputName( &self, input_name: &NSString, ) -> Retained<NSString>

Returns the primary alias of the GCControllerElement that a given physical input maps to.

If the user were to map a physical press of the A button of their game controller to the B button, then -[GCPhysicalInputProfile mappedElementAliasForPhysicalInputName: GCInputButtonA] would return GCInputButtonB. Note that mappings can change anytime your app is backgrounded, so make sure you update any relevant visuals when returning to foreground.

Parameter inputName: A GCInput string corresponding to the physical button you want the mapped element alias for.

Returns: A GCInput string corresponding to the primary alias of the GCControllerElement that a given physical button maps to, or nil if there is no mapping.

pub unsafe fn mappedPhysicalInputNamesForElementAlias( &self, element_alias: &NSString, ) -> Retained<NSSet<NSString>>

Returns a set of GCInput strings corresponding to physical inputs that are mapped to a given GCControllerElement.

If the user mapped the physical press of the A button, the B button, and the X button to the B button, then -[GCPhysicalInputProfile mappedPhysicalInputNamesForElementAlias: GCInputButtonB] would return [GCInputButtonA, GCInputButtonB, GCInputButtonX]. Note that mappings can change anytime your app is backgrounded, so make sure you update any relevant visuals when returning to foreground.

Parameter elementAlias: A GCInput string corresponding to an alias of the GCControllerElement you want the physical buttons for.

Returns: A set of GCInput strings corresponding to physical inputs that are mapped to a given GCControllerElement, or an empty set if there are no mappings.

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 GCKeyboardInput

fn as_ref(&self) -> &AnyObject

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

impl AsRef<GCKeyboardInput> for GCKeyboardInput

fn as_ref(&self) -> &Self

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

impl AsRef<GCPhysicalInputProfile> for GCKeyboardInput

fn as_ref(&self) -> &GCPhysicalInputProfile

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

impl AsRef<NSObject> for GCKeyboardInput

fn as_ref(&self) -> &NSObject

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

impl Borrow<AnyObject> for GCKeyboardInput

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<GCPhysicalInputProfile> for GCKeyboardInput

fn borrow(&self) -> &GCPhysicalInputProfile

Immutably borrows from an owned value.

impl Borrow<NSObject> for GCKeyboardInput

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for GCKeyboardInput

const NAME: &'static str = "GCKeyboardInput"

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

type Super = GCPhysicalInputProfile

The superclass of this class.

type ThreadKind = <<GCKeyboardInput 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 GCKeyboardInput

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

Formats the value using the given formatter.

impl Deref for GCKeyboardInput

type Target = GCPhysicalInputProfile

The resulting type after dereferencing.

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

Dereferences the value.

impl Hash for GCKeyboardInput

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 Message for GCKeyboardInput

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

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for GCKeyboardInput

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 GCKeyboardInput

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 GCKeyboardInput

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

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

impl DowncastTarget for GCKeyboardInput

impl Eq for GCKeyboardInput