DockyardPreferences Additions

Dockyard > Objective-C Classes > DockyardPreferences Additions

DockyardPreferences Additions

Class Description

Allows the `rearrange` message to be used as an IBAction.
Allows DockyardPreferences to be used in a widget by implementing some simple WebKit methods.
This is the central managing class for the entire Dockyard back end, and should be included in any executable that uses Dockyard. All Dockyard-wide defaults and settings, including the Docks themselves, should be accessed through this class, which will automatically synchronize itself with any other instance of DockyardPreferences running. This is very useful when using both the Manager and the menu extra, for example.

By Belkadan Software

Methods

+ isKeyExcludedFromWebScript:

+ isSelectorExcludedFromWebScript:

- updateNames:

+ webScriptNameForSelector:

Initializing DockyardPreferences

- initWithIdentifier:

Saving data

- update

Setting the delegate

- delegate

- setDelegate:

Setting Dockyard-specific defaults

- defaultsValueForKey:

- setDefaultsValue:forKey:

Getting dock names and information

- currentDock

- dockNames

- numberOfDocks

- setDockNames:

Enabling Dashboard switching

- setShouldSwitchDashboard:

- shouldSwitchDashboard

Getting dock information

- dashboardDataForDockWithName:

- dashboardDataForDocks

- dataForDockWithName:

- dataForDocks

Modifying dock contents

- addItem:toSet:ofDock:

- addItemWithData:toSet:ofDock:

- addItemsWithData:toSet:ofDock:

- addURL:withLabel:toDock:

- itemsInSet:ofDock:

- moveItemAtIndex:toIndex:inSet:ofDock:

- moveItemsAtIndexes:toIndex:inSet:ofDock:

- removeItemAtIndex:fromSet:ofDock:

- removeItemsAtIndexes:fromSet:ofDock:

- setItems:inSet:ofDock:

Creating and deleting docks

- createDockWithName:data:dashboardData:

- createDockWithName:fromFile:dashboardFile:

- createDocksWithNames:data:dashboardData:

- deleteDockAtIndex:

- deleteDockWithName:

- deleteDocksAtIndexes:

Renaming and reordering docks

- rearrange

- renameDock:to:

Switching docks

- changeDock:

Method Detail

isKeyExcludedFromWebScript:

+ (BOOL)isKeyExcludedFromWebScript:(constchar *)key

Limits the widget to three properties: `currentDock`, `dockNames`, and `shouldSwitchDashboard`.

isSelectorExcludedFromWebScript:

+ (BOOL)isSelectorExcludedFromWebScript:(SEL)sel

Limits the widget to three methods: `currentDock`, `dockNames`, `renameDock:to:`, and `changeDock:`. Anything else has to go through DockyardPlugin first.

webScriptNameForSelector:

+ (NSString *)webScriptNameForSelector:(SEL)sel

Changes Objective-C selectors into JavaScript method names: `changeDock:` becomes `changeDock` (no colon), and `renameDock:to:` becomes `renameDock`.

addItem:toSet:ofDock:

- (BOOL)addItem:(NSString *)path toSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Adds the item at `path` to the specified item set (applications, items, or widgets) of the specified dock. Returns `YES` if the item was added successfully, `NO` if not. WARNING: adding items to the widget set (DockyardWidgetSet) is not yet supported!

See also: addURL:withLabel:toDock:, addItemWithData:toSet:ofDock:, addItemsWithData:toSet:ofDock:

addItemWithData:toSet:ofDock:

- (BOOL)addItemWithData:(NSDictionary *)data toSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Adds the item specified in `data` to the specified item set (applications, items, or widgets) of the specified dock. `data` must be in the proper format for its item set. This means it must work as a member of the "persistent-apps," "persistent-others," or "layer-gadgets" arrays in Apple's dock and dashboard defaults. Returns `YES` if the item was added successfully, `NO` if not.

See also: addItem:toSet:ofDock:, addURL:withLabel:toDock:, addItemsWithData:toSet:ofDock:

addItemsWithData:toSet:ofDock:

