chrome/browser/mac/dock.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROME_BROWSER_MAC_DOCK_H_
   6 #define CHROME_BROWSER_MAC_DOCK_H_
   7
   8 #if defined(__OBJC__)
   9 @class NSString;
  10 #else
  11 class NSString;
  12 #endif
  13
  14 namespace dock {
  15
  16 enum AddIconStatus {
  17   IconAddFailure,
  18   IconAddSuccess,
  19   IconAlreadyPresent
  20 };
  21
  22 // Adds an icon to the Dock pointing to |installed_path| if one is not already
  23 // present. |dmg_app_path| is the path to the install source. Its tile will be
  24 // removed if present. If any changes are made to the Dock's configuration,
  25 // the Dock process is restarted so that the changes become visible in the UI.
  26 //
  27 // Various heuristics are used to determine where to place the new icon
  28 // relative to other items already present in the Dock:
  29 //  - If installed_path is already in the Dock, no new tiles for this path
  30 //    will be added.
  31 //  - If dmg_app_path is present in the Dock, it will be removed. If
  32 //    installed_path is not already present, the new tile referencing
  33 //    installed_path will be placed where the dmg_app_path tile was. This
  34 //    keeps the tile where a user expects it if they dragged the application
  35 //    icon from a disk image into the Dock and then clicked on the new icon
  36 //    in the Dock.
  37 //  - The new tile will precede any application with the same name already
  38 //    in the Dock.
  39 //  - In an official build, a new tile for Google Chrome will be placed
  40 //    immediately before the first existing tile for Google Chrome Canary,
  41 //    and a new tile for Google Chrome Canary will be placed immediately after
  42 //    the last existing tile for Google Chrome.
  43 //  - The new tile will be placed immediately after the last tile for another
  44 //    browser application already in the Dock.
  45 //  - The new tile will be placed last in the Dock.
  46 // For the purposes of these comparisons, applications are identified by the
  47 // last component in their path. For example, any application named Safari.app
  48 // will be treated as a browser. If the user renames an application on disk,
  49 // it will alter the result. Looking up the bundle ID could be slightly more
  50 // robust in the presence of such alterations, but it's not thought to be a
  51 // large enough problem to warrant such lookups.
  52 //
  53 // The changes made to the Dock's configuration are the minimal changes
  54 // necessary to cause the desired behavior. Although it's possible to set
  55 // additional properties on the dock tile added to the Dock's plist, this
  56 // is not done. Upon relaunch, Dock.app will determine the correct values for
  57 // the properties it requires and add them to its configuration.
  58 AddIconStatus AddIcon(NSString* installed_path, NSString* dmg_app_path);
  59
  60 }  // namespace dock
  61
  62 #endif  // CHROME_BROWSER_MAC_DOCK_H_