El delegat d'una instància NSToolbar es responsable de proporcionar els identificadors especificats pels ítems de la barra d'eines que estan a la barra d'eines, tant com els ítems per defecte en una nova barra d'eines.

Items de barra d'eines per defecte i permesos

El mètode delegat requerit toolbarAllowedItemIdentifiers: retorna una matriu d'identificadors especificant els ítems de la barra d'eines que poden mostrar-se per una instància específica de NSToolbar. Per defecte, una nova instància de barra d'eines no assumeix quins ítems estan permesos, ni tan sols l'ítem separador.

L'exemple d'implementació mostrat en el Llistat 1 configura la barra d'eines per permetre una selecció dels ítems de barra d'eines estàndard de Cocoa tant com els ítems de barra d'eines específics de l'aplicació. La barra d'eines resultant es mostra en la Figura 1.

Llistat 1: Exemple de la implementació del mètode toolbarAllowedItemIdentifiers:

- (NSArray *) toolbarAllowedItemIdentifiers: (NSToolbar *) toolbar {
    return [NSArray arrayWithObjects: SaveDocToolbarItemIdentifier,
        NSToolbarPrintItemIdentifier,
        NSToolbarShowColorsItemIdentifier,
        NSToolbarShowFontsItemIdentifier,
        NSToolbarCustomizeToolbarItemIdentifier,
        NSToolbarFlexibleSpaceItemIdentifier,
        NSToolbarSpaceItemIdentifier,
        NSToolbarSeparatorItemIdentifier, nil];
}

Figura 1: Exemple de configuració d'ítems de barra d'eines

El conjunt d'ítems de la barra d'eines per defecte són retornats implementant els mètode requerit toolbarDefaultItemIdentifiers:. La implementació s'espera per retornar una matriu d'identificadors que contenen els ítems per defecte de la barra d'eines especificada. Si durant la inicialització de la barra d'eines no es sobre-escriuen els valors trobats en els defectes de l'usuari (cridant setAutosavesConfiguration: amb un YES com a argument) aquests ítems s'utilitzaran com el conjunt per defecte de la barra d'eines. A més, si l'usuari escull canviar als ítems per defecte el conjunt retornat per toolbarDefaultItemIdentifiers: s'utilitzaran.

El codi d'exemple del Llistat 2 causa que els ítems per defecte per configurar-se com es mostra en la Figura 2.

Llistat 2: Exemple d'implementació del mètode toolbarDefaultItemIdentifiers:

- (NSArray *) toolbarDefaultItemIdentifiers: (NSToolbar *) toolbar {
    return [NSArray arrayWithObjects: SaveDocToolbarItemIdentifier,
        NSToolbarPrintItemIdentifier,
        NSToolbarSeparatorItemIdentifier,
        NSToolbarShowColorsItemIdentifier,
        NSToolbarShowFontsItemIdentifier,
        NSToolbarFlexibleSpaceItemIdentifier,
        NSToolbarSpaceItemIdentifier,
        SearchDocToolbarItemIdentifier, nil];
}

Figura 2: Exemple de configuració d'ítems de barra d'eines

Creant nous ítems de barra d'eines quan es demani

Una implementació del mètode requerit toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar: retorna una instància NSToolbarItem especificada per l'identificador d'ítem de la barra d'eines. L'ítem pot no ser afegit immediatament a la barra d'eines, així aquest mètode també es cridat quan es crea la plana de personalització.

El codi d'exemple del Llistat 3 crea una instància simple de NSToolbarItem per l'ítem de barra d'eines personalitzada de l'aplicació, SaveDocToolbarItemIdentifier. Aquest ítem apareix com una icona en la barra d'eines utilitzant el re-dibuixat per defecte NSToolbarItem.

Llistat 3: Una implementació del mètode toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar: per crear una instància simple de NSToolbarItem