- (BOOL)addItemsWithData:(NSArray *)data toSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Adds the items specified in `data` to the specified item set (applications, items, or widgets) of the specified dock. The members of `data` must be NSDictionaries in the proper format for the given item set. This means they must work as a member of the "persistent-apps," "persistent-others," or "layer-gadgets" arrays in Apple's dock and dashboard defaults. Returns `YES` if the items were added successfully, `NO` if not.

See also: addItem:toSet:ofDock:, addURL:withLabel:toDock:, addItemWithData:toSet:ofDock:

addURL:withLabel:toDock:

- (BOOL)addURL:(NSURL *)url withLabel:(NSString *)label toDock:(NSString *)dockName

Adds the specified URL to the item set of the specified dock, using `label` as the item title. Returns `YES` if the item was added successfully, `NO` if not.

See also: addItem:toSet:ofDock:, addItemWithData:toSet:ofDock:, addItemsWithData:toSet:ofDock:

changeDock:

- (BOOL)changeDock:(NSString *)newDock

Changes to the dock named `newDock`. This is the most important method in the entire Dockyard library, and perhaps one of the simplest to invoke. Returns `YES` if the dock was changed, `NO` if not.

createDockWithName:data:dashboardData:

- (BOOL)createDockWithName:(NSString *)name data:(NSDictionary *)dockData dashboardData:(NSDictionary *)dashboardData

Creates a dock with the specified name, using the data from `dockData`, and, if provided, the dashboard data from `dashboardData`. `dashboardData` is optional...pass `nil` to avoid setting any dashboard data for this dock. Make sure that the data dictionaries are in the same format as the Apple defaults domains "com.apple.dock" and "com.apple.dashboard". This is the preferred way to create docks if you have the data. Returns `YES` if the dock was created, `NO` if not.

See also: createDockWithName:fromFile:dashboardFile:, createDocksWithNames:fromData:dashboardData:

createDockWithName:fromFile:dashboardFile:

- (BOOL)createDockWithName:(NSString *)name fromFile:(NSString *)dockPath dashboardFile:(NSString *)dashboardPath

Creates a dock with the specified name, using the data from the file at `dockPath`, and, if provided, the dashboard data from the file at `dashboardPath`. `dashboardPath` is optional...pass `nil` to avoid setting any dashboard data for this dock. Make sure that the files at each path are in the same format as the Apple defaults domains "com.apple.dock" and "com.apple.dashboard". This is the preferred way to create docks if all you have is a file path. Returns `YES` if the dock was created, `NO` if not.

See also: createDockWithName:fromData:dashboardData:, createDocksWithNames:fromData:dashboardData:

createDocksWithNames:data:dashboardData:

- (BOOL)createDocksWithNames:(NSArray *)dockNames data:(NSArray *)dockData dashboardData:(NSArray *)dashboardData

Creates docks with the specified names, using the data from `dockData`, and, if provided, the dashboard data from `dashboardData`. There must be the same number of items in all three arrays. To avoid setting dashboard data for a particular dock, use an instance of NSNull as a placeholder. Make sure that each data dictionary element is in the same format as the Apple defaults domains "com.apple.dock" or "com.apple.dashboard". This is the preferred way to create multiple docks. Returns `YES` if every dock was created, `NO` if not. Note that if only some docks are created, this method will return `NO`.

See also: createDockWithName:fromFile:dashboardFile:, createDockWithName:fromData:dashboardData:

currentDock

- (NSString *)currentDock

Returns the name of the current dock.

See also: dockNames

dashboardDataForDockWithName:

- (NSDictionary *)dashboardDataForDockWithName:(NSString *)name

Returns the dictionary containing the dashboard data for the dock named `name`. This is in the same format as the defaults domain "com.apple.dashboard". This dictionary is not copied because of memory issues, and may be modified by DockyardPreferences, so do not save it anywhere without copying yourself. Instead, call this method again when you need it.

See also: itemsInSet:ofDock:

dashboardDataForDocks

- (NSDictionary *)dashboardDataForDocks

Returns the dictionary containing all of the dashboard data, organized by dock name. This dictionary is not copied because of memory issues, and may be modified by DockyardPreferences, so do not save it anywhere. It is better to get the data specifically using `dashboardDataForDockWithName:` or `itemsInSet:ofDock:`.

