CorkPboardInterpreter Class Reference
The abstract superclass for all Corkboard interpreter classes. More...
Public Member Functions | |
| (id) | - initWithPasteboard:arguments: |
| The designated initializer. | |
| (BOOL) | - writeToPasteboard: |
| Writes the receiver's represented data to the specified pasteboard. | |
| (id) | - initWithCoder: |
| Decodes and initializes the receiver. | |
| (void) | - encodeWithCoder: |
| Encodes the receiver to the specified coder. | |
| (void) | - dealloc |
| Deallocates the receiver. | |
| (NSData *) | - dataForRepresentedPasteboardType: |
| The data for the given pasteboard type as stored by the receiver. | |
| (void) | - viewDidBecomeAvailable |
| Sent to the receiver when its view becomes available. | |
| (void) | - viewWillBecomeUnavailable |
| Sent to the receiver when its view becomes unavailable. | |
| (IBAction) | - makeViewUnavailable: |
| Removes the receiver's view from Corkboard and potentially makes the receiver eligible for deallocation. | |
| (IBAction) | - redrawView: |
| Tells the view associated with the receiver to redraw. | |
| (NSRect) | - convertRectToHistoryItemView: |
| Transforms a rectangle from the receiver's view's coordinate space to a history item's view's coordinate space. | |
| (void) | - drawContentsInRect: |
| Sent to the receiver when its content needs to be drawn. | |
Static Public Member Functions | |
| (BOOL) | + canInitWithPasteboard:arguments: |
| Whether or not an attempt to instantiate the receiver with the given arguments would succeed. | |
| (NSArray *) | + supportedPasteboardTypes |
| The pasteboard types that the receiver can interpret. | |
| (NSInteger) | + priority |
| The priority, relative to other interpreters, of this class. | |
| (NSString *) | + localizedDisplayName |
| The display name, in the current locale, of the receiver. | |
| (NSImage *) | + icon |
| An icon representing the receiver. | |
Properties | |
| NSView * | view |
| The view associated with the receiver. | |
| NSArray * | supportedPasteboardTypes |
| Simply calls the class method + supportedPasteboardTypes. | |
| NSInteger | priority |
| Simply calls the class method + priority. | |
| NSString * | localizedDisplayName |
| Simply calls the class method + localizedDisplayName. | |
| NSImage * | icon |
| Simply calls the class method + icon. | |
| NSArray * | representedPasteboardTypes |
| The pasteboard types the receiver represents, in order of priority. | |
| NSString * | representedDataDescription |
| A string representing the data stored by the receiver, as provided by the receiver's developer. | |
| NSSet * | promisedFileWrappers |
| File wrappers representing any files promised by the original pasteboard data source. | |
| NSDate * | creationDate |
| The date when the receiver was initialized. | |
| BOOL | isHistoryItem |
| Whether or not the receiver is being displayed in the clipboard history window. | |
| NSSize | preferredViewSize |
| The preferred size of the view representing this pasteboard interpreter. | |
| NSColor * | closeButtonColor |
| The color of the close button used to remove the receiver's view. Unused. | |
| NSString * | accessibilityDescription |
| A textual representation of the data represented by the receiver. | |
Detailed Description
The abstract superclass for all Corkboard interpreter classes.CorkPboardInterpreter is the abstract superclass of your interpreters. You generally create a subclass of CorkPboardInterpreter to handle and display one or more pasteboard datatypes. The class is documented in greater detail in the Corkboard Developer Redbook.
Since Corkboard 1.1, CorkPboardInterpreter has implemented the NSCopying protocol. You should not need to make changes to your plug-ins to support this as it is done through the existing initWithPasteboard:arguments: (CorkPboardInterpreter) method.
- Attention:
- Corkboard will run as a 64-bit process if the system supports it. Your pasteboard interpreters must therefore be compiled for PPC, x86, PPC64, and x86-64 to ensure compatibility. Since Corkboard does not run on Mac OS X 10.4 Tiger or earlier, you need not be concerned with API/ABI issues so long as you use the Mac OS X 10.5 Leopard Target SDK and follow Apple's guidelines for 64-bit programming.
Currently, interpreters execute in the same process as the Corkboard user interface. You should therefore code with performance in mind, as many interpreters may need to run concurrently. Avoid consuming large amounts of memory, spinning the CPU, etc.
In the future, interpreters may be spun off into child processes, sandboxed, or otherwise isolated from the address space of the Corkboard user interface. In such cases, the nature of performance concerns may change.
- See also:
- CorkBufferedPboardInterpreter
- Since:
- CorkCore 1.0
Member Function Documentation
| - (id) initWithPasteboard: | (NSPasteboard *) | pboard | ||
| arguments: | (NSDictionary *) | args | ||
The designated initializer.
- pboard: The pasteboard containing the data to be interpreted.
- args: A dictionary of additional arguments. For more information about keys used by Corkboard, see CorkPboardInterpreter Argument Keys.
- Returns:
- The receiver, an object of the same kind or class, or nil on error.
If your class cannot handle the contents of the pasteboard, release self and return nil; Corkboard will move on to the next available class that claims to handle the available pasteboard data.
- Subclassing considerations:
- Subclasses should override this symbol.
- See also:
- + canInitWithPasteboard:arguments:
- Since:
- CorkCore 1.0
| + (BOOL) canInitWithPasteboard: | (NSPasteboard *) | pboard | ||
| arguments: | (NSDictionary *) | args | ||
Whether or not an attempt to instantiate the receiver with the given arguments would succeed.
- pboard: The pasteboard containing the data to be interpreted.
- args: A dictionary of additional arguments. For more information about keys used by Corkboard, see CorkPboardInterpreter Argument Keys.
The result of this method is used by the Corkboard user interface to present options to the user.
- See also:
- - initWithPasteboard:arguments:
- Since:
- CorkCore 1.0.2
| - (BOOL) writeToPasteboard: | (NSPasteboard *) | pboard |
Writes the receiver's represented data to the specified pasteboard.
- pboard: The pasteboard where the receiver's represented data is to be written.
- Returns:
- Whether or not the receiver was successfully written.
If you do need to override this method (e.g. to write some user-generated state information), do not forget to call -[super writeToPasteboard:] to write the primary pasteboard data. Remember that interpreters represent the original data; they are not editors. Be sure you need additional state before overriding.
- Since:
- CorkCore 1.0
| - (id) initWithCoder: | (NSCoder *) | aDecoder |
Decodes and initializes the receiver.
- aDecoder: The decoder used during initialization.
- Returns:
- The receiver, an object of the same kind or class, or nil on error.
If you do need to override this method (e.g. to read some user-generated state information), do not forget to call -[super initWithCoder:] to retrieve the primary pasteboard data. Remember that interpreters represent the original data; they are not editors. Be sure you need additional state before overriding.
If the user deletes the plug-in containing your subclass, or the subclass otherwise becomes unavailable, Corkboard will attempt to use another class to display the pasteboard data encoded by aDecoder.
- Since:
- CorkCore 1.0
| - (void) encodeWithCoder: | (NSCoder *) | aCoder |
Encodes the receiver to the specified coder.
- aCoder: The coder used during encoding. The coder must allow keyed coding.
If you do need to override this method (e.g. to write some user-generated state information), do not forget to call -[super encodeWithCoder:] to write the primary pasteboard data. Remember that interpreters represent the original data; they are not editors. Be sure you need additional state before overriding.
If the user deletes the plug-in containing your subclass, or the subclass otherwise becomes unavailable, Corkboard will attempt to use another class to display the encoded pasteboard data when it comes time to decode the receiver.
- Since:
- CorkCore 1.0
| - (void) dealloc |
Deallocates the receiver.
- Warning:
- After this method returns, the receiver is no longer a valid object.
- Since:
- CorkCore 1.0
| + (NSArray *) supportedPasteboardTypes |
The pasteboard types that the receiver can interpret.
- Returns:
- An array of pasteboard types, or nil on error.
- Subclassing considerations:
- Subclasses should override this symbol.
- See also:
- @property supportedPasteboardTypes
- Since:
- CorkCore 1.0
| + (NSInteger) priority |
The priority, relative to other interpreters, of this class.
- Returns:
- The priority of the class, or 0 on error.
You do not need to override this method to get this functionality. Instead, you can provide an integer or real value for the CorkPboardInterpreterPriority key of your class's info dictionary in your bundle's Info.plist. For more information on Corkboard's Info.plist additions, see the developer documentation at the Corkboard website.
- Attention:
- To ensure consistency across 32-bit and 64-bit environments, this value is always only 32 bits wide. The value is clamped to 32-bit values on 64-bit Mac OS X. This means that, if the value is greater than INT32_MAX, Corkboard will treat it as if it were INT32_MAX; if the value is less than INT32_MIN, Corkboard will treat it as if it were INT32_MIN.
- See also:
- @property priority
- Since:
- CorkCore 1.0
| + (NSString *) localizedDisplayName |
The display name, in the current locale, of the receiver.
- Returns:
- A string representing the receiver's localized display name.
You do not need to override this method to get this functionality. Instead, you can provide a string value for the CorkPboardInterpreterDisplayName key of your class's info dictionary in your bundle's Info.plist. The display name can be localized in your bundle's InfoPlist.strings file.
- See also:
- Corkboard Developer Redbook for information on Corkboard's Info.plist additions.
@property localizedDisplayName
- Since:
- CorkCore 1.0
| + (NSImage *) icon |
An icon representing the receiver.
- Returns:
- An icon representing the receiver, suitable for display to the user.
- See also:
- @property icon
- Since:
- CorkCore 1.0
| - (NSData *) dataForRepresentedPasteboardType: | (NSString *) | type |
The data for the given pasteboard type as stored by the receiver.
- type: The pasteboard type whose data you want.
- Returns:
- The data for the given pasteboard type as stored by the receiver.
- See also:
- @property representedPasteboardTypes
- Since:
- CorkCore 1.0
| - (void) viewDidBecomeAvailable |
Sent to the receiver when its view becomes available.
This message is sent to a pasteboard interpreter once the associated view is set and assigned to a superview. Think of it as the equivalent of the -awakeFromNib message. The default implementation does nothing.
- Warning:
- If the receiver is executing in a sandbox, this message will not be sent.
- Since:
- CorkCore 1.0
| - (void) viewWillBecomeUnavailable |
Sent to the receiver when its view becomes unavailable.
This message is sent to a pasteboard interpreter just before the associated view is removed from its superview and becomes eligible for deallocation. The view is still available at this point, but will be destroyed soon. The default implementation does nothing.
- Warning:
- If the receiver is executing in a sandbox, this message will not be sent.
- Since:
- CorkCore 1.0
| - (IBAction) makeViewUnavailable: | (id) | sender |
Removes the receiver's view from Corkboard and potentially makes the receiver eligible for deallocation.
- sender: The object that sent this message.
- Warning:
- If the receiver is executing in a sandbox, this action may need to be confirmed by the user before it proceeds.
- Since:
- CorkCore 1.0
| - (IBAction) redrawView: | (id) | sender |
Tells the view associated with the receiver to redraw.
- sender: The object that sent this message.
- Warning:
- You should not simply tell the receiver's view to display, as the view may not be available if the receiver is sandboxed.
- Since:
- CorkCore 1.0
| - (NSRect) convertRectToHistoryItemView: | (NSRect) | rect |
Transforms a rectangle from the receiver's view's coordinate space to a history item's view's coordinate space.
- rect: The rectangle to transform.
- Returns:
- The transformed rectangle. Even if the receiver does not represent an item in the clipboard history, the rectangle is still transformed.
- See also:
- CorkGetHistoryItemSize()
- Since:
- CorkCore 1.1
| - (void) drawContentsInRect: | (NSRect) | rect |
Sent to the receiver when its content needs to be drawn.
- rect: The rectangle that has been invalidated. Drawing operations are clipped to this rectangle.
- Attention:
- Drawing can be performed using Cocoa or Quartz; since you need to compile your subclasses for both 32-bit and 64-bit, you cannot use QuickDraw.
By default, this method fills rect with white so that the user can see the view, but does nothing otherwise.
- Subclassing considerations:
- Subclasses should override this symbol.
- See also:
- CorkBufferedPboardInterpreter
- Since:
- CorkCore 1.0
Property Documentation
- (NSView*) view [read, assign] |
The view associated with the receiver.
This method may return nil if it is called before - viewDidBecomeAvailable has been sent to the receiver, or if it is called after - viewWillBecomeUnavailable has been sent to the receiver. You do not need to override it; doing so will not replace the view displayed by the Corkboard UI.
- Warning:
- Do not rely on the bounds or frame properties of the view for the appropriate size of your content; use the receiver's preferredViewSize property instead. The dimensions of the receiver's view may not relate directly to the size of your content.
- Attention:
- If the receiver is executing in a sandbox, this message will always return nil.
- Since:
- CorkCore 1.0
- (NSArray*) supportedPasteboardTypes [read, assign] |
Simply calls the class method + supportedPasteboardTypes.
- Returns:
- The value of the class method + supportedPasteboardTypes. This property is provided for convenience; since it calls through to + supportedPasteboardTypes, if you need to override this property, you would typically override that method instead.
- See also:
- + supportedPasteboardTypes (class method)
- Since:
- CorkCore 1.0
- (NSInteger) priority [read, assign] |
Simply calls the class method + priority.
- Returns:
- The value of the class method + priority. This property is provided for convenience; since it calls through to + priority, if you need to override this property, you would typically override that method instead.
- See also:
- + priority (class method)
- Since:
- CorkCore 1.0
- (NSString*) localizedDisplayName [read, assign] |
Simply calls the class method + localizedDisplayName.
- Returns:
- The value of the class method + localizedDisplayName. This property is provided for convenience; since it calls through to + localizedDisplayName, if you need to override this property, you would typically override that method instead.
- See also:
- + localizedDisplayName (class method)
- Since:
- CorkCore 1.0
- (NSImage*) icon [read, assign] |
- (NSArray*) representedPasteboardTypes [read, assign] |
The pasteboard types the receiver represents, in order of priority.
An instance of an interpreter class automatically copies out all the data from the pasteboard used in its instantiation, then later writes that data to a pasteboard when the instance is to be transmitted outside of Corkboard or to disk. This preserves the precise state of that original pasteboard as closely as possible. This property simply lists the types of data that have been copied from that pasteboard.
For example, if the instance were created with a pasteboard containing data of NSStringPboardType and NSURLPboardType, this method would return an array containing NSStringPboardType and NSURLPboardType. The order of types matches the order of types returned by the initializing pasteboard's -types method.
- See also:
- - dataForRepresentedPasteboardType:
- Since:
- CorkCore 1.0
- (NSString*) representedDataDescription [read, assign] |
A string representing the data stored by the receiver, as provided by the receiver's developer.
In Corkboard 1.x, this property is used with Corkboard's developer information. In Corkboard 2.0 and newer, it is also used as the interpreter instance's input when the user performs a search. You can return a string representing the data you're interpreting, and it will be compared against the user's search terms. By default, the value is nil (indicating no searchable content.)
- See also:
- @property representedPasteboardTypes
- Since:
- CorkCore 1.0
- (NSSet*) promisedFileWrappers [read, assign] |
File wrappers representing any files promised by the original pasteboard data source.
Corkboard resolves file promises for you automatically. This property provides access to those files. If no files were promised or the promised files could not be resolved, the value of this property will be nil.
Not available on iPhone OS. The NSFileWrapper class does not exist on iPhone OS.
- Since:
- CorkCore 1.0.1
- (NSDate*) creationDate [read, assign] |
The date when the receiver was initialized.
Corkboard records the date and time of initialization of an interpreter instance for display to the user in some situations. In the case of archived objects, the date is maintained across encoding and decoding. In the case of copied objects, the date is not copied and the copy is assigned a new date based on the moment in time when it was allocated.
- Attention:
- Prior to Corkboard 1.1, the creation date of an interpreter instance was not recorded. Therefore, if the receiver was originally created in a version of Corkboard prior to 1.1, this value is equal to [NSDate distantPast].
- Since:
- CorkCore 1.1
- (BOOL) isHistoryItem [read, assign] |
Whether or not the receiver is being displayed in the clipboard history window.
The clipboard history maintains a list of recent data copied to the clipboard in the form of interpreter instances. The window for the clipboard history is compact and allots a fixed amount of space to each interpreter instance's view. You may wish to change how you draw your content to match the smaller space.
- Since:
- CorkCore 1.2
- (NSSize) preferredViewSize [read, assign] |
The preferred size of the view representing this pasteboard interpreter.
By default, this method simply returns the constant size {32.0, 32.0}. To change this value, override the getter for this property.
- Since:
- CorkCore 1.0
- (NSColor*) closeButtonColor [read, assign] |
The color of the close button used to remove the receiver's view. Unused.
Interpreter instances' views are removed from the Corkboard window by clicking a button positioned near their top left corners. These buttons can be assigned a default color by the user, but interpreter instances may choose to assign their own custom color to the close button. By default, the value is nil, indicating the user's default close button color should be used. To change this value, override the getter for this property.
- Attention:
- The color of a close button should not be the only way data is presented, as not all users can see it and it is not always visible anyway.
This property is ignored in Corkboard 1.1 and later.
- Since:
- CorkCore 1.0
- Deprecated:
- CorkCore 1.1
- (NSString*) accessibilityDescription [read, assign] |
A textual representation of the data represented by the receiver.
To ensure accessibility for visually impaired users, Corkboard consults this property to help them determine what data is available to them. By default, the value of the property is nil. It is strongly recommended that, wherever possible, you override the getter for this property to return a localized, textual description of the data represented by the receiver.
- Subclassing considerations:
- Subclasses should override this symbol.
- Since:
- CorkCore 1.0
The documentation for this class was generated from the following file: