PFObserver |
A concrete class representing an observer that may be registered to observe changes to UI elements in a running application.
Conforms to: PFUIElementDelegate
Superclass: NSObject
Declared In: PFObserver.h
A PFObserver object represents an observer that may be registered to observe changes to UI elements on the screen in a running application, such as a menu, window or button.
The PFObserver class implements all of the functionality of the accessibility API's AXObserverRef object. It declares a delegate method, -applicationWithIdentifier:atPath:didPostAccessibilityNotification:fromObservedUIElement:forAffectedUIElement: that a client application can implement to monitor and respond to accessibility notifications. As an alternative, it permits you to write a similar callback method using Objective-C.
In this documentation "observer" refers to a programmatic PFObserver object. Depending on context, "UI element" or "element" may refer to a programmatic PFUIElement or PFApplicationUIElement object or to the user interface object in the running application that is represented by a PFUIElement or PFApplicationUIElement object. References to a "PFUIElement object" generally include a PFApplicationUIElement object, since the PFApplicationUIElement class is a subclass of PFUIElement.
A PFObserver object can register to receive various notifications that are posted by UI elements in any running application when they change state; for example, when an application is activated or a window is closed. When an observer has registered for a notification, a client's delegate method or callback method is triggered to take any desired action in response to the change in the observed UI element. You can create multiple observers and register each of them for one or more notifications, but it is usually easier to register a single observer in an application and register it for all of the notifications of interest. Observers can be unregistered at will for individual notifications or for all of them. Observers maintain lists of all of their current registrations.
When they change state, accessibility API objects post notifications identified by a string, usually beginning with the prefix "AX" as in "AXWindowCreated". In a client application, you normally use the NSString constants declared in the NSAccessibility informal protocol (in NSAccessibility.h, in the Cocoa AppKit framework). Alternatively, you can use the corresponding CFStringRef constants declared in the accessibility API headers and cast them to NSString*, or use the string itself. Some constants are omitted from NSAccessibility.h or from the accessibility API headers; if you can't find a desired constant in one of these headers, use a constant from the other header or the string itself. Note that some constants in these headers may be marked as obsolete; use only the non-obsolete constants or their string equivalents to maximize compatibility with future releases of Mac OS X.
Some applications implement custom UI elements. Although Apple discourages the invention of new notifications, some applications may implement custom notifications that are not part of Apple's accessibility API. This framework is written so that you can read and manipulate them, as well as Apple's built-in accessibility API notifications. You may be able to identify the strings used to identify custom notifications by reading an application's documentation or by examining the .strings files in its application bundle. The accessibility API currently offers no means to obtain a list of available notifications programmatically.
Public methods in the PFAssistive framework, unless otherwise noted, take Objective-C objects as parameters and, when they return Objective-C objects, return them autoreleased. Clients of the PFAssistive framework should not have to deal with Core Foundation objects. Unless otherwise noted, methods with return values return nil, NULL, 0, or NO in the event of an error.
Almost all standard UI element objects in Cocoa and Carbon applications come prewired to post notifications when they change state. Custom UI elements may have been written to post notifications, as well. However, there are many applications that do not use standard UI elements or that use custom elements that do not support the accessibility API. The only way to know which of an application's UI elements support the accessibility API is trial and error and, in some cases, an application's documentation.
The following notifications were introduced in Mac OS X v10.6: NSAccessibilityRowExpandedNotification, NSAccessibilityRowCollapsedNotification, NSAccessibilitySelectedCellsChangedNotification, NSAccessibilityUnitsChangedNotification, and NSAccessibilitySelectedChildrenMovedNotification.
Class Design:
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 trusted through use of the accessibility API's AXMakeProcessTrusted() function. Authentication may be required.
Class method returns an array of observers for the running application whose BSD Unix application process identification number is pid.
Class method unregisters and removes all observers for the running application whose BSD Unix application process identification number is pid, deallocating them if they have not been retained by the client.
Returns the receiver's delegate.
Sets the receiver's delegate to object.
Returns the BSD Unix process identification number (PID) of the receiver's target application.
Initializes and returns a newly allocated PFObserver object with path, the full path to the target application's bundle or file.
Initializes and returns a newly allocated PFObserver object with path, the full path to the target application's bundle or file, temporary notification delegate callbackDelegate, and callback selector callback. Provides no observer management.
The designated initializer for the PFObserver class for an observer that uses a delegate method. Initializes and returns a newly allocated PFObserver object with pid, the target application's BSD Unix process identification number (PID).
The designated initializer for the PFObserver class for an observer that uses a callback method. Initializes and returns a newly allocated PFObserver object with pid, the target application's BSD Unix process identification number (PID), temporary notification delegate callbackDelegate, and callback selector callback. Provides no observer management.
Invalidates this PFObserver object when it is no longer needed.
Reports whether this PFObserver object has been invalidated.
Convenience class method creates and returns an initialized PFObserver object with name, the name of the target application. Provides full observer management.
Convenience class method creates and returns an initialized PFObserver object with name, the name of the target application, temporary notification delegate callbackDelegate, and callback selector callback. Provides full observer management.
Convenience class method creates and returns an initialized PFObserver object with pid, the target application's BSD Unix process identification number (PID). Provides full observer management.
Convenience class method creates and returns an initialized PFObserver object with pid, the target application's BSD Unix process identification number (PID), temporary notification delegate callbackDelegate, and callback selector callback. Provides full observer management.
Returns a string that represents the receiver.
Returns YES if element is registered with the receiver for notification.
Registers the receiver to observe element for notification, saving contextInfo for return in the client's callback selector, returning YES if successful.
Returns a mutable array containing all registrations currently in effect in the receiver; that is, all registrations that the client has registered and has not unregistered using this observer.
Unregisters the receiver to observe all elements for all notifications.
Unregisters the receiver to observe element for all notifications.
Unregisters the receiver to observe element for notification.
Returns whether the receiving observer represents the same observer that observer represents.
Returns the receiver's delegate.
Returns a string that represents the receiver.
Initializes and returns a newly allocated PFObserver object with path, the full path to the target application's bundle or file.
Initializes and returns a newly allocated PFObserver object with path, the full path to the target application's bundle or file, temporary notification delegate callbackDelegate, and callback selector callback. Provides no observer management.
The designated initializer for the PFObserver class for an observer that uses a delegate method. Initializes and returns a newly allocated PFObserver object with pid, the target application's BSD Unix process identification number (PID).
The designated initializer for the PFObserver class for an observer that uses a callback method. Initializes and returns a newly allocated PFObserver object with pid, the target application's BSD Unix process identification number (PID), temporary notification delegate callbackDelegate, and callback selector callback. Provides no observer management.
Invalidates this PFObserver object when it is no longer needed.
Returns whether the receiving observer represents the same observer that observer represents.
Returns YES if element is registered with the receiver for notification.
Reports whether this PFObserver object has been invalidated.
Class method returns an array of observers for the running application whose BSD Unix application process identification number is pid.
Convenience class method creates and returns an initialized PFObserver object with name, the name of the target application. Provides full observer management.
Convenience class method creates and returns an initialized PFObserver object with name, the name of the target application, temporary notification delegate callbackDelegate, and callback selector callback. Provides full observer management.
Convenience class method creates and returns an initialized PFObserver object with pid, the target application's BSD Unix process identification number (PID). Provides full observer management.
Convenience class method creates and returns an initialized PFObserver object with pid, the target application's BSD Unix process identification number (PID), temporary notification delegate callbackDelegate, and callback selector callback. Provides full observer management.
Returns the BSD Unix process identification number (PID) of the receiver's target application.
Registers the receiver to observe element for notification, saving contextInfo for return in the client's callback selector, returning YES if successful.
Returns a mutable array containing all registrations currently in effect in the receiver; that is, all registrations that the client has registered and has not unregistered using this observer.
Class method unregisters and removes all observers for the running application whose BSD Unix application process identification number is pid, deallocating them if they have not been retained by the client.
Sets the receiver's delegate to object.
Unregisters the receiver to observe all elements for all notifications.
Unregisters the receiver to observe element for all notifications.
Unregisters the receiver to observe element for notification.
delegate |
Returns the receiver's delegate.
- (id <PFObserverDelegate>)delegate;
The receiver's delegate, an object of any type, or nil if it has no delegate.
-applicationWithIdentifier:atPath:didPostAccessibilityNotification:fromObservedUIElement:forAffectedUIElement: is the only available delegate method, which is optional. It is declared in the PFObserverDelegate protocol.
See also -setDelegate:.
description |
Returns a string that represents the receiver.
- (NSString *)description;
An NSString object.
The returned string is formatted as a property list showing all notifications for all UI elements for which the observer is registered. In client code, call NSLog() and pass in the observer to see this information in the Xcode run log and debug console log.
initWithPath: |
Initializes and returns a newly allocated PFObserver object with path, the full path to the target application's bundle or file.
- (id)initWithPath:(NSString *)fullPath;
fullPathAn NSString object giving the full path to the client application file.
An initialized PFObserver object, or nil if the target application is not running.
Use this convenience initializer or the designated initializer -initWithPid: to initialize a newly-allocated observer that uses a delegate method instead of a callback method to respond to accessibility notifications.
A client application must call -setDelegate: and -registerForNotification:fromElement:contextInfo: in order to receive notifications.
See the designated initializer -initWithPid: for important information about creating new observer objects.
See also +observerWithName: and +observerWithPid:.
initWithPath:notificationDelegate:callbackSelector: |
Initializes and returns a newly allocated PFObserver object with path, the full path to the target application's bundle or file, temporary notification delegate callbackDelegate, and callback selector callback. Provides no observer management.
- (id)initWithPath:(NSString *)fullPath notificationDelegate:(id)callbackDelegate callbackSelector:(SEL)callback;
fullPathAn NSString object giving the full path to the client application file.
callbackDelegateAn object of any type. A client application typically passes self in this parameter.
callbackThe notification delegate's Objective-C selector to be invoked when a notification is received.
An initialized PFObserver object, or nil if the target application is not running.
Use this convenience initializer or the designated initializer -initWithPid:notificationDelegate:calbackSelector: to initialize a newly-allocated application observer object that uses a callback method instead of a delegate method to respond to accessibility notifications.
A client application must call -registerForNotification:fromElement:contextInfo: in order to receive notifications.
See the designated initializer -initWithPid:notificationDelegate:calbackSelector: for important information about creating new observer objects.
See also +observerWithName:notificationDelegate:callbackSelector: and +observerWithPid:notificationDelegate:callbackSelector:.
initWithPid: |
The designated initializer for the PFObserver class for an observer that uses a delegate method. Initializes and returns a newly allocated PFObserver object with pid, the target application's BSD Unix process identification number (PID).
- (id)initWithPid:(pid_t)pid;
pidAn integer, the running application's BSD Unix process identification number (PID).
An initialized PFObserver object, or nil if the target application is not running.
Use this designated initializer or the convenience initializer -initWithPath: to initialize a newly-allocated application observer object that uses a delegate method instead of a callback method to respond to accessibility notifications.
A client application must call -setDelegate: and -registerForNotification:fromElement:contextInfo: in order to receive notifications.
Although this is a designated initializer for the PFObserver class, a client application normally creates new PFObserver objects without using this method directly, instead using the +observerWithName: or the +observerWithPid: class method. The class methods are strongly preferred because they set up private data structures that automatically manage observers.
An observer does nothing unless it has been registered to receive at least one notification with respect to at least one observed UI element of the target application, using -registerForNotification:fromElement:contextInfo:. There can be multiple observers for any one target application, but it is normally sufficient to create one observer per target application and register it for multiple notifications. If you use the +observerWithName: or the +observerWithPid: class method to create an observer, the observer is managed for you.
When an observer receives a notification from an observed element, it sends the -applicationWithIdentifier:atPath:didPostAccessibilityNotification:fromObservedUIElement:forAffectedUIElement: delegate message, passing the target application's identifier and path, the notification, the observed UI element, and the affected UI element (which may differ from the element being observed).
The client's delegate method will always receive the affected element, even when observing NSAccessibilityUIElementDestroyedNotification. However, you must treat a destroyed element as invalid; do not pass it as a parameter to methods that call accessibility API functions. You can, however, use a destroyed element with PFUIElement's -pid, and with PFUIElement's -isEqual: and -isEqualToElement: to manage any element cache you maintain. Note that attempting to pass a destroyed UI element in an accessibility API function is not guaranteed to return an accessibility API error. PFUIElement's -elementInfo method will return some valid information about a destroyed element.
If a delegate method initiates a time-consuming operation or an operation that might fail, consider executing the operation in a secondary thread using a method like NSThread's +detachNewThreadSelector:toTarget:withObject: method to avoid blocking the application. On the other hand, if a callback method runs an AppleScript script using a method like NSAppleScript's -executeAndReturnError: (or the preferred method, OSAScript's -executeAndReturnError:, in the OSAKit framework), always execute the operation using NSObject's -performSelectorOnMainThread:withObject:waithUntilDone: method with wait set to NO, because AppleScript scripts must run on the main application thread if they involve user interaction, as with the 'display dialog' command. AppleScript queues scripts on the main application thread in first-in, first-out (FIFO) order.
All observers maintain a list of the notifications and elements for which they are currently registered. See -registrations for details.
See also +observerWithName: and +observerWithPid:.
initWithPid:notificationDelegate:callbackSelector: |
The designated initializer for the PFObserver class for an observer that uses a callback method. Initializes and returns a newly allocated PFObserver object with pid, the target application's BSD Unix process identification number (PID), temporary notification delegate callbackDelegate, and callback selector callback. Provides no observer management.
- (id)initWithPid:(pid_t)pid notificationDelegate:(id)callbackDelegate callbackSelector:(SEL)callback;
pidAn integer, the running application's BSD Unix process identification number (PID).
callbackDelegateAn object of any type. A client typically passes self in this parameter.
callbackThe notification delegate's Objective-C selector to be invoked when a notification is received.
An initialized PFObserver object, or nil if the target application is not running.
Use this designated initializer or the convenience initializer -initWitPath:notificationDelegate:calbackSelector: to initialize a newly-allocated application observer object that uses a callback method instead of a delegate method to respond to accessibility notifications.
Although this is a designated initializer for the PFObserver class, a client application normally creates new PFObserver objects without using this method directly, instead using the +observerWithName:notificationDelegate:callbackSelector: or the +observerWithPid:notificationDelegate:callbackSelector: class method. The class methods are strongly preferred because they set up private data structures that automatically manage observers.
An observer does nothing unless it has been registered to receive at least one notification with respect to at least one observed UI element of the target application, using -registerForNotification:fromElement:contextInfo:. There can be multiple observers for any one target application, but it is normally sufficient to create one observer per target application and register it for multiple notifications. If you use the +observerWithName:notificationDelegate:callbackSelector: or the +observerWithPid:notificationDelegate:callbackSelector: class method to create an observer, the observer is managed for you.
When an observer receives a notification from an observed element, it invokes the specified callback selector on the notification delegate. It passes back to the client's callback method the observer, the notification, the affected UI element (which may differ from the element being observed), and any context information that was provided by the client when it registered the observer for the notification. A notification delegate is temporary; the relationship only lasts until the observer is deallocated. The client's callback selector should have the following signature:
- (void)observer:(PFObserver *)observer notification:(NSString *)notification element:(PFUIElement *)element contextInfo:(void *)contextInfo
The client's callback method will always receive the affected element, even when observing NSAccessibilityUIElementDestroyedNotification. However, you must treat a destroyed element as invalid; do not pass it as a parameter to methods that call accessibility API functions. You can, however, use a destroyed element with PFUIElement's -pid, and with PFUIElement's -isEqual: and -isEqualToElement: to manage any element cache you maintain. Note that attempting to pass a destroyed UI element in an accessibility API function is not guaranteed to return an accessibility API error. PFUIElement's -elementInfo method will return some valid information about a destroyed element.
If a callback method initiates a time-consuming operation or an operation that might fail, consider executing the operation in a secondary thread using a method like NSThread's +detachNewThreadSelector:toTarget:withObject: method to avoid blocking the application. On the other hand, if a callback method runs an AppleScript script using a method like NSAppleScript's -executeAndReturnError: (or the preferred method, OSAScript's -executeAndReturnError:, in the OSAKit framework), always execute the operation using NSObject's -performSelectorOnMainThread:withObject:waithUntilDone: method with wait set to NO, because AppleScript scripts must run on the main application thread if they involve user interaction, as with the 'display dialog' command. AppleScript queues scripts on the main application thread in first-in, first-out (FIFO) order.
All observers maintain a list of the notifications and elements for which they are currently registered. See -registrations for details.
If you allocate your own observer and use this method or -initWithPath:notificationDelegate:callbackSelector: to initialize it, you must manage the observer yourself. It is the client's responsibility to keep track of each observer created in this manner, retaining it as long as it is in use; to register and unregister it for notifications and elements as desired; to release it when done with it; and to maintain a list of its current registrations.
See also -initWithPath:notificationDelegate:callbackSelector:, +observerWithName:notificationDelegate:callbackSelector: and +observerWithPid:notificationDelegate:callbackSelector:.
invalidate |
Invalidates this PFObserver object when it is no longer needed.
- (void)invalidate;
Optionally call this method when the client application is finished with this PFObserver object.
It will be desirable to call this method in a garbage collected environment to avoid adding time-consuming activity at collection time (and it does no harm to call it in a reference counted environment). If the client application does not call this method, it will be called automatically when the object is deallocated or finalized. It sets any delegate to nil and takes care of memory management.
NOTE: This version of PFAssistive Framework does not support garbage collected clients.
See also -isValid.
isEqualToObserver: |
Returns whether the receiving observer represents the same observer that observer represents.
- (BOOL)isEqualToObserver:(PFObserver *)observer;
observerA PFObserver object to be tested for equality with the receiver.
Returns YES if the receiving observer represents the same observer that observer represents.
Use this method for efficiency if you know that observer is a PFObserver object. Otherwise, use -isEqual:.
isRegisteredForNotification:fromElement: |
Returns YES if element is registered with the receiver for notification.
- (BOOL)isRegisteredForNotification:(NSString *)notification fromElement:(PFUIElement *)element;
notificationAn NSString representing a notification; you may use a string constant from the NSAccessibility informal protocol or from the accessibility API's AXConstants.h header file cast to NSString*, or the string itself.
elementA PFUIElement object.
Returns YES if the receiver is registered for notification from element.
Use this method at any time to test whether a particular element is registered with the receiver for a particular notification. It always returns NO for an element that does not support the specified notification.
See also -registerForNotification:fromElement:contextInfo:, -unregisterForNotification:fromElement:, -unregisterForAllNotificationsFromElement: and -unregisterForAllNotifications.
isValid |
Reports whether this PFObserver object has been invalidated.
- (BOOL)isValid;
Returns YES if this PFUIElement object has been invalidated.
See also -invalidate.
observersForPid: |
Class method returns an array of observers for the running application whose BSD Unix application process identification number is pid.
+ (NSArray *)observersForPid:(pid_t)pid;
pidAn integer, a running application's BSD Unix process identification number (PID).
An NSArray object containing PFObserver objects, or nil if no observers exist for the application.
This method only returns observers that were created using +observerWithName:, +observerWithPid:, +observerWithName:notificationDelegate:callbackSelector: or +observerWithPid:notificationDelegate:callbackSelector:.
observerWithName: |
Convenience class method creates and returns an initialized PFObserver object with name, the name of the target application. Provides full observer management.
+ (PFObserver *)observerWithName:(NSString *)name;
nameAn NSString object giving the name of the application file.
An autoreleased PFObserver object, or nil if the target application is not running.
Use this convenience method or +observerWithPid: to create an observer that uses a delegate method instead of a callback method to respond to accessibility notifications.
A client application must call -setDelegate: and -registerForNotification:fromElement:contextInfo: in order to receive notifications.
See the designated initializer, -initWithPid: for important information about creating new observer objects.
See also -initWithPath: and +observerWithPid:.
observerWithName:notificationDelegate:callbackSelector: |
Convenience class method creates and returns an initialized PFObserver object with name, the name of the target application, temporary notification delegate callbackDelegate, and callback selector callback. Provides full observer management.
+ (PFObserver *)observerWithName:(NSString *)name notificationDelegate:(id)callbackDelegate callbackSelector:(SEL)callback;
nameAn NSString object giving the name of the application file.
callbackDelegateAn object of any type. A client typically passes self in this parameter.
callbackThe notification delegate's Objective-C selector to be invoked when a notification is received.
An autoreleased PFObserver object, or nil if the target application is not running.
Use this method to create an observer for a specific application given its name and to set up automatic management of the observer, for an observer that uses a callback method instead of a delegate method to respond to accessibility notifications.
See the designated initializer, -initWithPid:notificationDelegate:calbackSelector:, for full information about use of this method.
See also -initWithPath:notificationDelegate:callbackSelector: and +observerWithPid:notificationDelegate:callbackSelector:.
observerWithPid: |
Convenience class method creates and returns an initialized PFObserver object with pid, the target application's BSD Unix process identification number (PID). Provides full observer management.
+ (PFObserver *)observerWithPid:(pid_t)pid;
pidAn integer, the running application's BSD Unix process identification number (PID).
An autoreleased PFObserver object, or nil if the target application is not running.
Use this convenience method or +observerWithName: to create an observer that uses a delegate method instead of a callback method to respond to accessibility notifications.
A client application must call -setDelegate: and -registerForNotification:fromElement:contextInfo: in order to receive notifications.
See the designated initializer, -initWithPid: for important information about creating new observer objects.
See also -initWithPid: and +observerWithName:.
observerWithPid:notificationDelegate:callbackSelector: |
Convenience class method creates and returns an initialized PFObserver object with pid, the target application's BSD Unix process identification number (PID), temporary notification delegate callbackDelegate, and callback selector callback. Provides full observer management.
+ (PFObserver *)observerWithPid:(pid_t)pid notificationDelegate:(id)callbackDelegate callbackSelector:(SEL)callback;
pidAn integer, the running application's BSD Unix process identification number (PID).
callbackDelegateAn object of any type. A client typically passes self in this parameter.
callbackThe notification delegate's Objective-C selector to be invoked when a notification is received.
An autoreleased PFObserver object, or nil if the target application is not running.
Use this method to create an observer for a specific application given its BSD Unix process identification number (PID) and to set up automatic management of the observer, for an observer that uses a callback method instead of a delegate method to respond to accessibility notifications.
See the designated initializer, -initWithPid:notificationDelegate:calbackSelector:, for full information about use of this method.
See also -initWithPath:notificationDelegate:callbackSelector: and +observerWithName:notificationDelegate:callbackSelector:.
pidNumber |
Returns the BSD Unix process identification number (PID) of the receiver's target application.
- (NSNumber *)pidNumber;
An NSNumber object encoding an integer value.
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.
Use NSNumber's -intValue method to extract the integer value of the result.
registerForNotification:fromElement:contextInfo: |
Registers the receiver to observe element for notification, saving contextInfo for return in the client's callback selector, returning YES if successful.
- (BOOL)registerForNotification:(NSString *)notification fromElement:(PFUIElement *)element contextInfo:(void *)contextInfo;
notificationAn NSString representing a notification; you may use a string constant from the NSAccessibility informal protocol or from the accessibility API's AXConstants.h header file cast to NSString*, or the string itself.
elementThe PFUIElement object to observe.
contextInfoAn object, typically of type NSDictionary, containing any information that the receiver's callback method may need at the time the notification is posted. This information is ignored if the client application uses a delegate method instead of a callback method.
YES if the receiver was successfully registered; NO, if not.
Use this method to register to observe a specific UI element in a target application in order to receive notifications that it posts. Alternatively, register to observe the root application element in order to receive notifications posted by all elements in the application. It is often more convenient to observe the root application element, because this ensures that you will receive all of the target application's notifications when any of its elements changes state.
For clients that use a delegate method, the delegate method receives the identifier and full path of the target application file, the notification, the observed element, and the affected element (which may differ from the observed element). For clients that use a callback method, the callback method receives the observer, the notification, the affected element (which may differ from the observed element), and contextInfo in its parameters.
Any one observer is associated with a single client delegate method or callback method no matter how many elements it is registered to observe or how many accessibility notifications it is registered to receive. A delegate method or callback method distinguishes how to respond to different notifications affecting different elements by testing its parameters. See -initWithPid:notificationDelegate:callbackSelector: for the required callback method signature for clients that use a callback method instead of a delegate method.
If the client needs to remember that element is the observed element, it may have to cache element at registration time. This is because the callback method will not necessarily return element as the affected element in every case. This is so, for example, when element is the root application element, because when the root application is observed, the affected element may be some other element.
The client's delegate method or callback method will always receive the affected element, even when observing NSAccessibilityUIElementDestroyedNotification. However, you must treat a destroyed element as invalid; do not pass it as a parameter to methods that call accessibility API functions. You can, however, use a destroyed element with PFUIElement's -pid, and with PFUIElement's -isEqual: and -isEqualToElement: to manage any element cache you maintain. Note that attempting to pass a destroyed UI element in an accessibility API function is not guaranteed to return an accessibility API error. PFUIElement's -elementInfo method will return some valid information about a destroyed element.
Many UI elements do not support every notification known to the accessibility API. If you attempt to register an element for a notification that it does not support, this method returns NO. Use the receiving observer's -isRegisteredForNotification:fromElement: at any time to test whether a particular element is registered for a particular notification; it will always return NO for an element that does not support the specified notification.
It is the client's responsibility to unregister an observer for all notifications before releasing it. This can be done by sending -unregisterForAllNotifications. For convenience, -removeObserversForPid: unregisters all observers for all notifications and releases all observers at once.
See also -unregisterForNotification:fromElement:, -unregisterForAllNotificationsFromElement:, -unregisterForAllNotifications and -isRegisteredForNotification:fromElement:.
registrations |
Returns a mutable array containing all registrations currently in effect in the receiver; that is, all registrations that the client has registered and has not unregistered using this observer.
- (NSMutableArray *)registrations;
An NSMutableArray object containing all registrations currently in effect in the receiving observer.
Each registration in the array is an NSDctionary object containing the registered notification string with key "registrationNotificationKey" and the registered PFUIElement object with key "registrationElementKey".
removeObserversForPid: |
Class method unregisters and removes all observers for the running application whose BSD Unix application process identification number is pid, deallocating them if they have not been retained by the client.
+ (void)removeObserversForPid:(pid_t)pid;
pidAn integer, a running application's BSD Unix process identification number (PID).
This method only unregisters and removes observers that were created using +observerWithName:, +observerWithPid:, +observerWithName:notificationDelegate:callbackSelector: or +observerWithPid:notificationDelegate:callbackSelector:.
See -registerForNotification:fromElement:contextInfo: for information regarding registration and unregistration.
setDelegate: |
Sets the receiver's delegate to object.
- (void)setDelegate:(id <PFObserverDelegate>)object;
objectAn object of any type, or nil to remove an existing delegate.
The delegate must adopt the PFObserverDelegate formal protocol to receive delegate messages.
The delegate method, which is optional, is declared in the PFObserverDelegate protocol. If it is implemented by the delegate, it is automatically called when the receiving observer detects a change in a UI element which its has registered to observe. The delegate must adopt the PFObserverDelegate formal protocol to receive delegate messages.
The only available delegate message is -applicationWithIdentifier:atPath:didPostAccessibilityNotification:fromObservedUIElement:forAffectedUIElement:, which is optional.
The delegate is not retained. To remove a delegate, pass nil.
See also -delegate.
unregisterForAllNotifications |
Unregisters the receiver to observe all elements for all notifications.
- (void)unregisterForAllNotifications;
It is the client's responsibility to unregister the receiving observer for all notifications before releasing it. For convenience, -removeObserversForPid: unregisters all observers for all notifications and releases all observers at once.
See also -registerForNotification:fromElement:contextInfo:, -unregisterForNotification:fromElement:, -unregisterForAllNotificationsFromElement: and -isRegisteredForNotification:fromElement:.
unregisterForAllNotificationsFromElement: |
Unregisters the receiver to observe element for all notifications.
- (void)unregisterForAllNotificationsFromElement:(PFUIElement *)element;
elementThe PFUIElement object being observed.
It is the client's responsibility to unregister the receiving observer for all notifications before releasing it. For convenience, -removeObserversForPid: unregisters all observers for all notifications and releases all observers at once.
See also -registerForNotification:fromElement:contextInfo:, -unregisterForNotification:fromElement:, -unregisterForAllNotifications and -isRegisteredForNotification:fromElement:.
unregisterForNotification:fromElement: |
Unregisters the receiver to observe element for notification.
- (void)unregisterForNotification:(NSString *)notification fromElement:(PFUIElement *)element;
notificationAn NSString representing a notification; you may use a string constant from the NSAccessibility informal protocol or from the accessibility API's AXConstants.h header file cast to NSString*, or the string itself.
elementThe PFUIElement object being observed.
It is the client's responsibility to unregister the receiving observer for all notifications before releasing it. For convenience, -removeObserversForPid: unregisters all observers for all notifications and releases all observers at once.
See also -registerForNotification:fromElement:contextInfo:, -unregisterForAllNotificationsFromElement:, -unregisterForAllNotifications and -isRegisteredForNotification:fromElement:.
Last Updated: Wednesday, May 19, 2010