PFApplicationUIElement

Superclass:
Declared In:

Introduction

A concrete class representing the root application UI element of a running application or the system-wide UI element.

Discussion

A PFApplicationUIElement object represents the root application UI element of a running application or the system-wide UI element. It is a subclass of PFUIElement and inherits all of PFUIElement's functionality (except that it does not respond to the -PFUIElementWasDestroyed: delegate method). It offers additional features for root-level UI elements (applications and the system-wide UI element).

See the PFUIElement class description for more information.

A client application may subclass PFApplicationUIElement and override its designated initializer or a convenience initializer or provide a new initializer that calls its designated initializer. The subclass must ultimately call PFApplicationUIElement's designated initializer, -initWithPid:delegate:. The designated initializer automatically registers the subclass's Class object so that PFUIElement methods that allocate and initialize a new root application UI Element will know what class of object to instantiate based on the target application's PID. The -[PFUIElement applicationElement] method, for example, calls +[PFApplicationUIElement applicationUIElementClassForPid:], passing in the PID obtained from -[PFUIElement pid], in order to obtain the subclass that was registered for that application, and it then instantiates and initializes a PFApplicationUIElement of the registered class. Subclassers of PFApplicationUIElement can also subclass PFUIElement by using the class registry mechanism. For details on the class registry mechanism, see +registerUIElementClass:forPid: , +applicationUIElementClassForPid: and +UIElementClassForPid: .

Before a client application can make use of this class, it must be authorized to control the computer using accessibility features. Authentication may be required.



Groups

PROPERTIES AND ACCESSOR METHODS

Group members:

-pidNumber

Returns the BSD Unix process identification number (PID) of the receiver.

 

ELEMENT UTILITIES

Group members:

-elementAtIndexPath:

Creates and returns a PFApplicationUIElement or PFUIElement object representing the visible UI element at the specified index path belonging to the receiving application UI element.

-elementAtPoint:

Creates and returns a PFUIElement object representing the visible UI element located at point on the screen belonging to the receiving application UI element.

-typeCharacters:keyCode:withModifierFlags:

Posts keyboard events to the application represented by the receiver, whether or not it is the active application. DEPRECATED in OS X Mavericks 10.9.

+typeCharactersSystemWide:keyCode:withModifierFlags:

Class method posts keyboard events to the active application. DEPRECATED in OS X Mavericks 10.9.

 

CLASS REGISTRATION METHODS

Group members:

+applicationUIElementClassForPid:

Class method returns the registered Class object for the root application UI element for the application having the given process identifier or PID.

+registerUIElementClass:forPid:

Class method registers the Class object for the PFUIElement base class or subclass for the application having the given process identifier or PID.

+UIElementClassForPid:

Class method returns the registered Class object for the UI element whose root application UI element has the given process identifier or PID.

 

INITIALIZATION

Group members:

+applicationUIElementWithBundleIdentifier:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with bundleIdentifier, the target application's bundle identifier.

+applicationUIElementWithPath:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with fullPath, the full path to the target application's bundle or file.

+applicationUIElementWithPid:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with pid, the UNIX process identifier for the application.

+applicationUIElementWithURL:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with url, the file URL for the target application's bundle or file.

-initSystemWideWithDelegate:

The designated initializer for the PFApplicationUIElement class for a system-wide element.

-initWithBundleIdentifier:delegate:

Initializes and returns a newly allocated PFApplicationUIElement object with bundleIdentifier, the target application's bundle identifier.

-initWithPath:delegate:

Initializes and returns a newly allocated PFApplicationUIElement object with fullPath, the full path to the target application's bundle or file.

-initWithPid:delegate:

The designated initializer for the PFApplicationUIElement class for a specific application.

-initWithURL:delegate:

Initializes and returns a newly allocated PFApplicationUIElement object with url, the file URL for the target application's bundle or file.

+systemWideUIElementWithDelegate:

Convenience class method creates and returns an initialized system-wide PFApplicationUIElement object.


Methods

+applicationUIElementClassForPid:

Class method returns the registered Class object for the root application UI element for the application having the given process identifier or PID.

+applicationUIElementWithBundleIdentifier:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with bundleIdentifier, the target application's bundle identifier.

+applicationUIElementWithPath:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with fullPath, the full path to the target application's bundle or file.

+applicationUIElementWithPid:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with pid, the UNIX process identifier for the application.

+applicationUIElementWithURL:delegate:

Convenience class method creates and returns an initialized PFApplicationUIElement object with url, the file URL for the target application's bundle or file.

-elementAtIndexPath:

Creates and returns a PFApplicationUIElement or PFUIElement object representing the visible UI element at the specified index path belonging to the receiving application UI element.

-elementAtPoint:

Creates and returns a PFUIElement object representing the visible UI element located at point on the screen belonging to the receiving application UI element.

-initSystemWideWithDelegate:

The designated initializer for the PFApplicationUIElement class for a system-wide element.

-initWithBundleIdentifier:delegate:

Initializes and returns a newly allocated PFApplicationUIElement object with bundleIdentifier, the target application's bundle identifier.

-initWithPath:delegate:

Initializes and returns a newly allocated PFApplicationUIElement object with fullPath, the full path to the target application's bundle or file.

-initWithPid:delegate:

The designated initializer for the PFApplicationUIElement class for a specific application.

-initWithURL:delegate:

Initializes and returns a newly allocated PFApplicationUIElement object with url, the file URL for the target application's bundle or file.

-pidNumber

Returns the BSD Unix process identification number (PID) of the receiver.

+registerUIElementClass:forPid:

Class method registers the Class object for the PFUIElement base class or subclass for the application having the given process identifier or PID.

+systemWideUIElementWithDelegate:

Convenience class method creates and returns an initialized system-wide PFApplicationUIElement object.

-typeCharacters:keyCode:withModifierFlags:

Posts keyboard events to the application represented by the receiver, whether or not it is the active application. DEPRECATED in OS X Mavericks 10.9.

+typeCharactersSystemWide:keyCode:withModifierFlags:

Class method posts keyboard events to the active application. DEPRECATED in OS X Mavericks 10.9.

+UIElementClassForPid:

Class method returns the registered Class object for the UI element whose root application UI element has the given process identifier or PID.


applicationUIElementClassForPid:


Class method returns the registered Class object for the root application UI element for the application having the given process identifier or PID.

+ (Class)applicationUIElementClassForPid:(pid_t)pid; 
Parameters
pid

An integer, the running application's BSD Unix process identification number.

Return Value

The Class registered as the root application UI element class or subclass for the given PID, or the PFApplicationUIElement base class if the PID is not registered for subclassing.

Discussion

When a root application UI element is created and initialized, the PFApplicationUIElement designated initializer, -initWithPid:delegate: , automatically registers its class in an internal dictionary keyed to the application's process identifier or PID. The class is always the PFApplicationUIElement base clase or a subclass. This method can be used to query the internal registry to obtain the PFApplicationUIElement class or subclass that was registered for a given target application. This makes it possible for client applications to create new application UI elements of the appropriate class, based on the target application's PID, using a statement like this: [[[PFApplicationUIElement applicationUIElementClassForPid:pid] alloc] initWithPid:pid delegate:[self delegate]]. The target application's PID as an NSNumber object is always available from PFApplicationUIElement's -pidNumber method. The PID is also always available as a pid_t (int) value from PFUIElement's -pid method. If the PID has not been registered, this method returns the PFApplicationUIElement base class.

Clients that do not subclass PFApplicationUIElement or PFUIElement need not pay any attention to the registry mechanism.

Clients that do subclass PFApplicationUIElement or both of them need to observe a few simple requirements:

(1) They must ensure that their PFApplicationUIElement subclass initializers ultimately call the PFApplicationUIElement designated initializer, --initWithPid:delegate: , which updates the registry. Subclasses must always call through to the base class designated initializer anyway, so this should never be an issue.

(2) If they subclass PFUIElement as well, they must call the +registerUIElementClass:forPid: class method immediately after creating and initializing an instance of the PFApplicationUIElement subclass, to register the subclass in place of the default PFUIElement class.

(3) If they implement any PFUIElement methods that return the UI element's root application UI element, those methods must call the +applicationUIElementClassForPid: class method to create, initialize and return a PFApplicationUIElement class or subclass instance of the correct class for the target application.

(4) If a screen reader or similar application uses a subclass of PFApplicationUIElement, it must create and initialize a root application UI element early in the execution path, in order to register the subclass before calling a method like PFUIElement's -applicationElement on the UI element object. If it subclasses PFUIElement, it must also call +registerUIElementClass:forPid: at the same time. A screen reader application might not normally create and initialize a root application UI element directly but instead use a method like PFUIElement's +elementAtPoint to get a specific UI element. If it then navigates the UI element hierarchy using a method like -AXParent, which might encounter the root application UI element, it must first have registered the PFApplicationUIElement subclass by creating and initializing a dummy subclass instance; and, of course, it must first have registered any PFUIElement subclass.

In general, any application that subclasses PFApplicationUIElement or both UI element classes should create and initialize a root application UI element at the outset, and also register any PFUIElement subclass immedidately afterward.

See also +registerUIElementClass:forPid: and +UIElementClassForPid:.


applicationUIElementWithBundleIdentifier:delegate:


Convenience class method creates and returns an initialized PFApplicationUIElement object with bundleIdentifier, the target application's bundle identifier.

+ (nullable instancetype)
        applicationUIElementWithBundleIdentifier:(nullable NSString *)bundleIdentifier 
        delegate:(nullable id)aDelegate; 
Parameters
bundleIdentifier

An NSString object, the application bundle's identifier.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

An autoreleased PFApplicationUIElement object, or nil if there is no application bundle with a bundle identifier of bundleIdentifier.

Discussion

Use this convenience method to create and return an initialized root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also +applicationUIElementWithPath:delegate: , +applicationUIElementWithURL:delegate: , +applicationUIElementWithPid:delegate: and +systemWideUIElementWithDelegate:.


applicationUIElementWithPath:delegate:


Convenience class method creates and returns an initialized PFApplicationUIElement object with fullPath, the full path to the target application's bundle or file.

+ (nullable instancetype)applicationUIElementWithPath:(nullable NSString *)fullPath 
        delegate:(nullable id)aDelegate; 
Parameters
fullPath

An NSString object giving the full path to the application.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

An autoreleased PFApplicationUIElement object, or nil if there is no application at fullPath.

Discussion

Use this convenience method to create and return an initialized root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also +applicationUIElementWithURL:delegate: , +applicationUIElementWithBundleIdentifier:delegate: , +applicationUIElementWithPid:delegate: and +systemWideUIElementWithDelegate:.


applicationUIElementWithPid:delegate:


Convenience class method creates and returns an initialized PFApplicationUIElement object with pid, the UNIX process identifier for the application.

+ (nullable instancetype)applicationUIElementWithPid:(pid_t)pid 
        delegate:(nullable id)aDelegate; 
Parameters
pid

An integer, the running application's BSD Unix process identification number.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

An autoreleased PFApplicationUIElement object, or nil if there is no application at url.

Discussion

Use this convenience method to create and return an initialized root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also +applicationUIElementWithPath:delegate: , +applicationUIElementWithURL:delegate: , +applicationUIElementWithBundleIdentifier:delegate: and +systemWideUIElementWithDelegate:.


applicationUIElementWithURL:delegate:


Convenience class method creates and returns an initialized PFApplicationUIElement object with url, the file URL for the target application's bundle or file.