dataForDockWithName:

- (NSDictionary *)dataForDockWithName:(NSString *)name

Returns the dictionary containing the dock data for the dock named `name`. This is in the same format as the defaults domain "com.apple.dock". This dictionary is not copied because of memory issues, and may be modified by DockyardPreferences, so do not save it anywhere without copying yourself. Instead, call this method again when you need it.

See also: itemsInSet:ofDock:

dataForDocks

- (NSDictionary *)dataForDocks

Returns the dictionary containing all of the dock data, organized by dock name. This dictionary is not copied because of memory issues, and may be modified by DockyardPreferences, so do not save it anywhere. It is better to get the data specifically using `dataForDockWithName:` or `itemsInSet:ofDock:`.

defaultsValueForKey:

- (id)defaultsValueForKey:(NSString *)key

Provides access to Dockyard defaults by returning the value associated with `key`. This is useful for accessing defaults that affect other aspects of Dockyard besides the dock items themselves.

delegate

- (id)delegate

Returns the preferences' delegate.

deleteDockAtIndex:

- (BOOL)deleteDockAtIndex:(unsigned)index

Removes the dock at the specified index. Returns `YES` if the deletion was successful, `NO` if not. This is the preferred way to delete a dock if you its position in the list of docks.

See also: deleteDockWithName:, deleteDocksAtIndexes:

deleteDockWithName:

- (BOOL)deleteDockWithName:(NSString *)name

Removes the dock called `name`. Returns `YES` if the deletion was successful, `NO` if not. This is the preferred way to delete a dock if all you know is its name.

See also: deleteDockAtIndex:, deleteDocksAtIndexes:

deleteDocksAtIndexes:

- (BOOL)deleteDocksAtIndexes:(NSIndexSet *)indexSet

Removes the dock at the specified indexes. Returns `YES` if the deletion was successful, `NO` if not. Note that if any one of the docks cannot be deleted, this method will return `NO`. This is the preferred way to delete multiple docks.

See also: deleteDockWithName:, deleteDockAtIndex:

dockNames

- (NSArray *)dockNames

Returns the list of docks currently in use. This list is sorted by user preference.

See also: setDockNames:

initWithIdentifier:

- (id)initWithIdentifier:(NSString *)givenID

Creates a new instance of DockyardPreferences. The identifier is currently unused, but may be in the future. It is recommended that each executable's instance of DockyardPreferences have its own identifier, but this is not possible when encoded in a nib file.

itemsInSet:ofDock:

- (NSArray *)itemsInSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Returns the items in the specified item set of the specified dock. The returned array is in the form of "persistent-apps", "persistent-others", or "layer-gadgets" from Apple's defaults, depending on which item set is asked for. This is the preferred way to retrieve dock items, but the result is not a copy due to memory issues. Because it may be modified later by DockyardPreferences, it is better to call this method again whenever needed, rather than retaining the result.

See also: setItems:inSet:ofDock:

moveItemAtIndex:toIndex:inSet:ofDock:

- (int)moveItemAtIndex:(unsigned)sourceIndex toIndex:(unsigned)destIndex inSet:(enum DockyardItemSet)whichItems ofDock:(NSString *)name

Moves the item at `sourceIndex` to `destIndex`. `whichItems` can be the dock applications, dock items, or dashboard widgets of the dock named `name`. If you are moving more than one item to the same index, `moveItemsAtIndexes:toIndex:inSet:ofDock:` is more efficient. The returned value is the index of the item after it has been moved, or -1 if it could not be moved.

See also: moveItemsAtIndexes:toIndex:inSet:ofDock:

moveItemsAtIndexes:toIndex:inSet:ofDock:

- (int)moveItemsAtIndexes:(NSIndexSet *)indexSet toIndex:(unsigned)destIndex inSet:(enum DockyardItemSet)whichItems ofDock:(NSString *)name

Moves the items at `sourceIndex` to `destIndex`. `whichItems` can be the dock applications, dock items, or dashboard widgets of the dock named `name`. If you are moving only one item to the destination index, `moveItemAtIndex:toIndex:inSet:ofDock:` is more efficient. The returned value is the index of the first item after it has been moved, or -1 if it could not be moved.

