MAAttachedWindow.h 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. //
  2. // MAAttachedWindow.h
  3. //
  4. // Created by Matt Gemmell on 27/09/2007.
  5. // Copyright 2007 Magic Aubergine.
  6. //
  7. #import <Cocoa/Cocoa.h>
  8. /*
  9. Below are the positions the attached window can be displayed at.
  10. Note that these positions are relative to the point passed to the constructor,
  11. e.g. MAPositionBottomRight will put the window below the point and towards the right,
  12. MAPositionTop will horizontally center the window above the point,
  13. MAPositionRightTop will put the window to the right and above the point,
  14. and so on.
  15. You can also pass MAPositionAutomatic (or use an initializer which omits the 'onSide:'
  16. argument) and the attached window will try to position itself sensibly, based on
  17. available screen-space.
  18. Notes regarding automatically-positioned attached windows:
  19. (a) The window prefers to position itself horizontally centered below the specified point.
  20. This gives a certain enhanced visual sense of an attachment/relationship.
  21. (b) The window will try to align itself with its parent window (if any); i.e. it will
  22. attempt to stay within its parent window's frame if it can.
  23. (c) The algorithm isn't perfect. :) If in doubt, do your own calculations and then
  24. explicitly request that the window attach itself to a particular side.
  25. */
  26. typedef enum _MAWindowPosition {
  27. // The four primary sides are compatible with the preferredEdge of NSDrawer.
  28. MAPositionLeft = NSMinXEdge, // 0
  29. MAPositionRight = NSMaxXEdge, // 2
  30. MAPositionTop = NSMaxYEdge, // 3
  31. MAPositionBottom = NSMinYEdge, // 1
  32. MAPositionLeftTop = 4,
  33. MAPositionLeftBottom = 5,
  34. MAPositionRightTop = 6,
  35. MAPositionRightBottom = 7,
  36. MAPositionTopLeft = 8,
  37. MAPositionTopRight = 9,
  38. MAPositionBottomLeft = 10,
  39. MAPositionBottomRight = 11,
  40. MAPositionAutomatic = 12
  41. } MAWindowPosition;
  42. @interface MAAttachedWindow : NSWindow {
  43. NSColor *borderColor;
  44. float borderWidth;
  45. float viewMargin;
  46. float arrowBaseWidth;
  47. float arrowHeight;
  48. BOOL hasArrow;
  49. float cornerRadius;
  50. BOOL drawsRoundCornerBesideArrow;
  51. @private
  52. NSColor *_MABackgroundColor;
  53. __weak NSView *_view;
  54. __weak NSWindow *_window;
  55. NSPoint _point;
  56. MAWindowPosition _side;
  57. float _distance;
  58. NSRect _viewFrame;
  59. BOOL _resizing;
  60. }
  61. /*
  62. Initialization methods
  63. Parameters:
  64. view The view to display in the attached window. Must not be nil.
  65. point The point to which the attached window should be attached. If you
  66. are also specifying a parent window, the point should be in the
  67. coordinate system of that parent window. If you are not specifying
  68. a window, the point should be in the screen's coordinate space.
  69. This value is required.
  70. window The parent window to attach this one to. Note that no actual
  71. relationship is created (particularly, this window is not made
  72. a childWindow of the parent window).
  73. Default: nil.
  74. side The side of the specified point on which to attach this window.
  75. Default: MAPositionAutomatic.
  76. distance How far from the specified point this window should be.
  77. Default: 0.
  78. */
  79. - (MAAttachedWindow *)initWithView:(NSView *)view // designated initializer
  80. attachedToPoint:(NSPoint)point
  81. inWindow:(NSWindow *)window
  82. onSide:(MAWindowPosition)side
  83. atDistance:(float)distance;
  84. - (MAAttachedWindow *)initWithView:(NSView *)view
  85. attachedToPoint:(NSPoint)point
  86. inWindow:(NSWindow *)window
  87. atDistance:(float)distance;
  88. - (MAAttachedWindow *)initWithView:(NSView *)view
  89. attachedToPoint:(NSPoint)point
  90. onSide:(MAWindowPosition)side
  91. atDistance:(float)distance;
  92. - (MAAttachedWindow *)initWithView:(NSView *)view
  93. attachedToPoint:(NSPoint)point
  94. atDistance:(float)distance;
  95. - (MAAttachedWindow *)initWithView:(NSView *)view
  96. attachedToPoint:(NSPoint)point
  97. inWindow:(NSWindow *)window;
  98. - (MAAttachedWindow *)initWithView:(NSView *)view
  99. attachedToPoint:(NSPoint)point
  100. onSide:(MAWindowPosition)side;
  101. - (MAAttachedWindow *)initWithView:(NSView *)view
  102. attachedToPoint:(NSPoint)point;
  103. // Accessor methods
  104. - (void)setPoint:(NSPoint)point side:(MAWindowPosition)side;
  105. - (NSColor *)borderColor;
  106. - (void)setBorderColor:(NSColor *)value;
  107. - (float)borderWidth;
  108. - (void)setBorderWidth:(float)value; // See note 1 below.
  109. - (float)viewMargin;
  110. - (void)setViewMargin:(float)value; // See note 2 below.
  111. - (float)arrowBaseWidth;
  112. - (void)setArrowBaseWidth:(float)value; // See note 2 below.
  113. - (float)arrowHeight;
  114. - (void)setArrowHeight:(float)value; // See note 2 below.
  115. - (float)hasArrow;
  116. - (void)setHasArrow:(float)value;
  117. - (float)cornerRadius;
  118. - (void)setCornerRadius:(float)value; // See note 2 below.
  119. - (float)drawsRoundCornerBesideArrow; // See note 3 below.
  120. - (void)setDrawsRoundCornerBesideArrow:(float)value; // See note 2 below.
  121. - (void)setBackgroundImage:(NSImage *)value;
  122. - (NSColor *)windowBackgroundColor; // See note 4 below.
  123. - (void)setBackgroundColor:(NSColor *)value;
  124. /*
  125. Notes regarding accessor methods:
  126. 1. The border is drawn inside the viewMargin area, expanding inwards; it does not
  127. increase the width/height of the window. You can use the -setBorderWidth: and
  128. -setViewMargin: methods together to achieve the exact look/geometry you want.
  129. (viewMargin is the distance between the edge of the view and the window edge.)
  130. 2. The specified setter methods are primarily intended to be used _before_ the window
  131. is first shown. If you use them while the window is already visible, be aware
  132. that they may cause the window to move and/or resize, in order to stay anchored
  133. to the point specified in the initializer. They may also cause the view to move
  134. within the window, in order to remain centered there.
  135. Note that the -setHasArrow: method can safely be used at any time, and will not
  136. cause moving/resizing of the window. This is for convenience, in case you want
  137. to add or remove the arrow in response to user interaction. For example, you
  138. could make the attached window movable by its background, and if the user dragged
  139. it away from its initial point, the arrow could be removed. This would duplicate
  140. how Aperture's attached windows behave.
  141. 3. drawsRoundCornerBesideArrow takes effect when the arrow is being drawn at a corner,
  142. i.e. when it's not at one of the four primary compass directions. In this situation,
  143. if drawsRoundCornerBesideArrow is YES (the default), then that corner of the window
  144. will be rounded just like the other three corners, thus the arrow will be inset
  145. slightly from the edge of the window to allow room for the rounded corner. If this
  146. value is NO, the corner beside the arrow will be a square corner, and the other
  147. three corners will be rounded.
  148. This is useful when you want to attach a window very near the edge of another window,
  149. and don't want the attached window's edge to be visually outside the frame of the
  150. parent window.
  151. 4. Note that to retrieve the background color of the window, you should use the
  152. -windowBackgroundColor method, instead of -backgroundColor. This is because we draw
  153. the entire background of the window (rounded path, arrow, etc) in an NSColor pattern
  154. image, and set it as the backgroundColor of the window.
  155. */
  156. @end