NSDockTile Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.5 and later.
Companion guide
Declared in
NSDockTile.h
Related sample code

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:

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

Getting the Tile Information

Applying Badge Icons to the Tile

Updating the Dock Tile

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 OS X v10.5 and later.
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 OS X v10.5 and later.
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 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 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 OS X v10.5 and later.
Related Sample Code
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 OS X v10.5 and later.
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 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 OS X v10.5 and later.
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 OS X v10.5 and later.
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 OS X v10.5 and later.
Declared In
NSDockTile.h

Constants

Dock Tile Plug-In Support Version

The version of the AppKit framework containing support for dock tile plug-ins.

#define NSAppKitVersionNumberWithDockTilePlugInSupport 1001.0
Constants
NSAppKitVersionNumberWithDockTilePlugInSupport

The specific version of the AppKit framework that introduced support for dock tile plug-ins.. Developers should not need to use this constant unless they are writing applications for OS X v10.5 and earlier.

Available in OS X v10.6 and later.

Declared in NSDockTile.h.