See also: moveItemAtIndex:toIndex:inSet:ofDock:

numberOfDocks

- (unsigned)numberOfDocks

Returns the number of docks currently in use.

rearrange

- (BOOL)rearrange

Informs the receiver that a rearrangement has taken place. Unlike the other dock-modifying commands, this method actually takes no action besides synchronizing the new arrangement with other executables. This method should be called after calling `setDockNames:` in order to make the changes affect all instances of DockyardPreferencs. These methods are not combined into one because of the cost involved -- synchronizing during every drag and drop is too memory-intensive. Returns `YES` if the rearrangment was successful, `NO` if not.

See also: setDockNames:

removeItemAtIndex:fromSet:ofDock:

- (void)removeItemAtIndex:(unsigned)index fromSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Removes the item at `index` from the specified item set of the specified dock. If you are removing more than one item, `removeItemsAtIndexes:fromSet:ofDock:` is more efficient.

See also: removeItemsAtIndexes:fromSet:ofDock:

removeItemsAtIndexes:fromSet:ofDock:

- (void)removeItemsAtIndexes:(NSIndexSet *)indexSet fromSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Removes the items at `indexSet` from the specified item set of the specified dock. If you are only removing one item, `removeItemAtIndex:fromSet:ofDock:` is more efficient.

See also: removeItemAtIndex:fromSet:ofDock:

renameDock:to:

- (BOOL)renameDock:(NSString *)oldName to:(NSString *)newName

Renames the dock named `oldName` to `newName`. Returns `YES` if the renaming was successful, `NO` if not. No two docks can have the same name.

setDefaultsValue:forKey:

- (void)setDefaultsValue:(id)value forKey:(NSString *)key

Provides access to Dockyard defaults by setting `value` as the value of `key`. This is useful for setting defaults that affect other aspects of Dockyard besides the dock items themselves. Note that the keys `"docks"`, `"dashboards"`, `"dockNames"`, `"currentDock"`, `"shouldSwitchDashboard"`, and `"dockData"` are reserved for private use by Dockyard. It is a good idea to follow the Dockyard naming convention of "Application:specificKey" for all custom defaults keys. This avoids potential collisions.

setDelegate:

- (void)setDelegate:(id)newDelegate

Sets the preferences' delegate. The delegate will receive all of the notifications sent out by DockyardPreferences. However, the preferences instance is guaranteed to have updated itself before forwarding any notifications, making sure that its delegate will have updated data to work with. Note that any object other than the delegate will not have this guarantee, and should take caution when requesting information from the preferences during a notification post.

setDockNames:

- (void)setDockNames:(NSArray *)newNames

Sets the list of names of docks currently in use to `newNames`. This method should ALWAYS contain either the same number of docks as before, or have less because of a drag in progress. Do not use this method in code if possible -- it is provided for Key-Value Coding and Cocoa Bindings.

See also: dockNames, rearrange

setItems:inSet:ofDock:

- (void)setItems:(NSArray *)dockItems inSet:(enum DockyardItemSet)itemSet ofDock:(NSString *)dockName

Sets the items in the specified item set of the specified dock to `dockItems`. This MUST be in the form of "persistent-apps", "persistent-others", or "layer-gadgets" from Apple's defaults (depending on the item set being modified), or previously copied from `itemsInSet:ofDock`.

See also: itemsInSet:ofDock:

setShouldSwitchDashboard:

- (void)setShouldSwitchDashboard:(BOOL)newShouldSwitch

Sets whether or not Dashboard switching is enabled.

See also: shouldSwitchDashboard

shouldSwitchDashboard

- (BOOL)shouldSwitchDashboard

Returns `YES` if Dashboard switching is enabled, `NO`otherwise.

See also: setShouldSwitchDashboard:

update

- (void)update

Forces the preferences to synchronize with NSUserDefaults and the hard disk. This does NOT synchronize with other executables currently running Dockyard. All methods that change preferences data automatically call this method, so you should never need to call it directly.

updateNames:

- (IBAction)updateNames:(id)sender

Forwards the message to `rearrange`.

See also: DockyardPreferences.rearrange

This page was generated with DocYouMeant, a program created by Belkadan Software