- Declared In:
- WTool.h
There's a nib for each tool, with the file's owner being the WTool controller.
A WTool is released when its window is closed. Otherwise, it will stay "awake" (but deselected) if a tool is chosen to replace it in a window.
A tool uses lots of stuff in the info plist, (which default to "string" type in this list):
| CFBundleGetInfoString | Tooltip description of tool; also used in Install Tools list [LOCALIZED] |
| CFBundleIconFile | Name of tool's icon in the bundle |
| CFBundleIdentifier | in form of com.domain.project; a unique identifier for a tool, not visible to user. |
| CFBundleName | Full name of tool to display in Toolbox menu and in toolbar configuration [LOCALIZED] |
| CFBundleVersion | version number -- SHOULD BE NUMERIC for version comparison! |
| CFBundleShortVersionString | version string for about box, essentially same as above. [LOCALIZED] |
| NSHumanReadableCopyright | copyright statement for about panel [LOCALIZED] |
| NSMainNibFile | name of nib file to load |
| NSPrincipalClass | The principal class conforming to the WTool protocol |
| ToolFrequency | (integer) Number of seconds between periodic reloads. 0 = not periodic. [OPTIONAL] |
| ToolHomePage | Home page of tool [OPTIONAL] |
| ToolHomePageName | of Home page of tool [OPTIONAL, will use CFBundleName] |
| ToolLabel | Label to display on toolbar [LOCALIZED] [OPTIONAL: will use CFBundleName] |
| ToolUsesMoreButton | Boolean of whether "More" button should be shown on status bar. [OPTIONAL: defaults to NO.] |
In writing new tools, you should try to keep the look and feel consistent with the existing tools. For instance, list and table views should use Helvetica 13 as their main font, not the default Lucida Grande. For tables that can add more results to their lists, put a "More Results" little button (this is hard to do in IB; turn off the border to set the height and then turn it back on) on the left in a placard using PlacardScrollView or under the table if there is no horizontal scroll bar.
Be sure to take advantage of the classes and categories defined in GeneralTool's framework to increase consistency and simplify the programming job.
Synopsis:
LocalizedStringInThisBundle(key, comment)
Description:
Macro to get a localized string associated with the tool bundle
Methods dealing with creation, selection, and deselection of a toolBuilt-in periodic events
- - wakeupBundle:toolbox:
- - initialFirstResponder
- - needsConfiguration
- - toolSelected
- - toolDeselected
Views and drawers
- - toolPeriodic
Selection opening and saving
- - configurationDrawer
- - detailDrawer
- - mainView
Filling menus
- - canOpenSelection
- - canSaveSelection
- - openSelection:
- - selectedItemName
- - selectedItemExtension
- - saveSelectedItemToPath:hideExtension:
1.5 and later, for more results or stop
- - multiParsers
- - addHomePagesToDictionary:
- - loadMore
- - stopLoading
- (void)addHomePagesToDictionary:(NSMutableDictionary *)inDictionary
Add any home pages and their URLs to the list which will be sorted and inserted in the Tool menu. If there is just one home page, it can be specified in the property dictionary of the tool. If there is any MultiParser associated with the tool, they are added in for you. So this is an opportunity to add other home pages via code. The key is the name to display; the value is the actual URL. New as of version 1.1.
- (BOOL)canOpenSelection
Whether there is an "openable" item selected or not, to control "Open Selected Item" menu.
- (BOOL)canSaveSelection
Whether there is an "saveable" item selected or not, to control "Save Selected Item To..." menu.
- (id)configurationDrawer
Return any configuration drawer, which opens on the right side. Return nil if none.
- (id)detailDrawer
Drawer to place into detail drawer, which opens on the bottom. Return nil if none.
- (id)initialFirstResponder
return the initial first responder to be set when the tool becomes active, or nil if none is to be explicitly set.
- (void)loadMore
Load more results, as a result of clicking the "More" button. New as of version 1.5.
- (id)mainView
Return the main view to install into window. The view should be 595x360 and may grow to be larger.
- (NSArray *)multiParsers
Return an array containing each Multiparser associated with the tool, or nil. This is used to populate the menu for selecting which sites to connect to. New as of version 1.1.
- (BOOL)needsConfiguration
Sent after wakeup, this method returns YES if the configuration drawer should be opened automatically because it should be configured before the tool can really work. (The tool should also disable any UI that doesn't make sense until configuration is entered.)
- (IBAction)openSelection:(id)sender
Open or view whatever item is selected in an external program. It might download something and then open a web page, preview, etc. Should do the same as when user double-clicks on an item in a list or viewer.
- (BOOL)saveSelectedItemToPath:(NSString *)inPath hideExtension:(BOOL)inHideExtension
Save whatever item is selected to the given file path. User has chosen "Save Selected Item To..." and already chosen a path. Client should pay attention to inHideExtension, use [[NSFileManager defaultManager] createFileAtPath:contents:attributes:], and [[NSWorkspace sharedWorkspace] noteFileSystemChanged:].
- (NSString *)selectedItemExtension
Return dot-extension for selected item.
- (NSString *)selectedItemName
Return name (suitable for a file name) of any selected item, for use by "Save Selected Item To..." menu item. Does not return a file extension.
- (void)stopLoading
Stop loading things, as a result of clicking the "Stop" button. New as of version 1.5.
- (void)toolDeselected
Tool is going away (but may come back). Should stop loading in progress.
- (NSString *)toolPeriodic
Sent by owner for periodic updating of the display. Not sent until the tool is woken up. If returns a non-nil string, the dock will flash and the user will be notified with the string.
- (void)toolSelected
Tool selected, or re-selected. Maybe useful for setting first responder status, or for grabbing latest data if tool is made visible after being invisible.
- (BOOL)wakeupBundle:(NSBundle *)inBundle toolbox:(WToolbox *)inToolbox
Passed in reference to bundle and to WToolbox object. Possibly load preferences, possibly connect to server. Initialize the view when first loaded, only called once. This is invoked after awakeFromNib so simple UI hookups can be performed in that method if desired. The UI is not displayed until after this method is invoked.