+ (nullable instancetype)applicationUIElementWithURL:(nullable NSURL *)url 
        delegate:(nullable id)aDelegate; 
Parameters
url

An NSURL object referencing the application.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

An autoreleased PFApplicationUIElement object, or nil if there is no application at url.

Discussion

Use this convenience method to create and return an initialized root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also +applicationUIElementWithPath:delegate: , +applicationUIElementWithBundleIdentifier:delegate: , +applicationUIElementWithPid:delegate: and +systemWideUIElementWithDelegate:.


elementAtIndexPath:


Creates and returns a PFApplicationUIElement or PFUIElement object representing the visible UI element at the specified index path belonging to the receiving application UI element.

- (nullable id)elementAtIndexPath:(NSIndexPath *)indexPath; 
Parameters
indexPath

An NSIndexPath object.

Return Value

The PFApplicationUIElement or PFUIElement object at the specified index path, or nil if the indexPath is invalid (for example, if it contains an NSNotfound value), or if the rootIndex feature is in use and it identifies a different appliation UI element than self.

Discussion

Use this method to obtain a PFApplicationUIElement or PFUIElement object when you have the index path defining its position in the Accessibility UI element hierarchy.

This method returns nil if indexPath contains an out-of-bounds index (an index greater than the index of the last child element at that position). Typically, this is an NSNotFound value created in -parentIndexPath or -indexPath because the target application's accessibility hierarchy contains a mismatch error where an element is not a child of its parent.

It also returns nil if the rootIndex feature is in use to identify multip application UI elements and the rootIndex of the element at indexPath identifies a different application UI element than self.

Use the PFUIElement methods -parentIndexPath and -indexPath to create index paths for specific UI elements.


elementAtPoint:


Creates and returns a PFUIElement object representing the visible UI element located at point on the screen belonging to the receiving application UI element.

- (nullable PFUIElement *)elementAtPoint:(NSPoint)point; 
Parameters
point

An NSPoint struct using top-left relative screen coordinates.

Return Value

The PFUIElement object at point, or nil if the application does not own it or an error occurs.

Discussion

Use this method to read the screen, based, for example, on the current location of the mouse.

Use the PFUIElement class method +elementAtPoint:withDelegate:error: instead of this instance method to get a PFUIElement object representing the UI element located at point no matter what application owns it.

See PFUIElement's -initWithElementRef:delegate:: method for important information.


initSystemWideWithDelegate:


The designated initializer for the PFApplicationUIElement class for a system-wide element.

- (nullable instancetype)initSystemWideWithDelegate:(nullable id)delegate NS_DESIGNATED_INITIALIZER; 
Parameters
delegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

A system-wide PFApplicationUIElement object.

Discussion

Initializes and returns a newly allocated system-wide PFApplicationUIElement object.

Use this designated initializer to initialize a newly-allocated root UI element object for the entire system, representing all running applications collectively. Use this method, for example, to obtain the element currently having systemwide focus without first determining which application is active.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: method for important information.

See also -initWithPath:delegate: , -initWithURL:delegate: , -initWithBundleIdentifier:delegate: and -initWithPid:delegate:.


initWithBundleIdentifier:delegate:


Initializes and returns a newly allocated PFApplicationUIElement object with bundleIdentifier, the target application's bundle identifier.

- (nullable instancetype)initWithBundleIdentifier:(nullable NSString *)bundleIdentifier 
        delegate:(nullable id)aDelegate; 
Parameters
bundleIdentifier

An NSString object, the application bundle's identifier.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

A PFApplicationUIElement object, or nil if there is no application bundle with a bundle identifier of bundleIdentifier.

Discussion

Use this convenience initializer to initialize a newly-allocated root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also -initWithPath:delegate: , -initWithURL:delegate: , -initWithPid:delegate: and -initSystemWideWithDelegate:.


initWithPath:delegate:


Initializes and returns a newly allocated PFApplicationUIElement object with fullPath, the full path to the target application's bundle or file.

- (nullable instancetype)initWithPath:(nullable NSString *)fullPath 
        delegate:(nullable id)aDelegate; 
Parameters
fullPath

An NSString object giving the full path to the application.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

A PFApplicationUIElement object, or nil if there is no application at fullPath.

Discussion

Use this convenience initializer to initialize a newly-allocated root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

If the target application is not a user application, this method calls Application Services functions that were deprecated in OS X Mountain Lion 10.8 and/or OS X Mavericks 10.9 because the corresponding NSRunningApplication methods do not work with system or background applications. Deprecation warnings are suppressed during compilation.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also -initWithURL:delegate: , -initWithBundleIdentifier:delegate: , -initWithPid:delegate: and -initSystemWideWithDelegate:.


initWithPid:delegate:


The designated initializer for the PFApplicationUIElement class for a specific application.

- (nullable instancetype)initWithPid:(pid_t)pid delegate:(nullable id)aDelegate NS_DESIGNATED_INITIALIZER; 
Parameters
pid

An integer, the running application's BSD Unix process identification number.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

A PFApplicationUIElement object whose UNIX process identifier is pid, or nil if there is no application with that pid.

Discussion

Initializes and returns a newly allocated PFApplicationUIElement object with pid, the target application's BSD Unix process identification number (PID).

Use this designated initializer to initialize a newly-allocated root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also -initWithPath:delegate: , -initWithURL:delegate: , -initWithBundleIdentifier:delegate: and -initSystemWideWithDelegate:.


initWithURL:delegate:


Initializes and returns a newly allocated PFApplicationUIElement object with url, the file URL for the target application's bundle or file.

- (nullable instancetype)initWithURL:(nullable NSURL *)url 
        delegate:(nullable id)aDelegate; 
Parameters
url

An NSURL object referencing the application.

aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

A PFApplicationUIElement object, or nil if there is no application at url.

Discussion

Use this convenience initializer to initialize a newly-allocated root UI element object for a specific application; for example, to browse a specific application's user interface without regard to whether it is frontmost or where on the screen its UI elements may be located.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also -initWithPath:delegate: , -initWithBundleIdentifier:delegate: , -initWithPid:delegate: and -initSystemWideWithDelegate:.


pidNumber


Returns the BSD Unix process identification number (PID) of the receiver.

- (NSNumber *)pidNumber; 
Return Value

An NSNumber object encoding an integer value.

Discussion

It is sometimes useful to know the process identification number of an application. For example, it can be used with a variety of Carbon functions to access information not otherwise readily available in Cocoa.

See also the -pid method in the PFUIElement class, which returns the PID as an integer.

Use NSNumber's -intValue method to extract the integer value of the result.


registerUIElementClass:forPid:


Class method registers the Class object for the PFUIElement base class or subclass for the application having the given process identifier or PID.

+ (BOOL)registerUIElementClass:(Class)uiElementClass forPid:(pid_t)pid; 
Parameters
uiElementClass

The Class object PFUIElement or a subclass.

pid

An integer, the running application's BSD Unix process identification number.

Discussion

Returns YES if the PFUIElement subclass Class object is successfully registered. A result of NO indicates that a PFApplicationUIElement subclass has not yet been registered for the same PID by creating and initializing it.

When a root application UI element is created and initialized, the PFApplicationUIElement designated initializer, -initWithPid:delegate: , automatically registers its class in an internal dictionary keyed to the application's process identifier or PID. The class is always the PFApplicationUIElement base class or a subclass. This method can be called, immediately after creating and initializing a PFApplicationUIElement subclass, to register a subclass of PFUIElement for the same PID. Subclassing PFUIElement is optional. The target application's PID as an NSNumber object is always available from PFApplicationUIElement's -pidNumber method. The PID is also always available as a pid_t (int) value from PFUIElement's -pid method.

