| # PFApplicationUIElement
Superclass: | PFUIElement
Declared In: | PFUIElement.h
## 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. Before a client application can make use of this class, the "Enable access for assistive devices" setting in the Universal Access pane of System Preferences must be turned on, or the client application must be made a trusted process through use of the accessibility API's `AXMakeProcessTrusted()` function. Authentication may be required. ## Groups ### 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. ### ELEMENT UTILITIES #### Group members: `-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. `+typeCharactersSystemWide:keyCode:withModifierFlags:` Class method posts keyboard events to the active application. ### ACCESSOR METHODS #### Group members: `-pidNumber` Returns the BSD Unix process identification number (PID) of the receiver. ## Methods `+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. `-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. `+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. `+typeCharactersSystemWide:keyCode:withModifierFlags:` Class method posts keyboard events to the active application. ### applicationUIElementWithBundleIdentifier:delegate: Convenience class method creates and returns an initialized PFApplicationUIElement object with `bundleIdentifier`, the target application's bundle identifier.
    + (PFApplicationUIElement *)
            applicationUIElementWithBundleIdentifier:(NSString *)bundleIdentifier
            delegate:(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.
    + (PFApplicationUIElement *)applicationUIElementWithPath:(NSString *)fullPath
            delegate:(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.
    + (PFApplicationUIElement *)applicationUIElementWithPid:(pid_t)pid
            delegate:(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.
    + (PFApplicationUIElement *)applicationUIElementWithURL:(NSURL *)url
            delegate:(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:. ### 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.
    - (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. ##### 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` without regard to 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.
    - (PFApplicationUIElement *)initSystemWideWithDelegate:(id)delegate;
##### 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.
    - (PFApplicationUIElement *)initWithBundleIdentifier:(NSString *)bundleIdentifier
            delegate:(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.
    - (PFApplicationUIElement *)initWithPath:(NSString *)fullPath
            delegate:(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. 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.
    - (PFApplicationUIElement *)initWithPid:(pid_t)pid delegate:(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 A PFApplicationUIElement object whose UNIX process identifier is 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.
    - (PFApplicationUIElement *)initWithURL:(NSURL *)url
            delegate:(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. ### systemWideUIElementWithDelegate: Convenience class method creates and returns an initialized system-wide PFApplicationUIElement object.
    + (PFApplicationUIElement *)systemWideUIElementWithDelegate:(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.
    - (void)typeCharacters:(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 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.
    + (void)typeCharactersSystemWide:(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 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. Last Updated: Sunday, October 16, 2011