1 /*
2    NSTextAttachment.h
3 
4    Classes to represent text attachments.
5 
6    Copyright (C) 1996 Free Software Foundation, Inc.
7 
8    Author:  Daniel Böhringer <boehring@biomed.ruhr-uni-bochum.de>
9    Date: August 1998
10    Source by Daniel Böhringer integrated into GNUstep gui
11    by Felipe A. Rodriguez <far@ix.netcom.com>
12 
13    This file is part of the GNUstep GUI Library.
14 
15    This library is free software; you can redistribute it and/or
16    modify it under the terms of the GNU Lesser General Public
17    License as published by the Free Software Foundation; either
18    version 2 of the License, or (at your option) any later version.
19 
20    This library is distributed in the hope that it will be useful,
21    but WITHOUT ANY WARRANTY; without even the implied warranty of
22    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
23    Lesser General Public License for more details.
24 
25    You should have received a copy of the GNU Lesser General Public
26    License along with this library; see the file COPYING.LIB.
27    If not, see <http://www.gnu.org/licenses/> or write to the
28    Free Software Foundation, 51 Franklin Street, Fifth Floor,
29    Boston, MA 02110-1301, USA.
30 */
31 
32 /**
33 NSTextAttachment is used to represent text attachments. When inline,
34 text attachments appear as the value of the NSAttachmentAttributeName
35 attached to the special character NSAttachmentCharacter.
36 
37 NSTextAttachment uses an object obeying the NSTextAttachmentCell
38 protocol to get input from the user and to display an image.
39 
40 NSTextAttachmentCell is a simple subclass of NSCell which provides
41 the NSTextAttachment protocol.
42 */
43 
44 #ifndef _GNUstep_H_NSTextAttachment
45 #define _GNUstep_H_NSTextAttachment
46 
47 #import <GNUstepBase/GSVersionMacros.h>
48 
49 #if OS_API_VERSION(GS_API_MACOSX, GS_API_LATEST)
50 
51 #import <Foundation/NSAttributedString.h>
52 #import <Foundation/NSGeometry.h>
53 #import <Foundation/NSObject.h>
54 #import <AppKit/NSCell.h>
55 
56 @class NSFileWrapper;
57 @class NSLayoutManager;
58 @class NSTextAttachment;
59 @class NSTextContainer;
60 
61 enum {
62     NSAttachmentCharacter = 0xfffc	/* To denote attachments. */
63 };
64 
65 /*
66    These are the only methods required of cells in text attachments...
67    The default NSCell class implements most of these; the NSTextAttachmentCell
68    class is a subclass which implements all and provides some additional
69    functionality.
70  */
71 @protocol NSTextAttachmentCell <NSObject>
72 - (void)drawWithFrame:(NSRect)cellFrame inView:(NSView *)controlView;
73 - (void)drawWithFrame:(NSRect)cellFrame
74 	       inView:(NSView *)controlView
75        characterIndex:(NSUInteger)charIndex;
76 - (void)drawWithFrame:(NSRect)cellFrame
77 	       inView:(NSView *)controlView
78        characterIndex:(NSUInteger)charIndex
79 	layoutManager:(NSLayoutManager *)layoutManager;
80 - (void)highlight:(BOOL)flag
81 	withFrame:(NSRect)cellFrame
82 	   inView:(NSView *)controlView;
83 
84 
85 /** The old way of placing the cell. The text system will never call
86 these directly (TODO: make sure it doesn't), but other things might. The
87 class implements the new method by calling these, so subclasses can
88 easily change behavior by overriding these. **/
89 
90 - (NSSize)cellSize;
91 
92 /* Returns the offset from the current point when typesetting to the lower
93 left corner of the cell. The class returns (0,0). Positive y is probably
94 up. (TODO) */
95 - (NSPoint)cellBaselineOffset;
96 
97 
98 /** The new way of placing the cell. **/
99 
100 /* Returns the rectangle in which the cell should be drawn. The rectangle
101 is relative to the current point when typesetting. Positive y is up.
102 
103 lineFrag is the line frag rect that this cell might be placed in, and
104 position is the current position in that line frag rect (positive y is
105 up). Note that the line frag rect and glyph position may not be where
106 the cell is actually placed.
107 
108 Note that this might be called many times for the same attachment. Eg. if
109 you return a rectangle that won't fit in the proposed line frag rect, the
110 typesetter might try to adjust things so it will fit. It will then send
111 this message with a new proposed line frag rect and glyph position. Thus,
112 great care must be taken when using the line frag rect to calculate the
113 returned rectangle to prevent the typesetting process from getting stuck.
114 
115 The class uses -cellSize and -cellBaselineOffset to return a rect.
116 */
117 -(NSRect) cellFrameForTextContainer: (NSTextContainer *)textContainer
118 	       proposedLineFragment: (NSRect)lineFrag
119 		      glyphPosition: (NSPoint)position
120 		     characterIndex: (NSUInteger)charIndex;
121 
122 
123 - (BOOL)wantsToTrackMouse;
124 - (BOOL)wantsToTrackMouseForEvent:(NSEvent *)theEvent
125 			   inRect:(NSRect)cellFrame
126 			   ofView:(NSView *)controlView
127 		 atCharacterIndex:(NSUInteger)charIndex;
128 - (BOOL)trackMouse:(NSEvent *)theEvent
129 	    inRect:(NSRect)cellFrame
130 	    ofView:(NSView *)controlView
131       untilMouseUp:(BOOL)flag;
132 - (BOOL)trackMouse:(NSEvent *)theEvent
133 	    inRect:(NSRect)cellFrame
134 	    ofView:(NSView *)controlView
135   atCharacterIndex:(NSUInteger)charIndex
136       untilMouseUp:(BOOL)flag;
137 - (void)setAttachment:(NSTextAttachment *)anObject;
138 - (NSTextAttachment *)attachment;
139 @end
140 
141 
142 /*
143    Simple class to provide basic attachment cell functionality.
144    By default this class causes NSTextView to send out delegate
145    messages when the attachment is clicked on or dragged.
146  */
147 @interface NSTextAttachmentCell : NSCell <NSTextAttachmentCell> {
148     NSTextAttachment *_attachment;
149 }
150 @end
151 
152 
153 @interface NSTextAttachment : NSObject <NSCoding> {
154     NSFileWrapper *_fileWrapper;
155     id <NSTextAttachmentCell>_cell;
156     struct GSTextAttachmentFlagsType {
157       // total 32 bits.  31 bits left.
158       unsigned cell_explicitly_set: 1;
159       unsigned unused:31;
160     } _taflags;
161 }
162 
163 /*
164    Designated initializer.
165  */
166 - (id)initWithFileWrapper:(NSFileWrapper *)fileWrapper;
167 
168 /*
169    The fileWrapper is the meat of most types of attachment.
170    It can be set or queried with these methods.  An NSTextAttachment
171    usually has a fileWrapper.  setFileWrapper does not update the
172    attachment's cell in any way.
173  */
174 - (void)setFileWrapper:(NSFileWrapper *)fileWrapper;
175 - (NSFileWrapper *)fileWrapper;
176 
177 /*
178    The cell which handles user interaction.
179    By default an instance of NSTextAttachmentCell is used.
180  */
181 - (id <NSTextAttachmentCell>)attachmentCell;
182 - (void)setAttachmentCell:(id <NSTextAttachmentCell>)cell;
183 
184 @end
185 
186 @interface NSAttributedString (NSTextAttachment)
187 + (NSAttributedString*) attributedStringWithAttachment:
188                  (NSTextAttachment*)attachment;
189 - (BOOL) containsAttachments;
190 @end
191 
192 @interface NSMutableAttributedString (NSTextAttachment)
193 - (void) updateAttachmentsFromPath: (NSString *)path;
194 @end
195 
196 #endif
197 
198 #endif /* _GNUstep_H_NSTextAttachment */
199 
200