See also +applicationUIElementClassForPid: and +UIElementClassForPid: .


systemWideUIElementWithDelegate:


Convenience class method creates and returns an initialized system-wide PFApplicationUIElement object.

+ (nullable instancetype)systemWideUIElementWithDelegate:(nullable id)aDelegate; 
Parameters
aDelegate

An object that may implement the optional -PFUIElementReportError: delegate method. May be nil.

Return Value

An autoreleased system-wide PFApplicationUIElement object.

Discussion

Use this convenience method to create and return an initialized UI element object for the entire system, representing all running applications collectively. Use this method, for example, to obtain the element currently having systemwide focus without first determining which application is active.

A PFApplicationUIElement object does not participate in PFUIElement's delegate and notification mechanisms regarding destroyed UI elements. It does not report when it is destroyed (that is, when the application quits). See the -PFUIElementWasDestroyed: delegate method and PFUIElement's -elementInfo for details regarding these mechanisms.

See PFUIElement's -initWithElementRef:delegate: for important information.

See also +applicationUIElementWithPath:delegate: , +applicationUIElementWithURL:delegate: , +applicationUIElementWithBundleIdentifier:delegate: and +applicationUIElementWithPid:delegate:.


typeCharacters:keyCode:withModifierFlags:


Posts keyboard events to the application represented by the receiver, whether or not it is the active application. DEPRECATED in OS X Mavericks 10.9.

- (void)typeCharacters:(nullable NSString *)characters 
        keyCode:(unsigned short)virtualKey withModifierFlags:(NSUInteger)flags; 
Parameters
characters

An NSString object representing a Unicode character that can be generated by a single key press without modifier keys (Shift excepted).

virtualKey

The virtual key code provided by NSEvent's -keyCode method.

flags

An integer; either 0 for no modifier keys, or one or more of the first five key mask constants listed in NSEvent.h (combined using the C bitwise OR operator, if more than one) for modifier keys.

Discussion

This method is deprecated in OS X Mavericks 10.9 and newer because Apple has deprecated the function on which it relies, AXUIElementPostKeyboardEvent() in AXUIElement.h. The similar CGPostKeyboardEvent() function in CGRemoteOperation.h was deprecated in Mac OS X 10.6 (Snow Leopard). Developers are advised to use Quartz Event Taps through the CGEventCreateKeyboardEvent() function in CGEvent.h or its Cocoa counterpart, +[NSEvent keyEventWithType:location:modifierFlags:timestamp:windowNumber:context:characters:charactersIgnoringModifiers:isARepeat:keyCode:].

In OS X Mountain Lion 10.8 or later, use this method to type one character at a time into the UI element that currently has keyboard focus in the application represented by the receiver (usually a text-based view or control such as a text view or a text field). Specifying the Command key in flags may be treated by the application as a keyboard shortcut for a menu item or button.

Use -typeCharactersSystemWide:keyCode:withModifierFlags: instead of this method to type characters into the active application without first determining which application is active.

The characters and flags parameters are equivalent to those used in NSEvent's -charactersIgnoringModifiers and -modifierFlags methods. The virtualKey parameter is the virtual key code provided by NSEvent's -keyCode method; it is a hardware-independent integer value provided by system resources for every known keyboard, mapped from the hardware-dependent raw key code using the current keyboard layout resource.

On Roman systems, the characters parameter is optional and should be passed as nil or an empty string unless you are knowledgeable regarding the use of keyboard layouts, but it is not optional on some other systems where it is used as a hint to supplement the virtual key code during key translation.


typeCharactersSystemWide:keyCode:withModifierFlags:


Class method posts keyboard events to the active application. DEPRECATED in OS X Mavericks 10.9.

+ (void)typeCharactersSystemWide:(nullable NSString *)characters 
        keyCode:(unsigned short)virtualKey withModifierFlags:(NSUInteger)flags; 
Parameters
characters