- (NSToolbarItem *) toolbar:(NSToolbar *)toolbar
      itemForItemIdentifier:(NSString *)itemIdentifier
  willBeInsertedIntoToolbar:(BOOL)flag
{
    NSToolbarItem *toolbarItem = [[[NSToolbarItem alloc] initWithItemIdentifier: itemIdentifier] autorelease];

    if ([itemIdentifier isEqual: SaveDocToolbarItemIdentifier]) {
      // Posem l'etiqueta de text mostrada en la 
      // barra d'eines i la paleta de personalització
      [toolbarItem setLabel:@"Save"];
      [toolbarItem setPaletteLabel:@"Save"];

      // Posem un missatge flotant raonable, i la imatge
      // que voldríem localitzar per utilitzar l'ítem
      [toolbarItem setToolTip:@"Save Your Document"];
      [toolbarItem setImage:[NSImage imageNamed:@"SaveDocumentItemImage"]];

      // Li diem quin missatge ha d'enviar quan es prem 
      [toolbarItem setTarget:self];
      [toolbarItem setAction:@selector(saveDocument:)];
    } 
    else  {
      // Identificador d'ítem que no exiteix
      // o no està suportat per utilitzar-lo
      // Retornant un nil s'informa a la barra d'eines
      // que aquest tipus d'ítem no està suportat
      toolbarItem = nil;
    }
    return toolbarItem;
}

Retornant un ítem de barra d'eines que crea una vista personalitzada es quelcom més complicat. A més d'especificar la informació necessària per un ítem de barra d'eines simple, l'aplicació també ha d'activar explícitament la vista que s'utilitzarà per dibuixar l'ítem, la mida mínima que la vista necessita per mostra la propietat, i la mida màxima que l'ítem de la barra d'eines pot tenir.

Un efecte col·lateral d'utilitzar una vista personalitzada per un ítem de barra d'eines que s'ha de considerar en aquest cas quan la barra d'eines es mostrat com només text. El comportament per defecte es mostrar l'etiqueta de l'ítem com un text desactivat, efectivament desactivant completament l'ítem de barra d'eines. Un ítem de barra d'eines també pot especificar una instància NSMenu que s'utilitzarà quan la barra d'eines es mostri en mode només text. Aquest menú també s'utilitzarà quan un ítem de barra d'eines que utilitza una vista personalitzada es mostra en un menú que sobresurt de la barra d'eines.

L'exemple del codi del Llistat 4 implementa un ítem de barra d'eines de cerca com es mostra en la Figura 1.

Llistat 4: Una implementació del mètode toolbar:itemForItemIdentifier:willBeInsertedIntoToolbar: per crear una instància NSView basada en NSToolbarItem

- (NSToolbarItem *) toolbar:(NSToolbar *)toolbar
      itemForItemIdentifier:(NSString *)itemIdentifier
  willBeInsertedIntoToolbar:(BOOL)flag
{
    NSToolbarItem *toolbarItem = [[[NSToolbarItem alloc] initWithItemIdentifier:itemIdentifier] autorelease];

    if ([itemIdentifier isEqual: SearchDocToolbarItemIdentifier]) {
      // Posem les propietats estàndard
      [toolbarItem setLabel:@"Search"];
      [toolbarItem setPaletteLabel:@"Search"];
      [toolbarItem setToolTip:@"Search Your Document"];

      // Utilitzem una vista personalitzada, un camp de text arrodonit
      // enganxada a un searchFieldOutlet de InterfaceBuilder com a
      // vista personalitzada
      [toolbarItem setView:searchFieldOutlet];
      [toolbarItem setMinSize:NSMakeSize(100,NSHeight([searchFieldOutlet frame]))];
      [toolbarItem setMaxSize:NSMakeSize(400,NSHeight([searchFieldOutlet frame]))];

      // Crea el menú personalitzat 
      NSMenu *submenu=[[[NSMenu alloc] init] autorelease];
      NSMenuItem *submenuItem=[[[NSMenuItem alloc] initWithTitle: @"Search Panel"
              action:@selector(searchUsingSearchPanel:)
              keyEquivalent: @""] autorelease];
      NSMenuItem *menuFormRep=[[[NSMenuItem alloc] init] autorelease];

      [submenu addItem: submenuItem];
      [submenuItem setTarget:self];
      [menuFormRep setSubmenu:submenu];
      [menuFormRep setTitle:[toolbarItem label]];
      [toolbarItem setMenuFormRepresentation:menuFormRep];
    } 
    else {
      // Identificador d'ítem que no exiteix
      // o no està suportat per utilitzar-lo
      // Retornant un nil s'informa a la barra d'eines
      // que aquest tipus d'ítem no està suportat
      toolbarItem = nil;
    }
    return toolbarItem;
}

