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

  1//
  2//  GTMHotKeyTextField.h
  3//
  4//  Copyright 2006-2010 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
 19// Text field for capturing hot key entry. This is intended to be similar to the
 20// Apple key editor in their Keyboard pref pane.
 21
 22// NOTE: There are strings that need to be localized to use this field.  See the
 23// code in stringForKeycode the the keys.  The keys are all the English versions
 24// so you'll get reasonable things if you don't have a strings file.
 25
 26#import <Cocoa/Cocoa.h>
 27#import "GTMDefines.h"
 28
 29@interface GTMHotKey : NSObject <NSCopying> {
 30 @private
 31  NSUInteger modifiers_;
 32  NSUInteger keyCode_;
 33  BOOL doubledModifier_;
 34}
 35
 36+ (id)hotKeyWithKeyCode:(NSUInteger)keyCode
 37              modifiers:(NSUInteger)modifiers
 38        useDoubledModifier:(BOOL)doubledModifier;
 39
 40- (id)initWithKeyCode:(NSUInteger)keyCode
 41            modifiers:(NSUInteger)modifiers
 42   useDoubledModifier:(BOOL)doubledModifier;
 43
 44// Custom accessors (readonly, nonatomic)
 45- (NSUInteger)modifiers;
 46- (NSUInteger)keyCode;
 47- (BOOL)doubledModifier;
 48
 49@end
 50
 51//  Notes:
 52//  - Though you are free to implement control:textShouldEndEditing: in your
 53//    delegate its return is always ignored. The field always accepts only
 54//    one hotkey keystroke before editing ends.
 55//  - The "value" binding of this control is to the dictionary describing the
 56//    hotkey.
 57//  - The field does not attempt to consume all hotkeys. Hotkeys which are
 58//    already bound in Apple prefs or other applications will have their
 59//    normal effect.
 60//
 61
 62@interface GTMHotKeyTextField : NSTextField
 63@end
 64
 65@interface GTMHotKeyTextFieldCell : NSTextFieldCell {
 66 @private
 67  GTMHotKey *hotKey_;
 68}
 69
 70// Convert Cocoa modifier flags (-[NSEvent modifierFlags]) into a string for
 71// display. Modifiers are represented in the string in the same order they would
 72// appear in the Menu Manager.
 73//
 74//  Args:
 75//    flags: -[NSEvent modifierFlags]
 76//
 77//  Returns:
 78//    Autoreleased NSString
 79//
 80+ (NSString *)stringForModifierFlags:(NSUInteger)flags;
 81
 82// Convert a keycode into a string that would result from typing the keycode in
 83// the current keyboard layout. This may be one or more characters.
 84//
 85// Args:
 86//   keycode: Virtual keycode such as one obtained from NSEvent
 87//   useGlyph: In many cases the glyphs are confusing, and a string is clearer.
 88//             However, if you want to display in a menu item, use must
 89//             have a glyph. Set useGlyph to FALSE to get localized strings
 90//             which are better for UI display in places other than menus.
 91//     bundle: Localization bundle to use for localizable key names
 92//
 93// Returns:
 94//   Autoreleased NSString
 95//
 96+ (NSString *)stringForKeycode:(UInt16)keycode
 97                          useGlyph:(BOOL)useGlyph
 98                    resourceBundle:(NSBundle *)bundle;
 99
100@end
101
102// Custom field editor for use with hotkey entry fields (GTMHotKeyTextField).
103// See the GTMHotKeyTextField for instructions on using from the window
104// delegate.
105@interface GTMHotKeyFieldEditor : NSTextView {
106 @private
107  GTMHotKeyTextFieldCell *cell_;
108}
109
110// Get the shared field editor for all hot key fields
111+ (GTMHotKeyFieldEditor *)sharedHotKeyFieldEditor;
112
113// Custom accessors (retain, nonatomic)
114- (GTMHotKeyTextFieldCell *)cell;
115
116@end