UKToolbarFactory.h

   1 //
   2 //  UKToolbarFactory.h
   3 //  UKToolbarFactory
   4 //
   5 //  Created by Uli Kusterer on Sat Jan 17 2004.
   6 //  Copyright (c) 2004 M. Uli Kusterer. All rights reserved.
   7 //
   8
   9 /*
  10         PURPOSE:
  11         Easily add toolbars to windows in your application.
  12
  13         DIRECTIONS:
  14         To use UKToolbarFactory, drag this header file into your NIB file's window.
  15         Now you'll be able to instantiate a UKToolbarFactory object in your NIB.
  16         Hook up the UKToolbarFactory's "owner" outlet with the NSWindow on which you
  17         want a toolbar. Make sure you have specified an "Autosave name" for the
  18         NSWindow (e.g. "MainWindow").
  19
  20         Now create a file that is named with your application's bundle identifier
  21         (e.g. "com.mycompany.myapplication"), followed by a period, the autosave
  22         name of the NSWindow and ".plist"
  23         (e.g. "com.mycompany.myapplication.MainWindow.plist").
  24
  25         In this file you can now define the toolbar items that will be available in
  26         your window's toolbar. The file must contain a dictionary of item
  27         definition dictionaries under the key "Items". These item definition
  28         dictionaries are stored under the item identifier as the key. The actual
  29         item definition dictionary contains the following keys (all strings):
  30
  31         Action  -   The selector to call on the first responder when this item is
  32                                 clicked, e.g. "close:" or "print:" or "myCustomIBAction:".
  33         Label   -   The label to display under the toolbar item in the toolbar.
  34         CustomizationLabel -
  35                                 An alternate label to be displayed in the "Customize toolbar"
  36                                 window for this item. This can be more detailed. If this isn't
  37                                 present, the "Label" will be used here as well.
  38         ToolTip -   The tool tip to display when the mouse is over this item in the
  39                                 toolbar. If this isn't specified, no tooltip is shown.
  40     ViewClass - If specified, this is the name of an NSView subclass from which
  41                 an object will be created and shown instead of an icon. If the
  42                 view is an NSSearchField or similar class, this will also set
  43                 its placeholder string to the label of the item.
  44     MaxWidth -  The maximum width for a view-based item. Must be provided if
  45                 ViewClass is specified.
  46     MinWidth -  The minimum width for a view-based item. Must be provided if
  47                 ViewClass is specified.
  48
  49         The image to be used for the toolbar item must have the item identifier as
  50         its name (plus any filename extension needed to indicate the image file's
  51         type, e.g. ".tiff").
  52
  53         The file must also contain an array under the key "DefaultItems", which
  54         contains the list of item identifiers to be displayed in this toolbar by
  55         default. Apart from the identifiers in this file, you can also specify
  56         the identifiers defined by Apple, i.e. NSToolbarSeparatorItem,
  57         NSToolbarSpaceItem, NSToolbarFlexibleSpaceItem, or NSToolbarCustomizeToolbar,
  58         which are automatically added to the list of allowed items.
  59
  60         If you want to allow NSToolbarShowColorsItem, NSToolbarShowFontsItem, or
  61         NSToolbarPrintItem, you have to explicitly add them to the "Items" dictionary
  62         or they won't show up in the customization sheet. You needn't specify any
  63         actions, labels or tool tips for them, though.
  64
  65     To support selectable items, you have to provide an "Options" dictionary and
  66     provide a "Selectable" entry, which should be an NSBoolean set to YES. This
  67     will make all non-view items in the toolbar selectable, and will make sure
  68     the last one clicked is selected.
  69
  70         To enable/disable toolbar items as needed, implement
  71                 -(BOOL) validateToolbarItem: (NSToolbarItem*)item;
  72         on the owning NSWindow. This works analogous to validateMenuItem:.
  73 */
  74
  75 // -----------------------------------------------------------------------------
  76 //  Headers:
  77 // -----------------------------------------------------------------------------
  78
  79 #import <AppKit/AppKit.h>
  80
  81
  82 // -----------------------------------------------------------------------------
  83 //  UKToolbarFactory:
  84 // -----------------------------------------------------------------------------
  85
  86 @interface UKToolbarFactory : NSObject
  87 {
  88         IBOutlet NSWindow*              owner;                          // Window to put the toolbar on.
  89         NSDictionary*                   toolbarItems;           // List of possible items in the toolbar.
  90         NSString*                               toolbarIdentifier;  // The toolbar identifier and base file name.
  91         NSString*                               selectedItem;           // The currently selected item, if this allows selections.
  92 }
  93
  94 -(void)                 setToolbarIdentifier: (NSString*)str;
  95 -(NSString*)    toolbarIdentifier;  // Defaults to the application's bundle identifier with a period and the autosave name of the owning window.
  96
  97 -(NSString*)    selectedItemIdentifier;
  98 -(void)                 setSelectedItemIdentifier: (NSString*)str;
  99
 100 -(BOOL)                 isSelectable;
 101
 102 @end