Mitjançant programació afegir i eliminar ítems de barra d'eines

Mentre sota la majoria de circumstàncies l'usuari afegeix i elimina els ítems des d'una barra d'eines utilitzat la plana de personalització o el menú de context, és possible insertar i eliminar ítems mitjançant la programació.

El mètode insertItemWithItemIdentifier:atIndex: inserta l'ítem especificat per l'identificador d'ítem a la posició especificada.

El mètode removeItemAtIndex: treu l'ítem de la barra d'eines a l'índex especificat.

Ser notificat quan els ítem s'afegeixen o eliminen de la barra d'eines

Un delegat NSToolbar opcionalment pot notificar-se quan els ítems de la barra d'eines s'ha afegit o tret de la barra d'eines.

El mètode delegat opcional toolbarWillAddItem: proporciona notificació que un ítem de barra d'eines s'ha afegit a la barra d'eines. L'identificador de l'ítem de barra d'eines està dins del diccionari d'informació d'usuari de la notificació a la clau @"item". El típic ús d'aquest mètode es posar el destí per a un ítem de barra d'eines estàndard, com és el Print, i potser per alterar altres atribuïts de l'ítem, com el missatge flotant.

El codi d'exemple del Llistat 5 posa el destí i l'acció per l'ítem Print estàndard quan el delegat es notificat que l'ítem serà afegit a la barra d'eines.

Llistat 5: Una implementació del mètode toolbarWillAddItem: per configurar un NSToolbarItem abans que s'afegeixi a la barra d'eines.

- (void) toolbarWillAddItem:(NSNotification *)notification {
    NSToolbarItem *addedItem = [[notification userInfo] objectForKey: @"item"];

    if ([[addedItem itemIdentifier] isEqual: NSToolbarPrintItemIdentifier]) {
      [addedItem setToolTip:@"Print Your Document"];
      [addedItem setTarget:self];
      [addedItem setAction:@selector(myCustomPrintAction:)];
    }
} 

El mètode delegat opcional toolbarDidRemoveItem: proporciona notificació que la barra d'eines ha eliminat un ítem de la barra d'eines des de la barra d'eines. L'identificador de l'ítem de barra d'eines està dins del diccionari d'informació d'usuari de la notificació sota la clau @"item". Podries utilitzar aquesta oportunitat per informar al controlador de la finestra que les dades associades amb aquest ítem ja no seran vàlides.

L'exemple del Llistat 6 invalida la cadena de cerca de l'aplicació quan l'ítem de cerca es treu de la barra d'eines.

Llistat 6: Una implementació del mètode toolbarDidRemoveItem: que invalida un valor quan un ítem de barra d'eines es treu de la barra d'eines.

- (void)toolbarDidRemoveItem:(NSNotification *)notification {
    NSToolbarItem *removedItem = [[notification userInfo] objectForKey: @"item"];

    if ([removedItem itemIdentifier] isEqual:SearchDocToolbarItemIdentifier) {
      [self invalidateSearchString];
    }
}

Altres objectes que el delegat de la barra d'eines poden registrar l'afegit i l'eliminació dels ítems de barra d'eines mitjançant el NSToolbarWillAddItemNotification i NSToolbarDidRemoveItemNotification.