An NSString object representing a Unicode character that can be generated by a single key press without modifier keys (Shift excepted).

virtualKey

The virtual key code provided by NSEvent's -keyCode method.

flags

An unsigned integer; either 0 for no modifier keys, or one or more of the first five key mask constants listed in NSEvent.h (combined using the C bitwise OR operator, if more than one) for modifier keys.

Discussion

This method is deprecated in OS X Mavericks10.9 or later because Apple has deprecated the function on which it relies, AXUIElementPostKeyboardEvent() in AXUIElement.h. The similar CGPostKeyboardEvent() function in CGRemoteOperation.h was deprecated in Mac OS X 10.6 (Snow Leopard). Developers are advised to use Quartz Event Taps through the CGEventCreateKeyboardEvent() function in CGEvent.h or its Cocoa counterpart, +[NSEvent keyEventWithType:location:modifierFlags:timestamp:windowNumber:context:characters:charactersIgnoringModifiers:isARepeat:keyCode:].

In OS X Mountain Lion 10.8 or earlier, use this method to type one character at a time into the UI element that currently has keyboard focus in the active application (usually a text-based view or control such as a text view or a text field). Specifying the Command key in flags may be treated by the application as a keyboard shortcut for a menu item or button.

Use -typeCharacters:keyCode:withModifierFlags: instead of this method to type characters into a specific application whether or not it is active.

The characters and flags parameters are equivalent to those used in NSEvent's -charactersIgnoringModifiers and -modifierFlags methods. The virtualKey parameter is the virtual key code provided by NSEvent's -keyCode method; it is a hardware-independent integer value provided by system resources for every known keyboard, mapped from the hardware-dependent raw key code using the current keyboard layout resource.

On Roman systems, the characters parameter is optional and should be passed as nil or an empty string unless you are knowledgeable regarding the use of keyboard layouts, but it is not optional on some other systems where it is used as a hint to supplement the virtual key code during key translation.


UIElementClassForPid:


Class method returns the registered Class object for the UI element whose root application UI element has the given process identifier or PID.

+ (Class)UIElementClassForPid:(pid_t)pid; 
Parameters
pid

An integer, the running application's BSD Unix process identification number.

Return Value

The Class registered as the UI element class or subclass for the given PID, or the PFUIElement base class if the PID is not registered for subclassing.

Discussion

When a root application UI element is created and initialized, the PFApplicationUIElement designated initializer, -initWithPid:delegate: , automatically registers its default PFUIElement base class in an internal dictionary keyed to the application's process identifier or PID. If a client application wishes to subclass PFUIElement for the same application, it must call +registerUIElementClass:forPid: to register the subclass immediately after creating and initializing the PFApplicationUIElement subclass instance. Once registered, the class returned by this method is always the PFUIElement subclass. The target application's PID as an NSNumber object is always available from PFApplicationUIElement's -pidNumber method. The PID is also always available as a pid_t (int) value from PFUIElement's -pid method. If the PID has not been registered, this method returns the PFUIElement base class.

See also +registerUIElementClass:forPid: and +applicationUIElementClassForPid:.


Properties

rootIndex

The index of the root application UI element for use in a UI element's index path.


rootIndex


The index of the root application UI element for use in a UI element's index path.

@property(readwrite,
    retain) NSNumber *rootIndex; 
Return Value

An NSNumber object encoding an NSUInteger value.

Discussion

The root application element's root index is initialized to 0 when the application UI element is created because there is only one root application element in an application. For clients that wish to use index paths for combined management of multiple applications, the rootIndex property of PFApplicationUIElement can be set to any integer value immediately after it is created and initialized. The -indexPath and -parentIndexPath methods will thereafter include the new root index as the index of the root application UI element. When setting the root index to a value other than 0, it is the client's responsibility to manage the root application indexes.

Use NSNumber's -unsignedIntegerValue method to extract the NSUInteger value of the result.

See also -elementAtIndexPath:.