/core/externals/google-toolbox-for-mac/AppKit/GTMUILocalizer.h

http://macfuse.googlecode.com/ · C++ Header · 95 lines · 14 code · 5 blank · 76 comment · 0 complexity · 41314456a57999c379f04d17ea3f2470 MD5 · raw file

  1. //
  2. // GTMUILocalizer.h
  3. //
  4. // Copyright 2009 Google Inc.
  5. //
  6. // Licensed under the Apache License, Version 2.0 (the "License"); you may not
  7. // use this file except in compliance with the License. You may obtain a copy
  8. // of the License at
  9. //
  10. // http://www.apache.org/licenses/LICENSE-2.0
  11. //
  12. // Unless required by applicable law or agreed to in writing, software
  13. // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  14. // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
  15. // License for the specific language governing permissions and limitations under
  16. // the License.
  17. //
  18. #import <Cocoa/Cocoa.h>
  19. // A class for localizing nibs by doing simple string replacement.
  20. // To use this, make an instance of GTMUILocalizer in your nib. Connect the
  21. // owner_ outlet of the your instance to the File Owner of the nib. It expects
  22. // the owner_ outlet to be an instance or subclass of NSWindowController,
  23. // NSViewController or NSApplication. Using the bundle of the nib it will then
  24. // localize any items in the NSWindowController's window and subviews, or the
  25. // NSViewController's view and subviews or the NSApplication's main menu
  26. // and dockmenu at when awakeFromNib is called on the GTMUILocalizer instance.
  27. // You can optionally hook up otherObjectToLocalize_ and
  28. // yetAnotherObjectToLocalize_ and those will also be localized. Strings in the
  29. // nib that you want localized must start with ^ (shift-6). The strings will
  30. // be looked up in the Localizable.strings table without the caret as the
  31. // key.
  32. // Things that will be localized are:
  33. // - Titles and altTitles (for menus, buttons, windows, menuitems, tabViewItem)
  34. // - stringValue (for labels)
  35. // - tooltips
  36. // - accessibility help
  37. // - menus
  38. //
  39. // Due to technical limitations, accessibility description cannot be localized.
  40. // See http://lists.apple.com/archives/Accessibility-dev/2009/Dec/msg00004.html
  41. // and http://openradar.appspot.com/7496255 for more information.
  42. //
  43. // As an example if I wanted to localize a button with the word "Print" on
  44. // it, I would put it in a window controlled by a NSWindowController that was
  45. // the owner of the nib. I would set it's title to be "^Print". I would then
  46. // create an instance of GTMUILocalizer and set it's owner_ to be the owner
  47. // of the nib.
  48. // In my Localizable.strings file in my fr.lproj directory for the bundle
  49. // I would put "Print" = "Imprimer";
  50. // Then when my app launched in French I would get a button labeled
  51. // "Imprimer". Note that GTMUILocalizer is only for strings, and doesn't
  52. // resize, move or change text alignment on any of the things it modifies.
  53. // If you absolutely need a caret at the beginning of the string
  54. // post-localization, you can put "Foo" = "^Foo"; in your strings file and
  55. // it will work.
  56. // Your nib could be located in a variety of places depending on what you want
  57. // to do. I would recommend having your "master" nib directly in Resources.
  58. // If for some reason you needed to do some custom localization of the
  59. // nib you could copy the master nib into your specific locale folder, and
  60. // then you only need to adjust the items in the nib that you need to
  61. // customize. You can leave the strings in the "^Foo" convention and they
  62. // will localize properly. This keeps the differences between the nibs down
  63. // to the bare essentials.
  64. //
  65. // NOTE: NSToolbar localization support is limited to only working on the
  66. // default items in the toolbar. We cannot localize items that are on of the
  67. // customization palette but not in the default items because there is not an
  68. // API for NSToolbar to get all possible items. You are responsible for
  69. // localizing all non-default toolbar items by hand.
  70. //
  71. @interface GTMUILocalizer : NSObject {
  72. @protected
  73. IBOutlet id owner_;
  74. IBOutlet id otherObjectToLocalize_;
  75. IBOutlet id yetAnotherObjectToLocalize_;
  76. @private
  77. NSBundle *bundle_;
  78. }
  79. - (id)initWithBundle:(NSBundle *)bundle;
  80. // Localize |object|. If |recursive| is true, it will attempt
  81. // to localize objects owned/referenced by |object|.
  82. - (void)localizeObject:(id)object recursively:(BOOL)recursive;
  83. // A method for subclasses to override in case you have a different
  84. // way to go about getting localized strings.
  85. // If |string| does not start with ^ you should return nil.
  86. // If |string| is nil, you should return nil
  87. - (NSString *)localizedStringForString:(NSString *)string;
  88. // Allows subclasses to override how the bundle is picked up
  89. + (NSBundle *)bundleForOwner:(id)owner;
  90. @end