---

NSDockTile Class Reference

Overview

The NSDockTile class lets you customize the visual representation for your application’s miniaturized windows and application icon as they appear in the Dock. You do not create Dock tile objects explicitly in your application. Instead, you retrieve the Dock tile for an existing window or for the application by calling that object’s dockTile method.

Typically, you do not subclass the NSDockTile class. Instead, you use the methods of the class to make the following customizations:

• Badge the tile with a custom string.

• Remove or show the application icon badge.

• Draw the tile content yourself.

If you decide to draw the tile content yourself, you must provide a custom content view to handle the drawing.

Application Dock Tiles

An application Dock tile defaults to display the application’s applicationIconImage.

The application Dock tile never shows a smaller application icon badge.

Whether using the default or custom view, the application Dock tile may be badged with a short custom string.

Window Dock Tiles

A window Dock tile defaults to display a miniaturized version of the windows contents with a badge derived from the application Dock icon, including any customized application Dock icon. The default window Dock tile image may not be badged with a custom string.

A window Dock tile can use a custom view to draw the Dock icon. If a custom view is used, no application badge will be added, but the text label will be overlaid on top of the icon.

Tasks

Drawing the Tile’s Content

• – setContentView:
• – contentView

Getting the Tile Information

• – size
• – owner

Applying Badge Icons to the Tile

• – setShowsApplicationBadge:
• – showsApplicationBadge
• – setBadgeLabel:
• – badgeLabel

Updating the Dock Tile

• – display

Instance Methods

badgeLabel

Returns the tile’s current badge label.

- (NSString *)badgeLabel

Return Value

The localized string to be displayed in the tile’s badging area. This string may be empty or nil.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setBadgeLabel:

Declared In

NSDockTile.h

contentView

Returns the view used to draw the dock tile contents.

- (NSView *)contentView

Return Value

The view used to draw the tile.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setContentView:

Declared In

NSDockTile.h

display

Redraws the dock tile’s content.

- (void)display

Discussion

If a custom content view is provided, Cocoa calls the drawRect: method of that view (and its subviews) to draw the tile’s content.

You can call this method to force the redrawing of the dock tile contents. You might do this if the contents of the underlying application or window change in a way that would require a refreshing of the tile. Some types of system activity, such as resizing the dock, may trigger automatic redraws of the tile. In most cases, however, your application is responsible for triggering redraws.

Cocoa does not automatically redraw the contents of your dock tile. Instead, your application must explicitly send display messages to the dock tile object whenever the contents of your view change and need to be redrawn.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSDockTile.h

owner

Returns the object represented by the dock tile.

- (id)owner

Return Value

The object represented by the dock tile. This is either the NSApplication object or one of your application’s NSWindow objects.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSDockTile.h

setBadgeLabel:

Sets the string to be displayed in the tile’s badging area.

- (void)setBadgeLabel:(NSString *)string

Parameters

string

The localized string to display. This string can contain a count value or other badging information. To clear the badge string, specify an empty string (@"") or nil.

Discussion

The appearance of the badge area is system defined.

Window dock tiles only display a badge label when there is a custom view associated with the dock tile.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – badgeLabel
• – showsApplicationBadge

Declared In

NSDockTile.h

setContentView:

Sets the view to use for drawing the dock tile contents.

- (void)setContentView:(NSView *)view

Parameters

view

The view to use for drawing the tile. This view may contain additional subviews.

Discussion

The view you specify should be height and width resizable.

Cocoa does not automatically redraw the contents of your dock tile. Instead, your application must explicitly send display messages to the dock tile object whenever the contents of your view change and need to be redrawn. Your dock tile view is responsible for drawing the entire contents of the dock tile. Your view does not need to draw the application or custom string badges.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – contentView
• – display

Declared In

NSDockTile.h

setShowsApplicationBadge:

Sets whether the tile should be badged with the application’s icon.

- (void)setShowsApplicationBadge:(BOOL)flag

Parameters

flag

YES to show the application icon; otherwise, NO to hide it.

Discussion

Miniaturized windows include the application badge by default to convey the associated application to the user. In Mac OS X v10.5 and later, application tiles do not support the application badge. A miniaturized window with a custom view does not draw the application badge.

The application icon is positioned automatically in the tile by the NSDockTile object.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – showsApplicationBadge

Declared In

NSDockTile.h

showsApplicationBadge

Returns a Boolean value indicating whether the tile is badged with the application’s icon.

- (BOOL)showsApplicationBadge

Return Value

YES if the tile is badged; otherwise, NO. Returns YES by default.

Availability

• Available in Mac OS X v10.5 and later.

See Also

• – setShowsApplicationBadge:

Declared In

NSDockTile.h

size

Returns the size of the tile.

- (NSSize)size

Return Value

The size of the tile, measured in screen coordinates.

Discussion

The size returned by this method corresponds to the size of the backing store in the dock, which may be bigger than the actual tile displayed on the screen.

Availability

• Available in Mac OS X v10.5 and later.

Related Sample Code

• DockTile

Declared In

NSDockTile.h

---