libs-gui/Documentation/gsdoc/NSView.gsdoc

985 lines
28 KiB
Text
Raw Normal View History

<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
<gsdoc base="NSView" prev="NSTextView.html" next="NSWindow.html" up="Gui.html">
<head>
<title>NSView</title>
<author name="Richard Frith-Macdonald">
<email address="rfm@gnu.org"/>
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
</author>
<author name="James Dessart">
<email address="skwirl@cam.org"/>
</author>
<author name="Nicola Pero">
<email address="n.pero@mi.flashnet.it"/>
</author>
<version>$Revision$</version>
<date>$Date$</date>
</head>
<body>
<chapter>
<heading>NSView</heading>
<class name="NSView" super="NSResponder">
<declared>Gui/NSView.h</declared>
<conform>NSCoding</conform>
<desc>
<p>NSView is an abstract class which provides facilities for
drawing in a window and receiving events. It is the
superclass of many of the visual elements of the GUI.</p>
<p>In order to display itself, a view must be placed in a
window (represented by an NSWindow object). Within the
window is a hierarchy of NSViews, headed by the window's
content view. Every other view in a window is a descendant
of this view.</p>
<p>Subclasses can override <code>drawRect:</code> in order
to implement their appearance. Other methods of NSView and
NSResponder can also be overridden to handle user generated
events.</p>
</desc>
<method type="NSMenu*" factory="yes">
<sel>defaultMenu</sel>
<desc>
<p>As of yet, unimplemented.</p>
</desc>
</method>
<method type="NSView*" factory="yes">
<sel>focusView</sel>
<desc>
<p>Returns the view which currently has the focus.</p>
</desc>
</method>
<method type="BOOL">
<sel>acceptsFirstMouse:</sel>
<arg type="NSEvent*">theEvent</arg>
<desc>
<p>Returns <code>YES</code> if the view object will accept the first click
received when in an inactive window, and <code>NO</code> otherwise.</p>
</desc>
</method>
<method type="void">
<sel>addCursorRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>cursor:</sel>
<arg type="NSCursor*">aCursor</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>addSubview:</sel>
<arg type="NSView*">aView</arg>
<desc>
<p>
Adds <var>aView</var> as a subview of the receiver.
</p>
</desc>
</method>
<method type="void">
<sel>addSubview:</sel>
<arg type="NSView*">aView</arg>
<sel>positioned:</sel>
<arg type="NSWindowOrderingMode">place</arg>
<sel>relativeTo:</sel>
<arg type="NSView*">otherView</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>addToPageSetup</sel>
<desc>
</desc>
</method>
<method type="NSTrackingRectTag">
<sel>addTrackingRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>owner:</sel>
<arg type="id">anObject</arg>
<sel>userData:</sel>
<arg type="void*">userData</arg>
<sel>assumeInside:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>adjustPageHeightNew:</sel>
<arg type="float*">newBottom</arg>
<sel>top:</sel>
<arg type="float">top</arg>
<sel>bottom:</sel>
<arg type="float">proposedBottom</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>adjustPageWidthNew:</sel>
<arg type="float*">newRight</arg>
<sel>left:</sel>
<arg type="float">left</arg>
<sel>right:</sel>
<arg type="float">proposedRight</arg>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>adjustScroll:</sel>
<arg type="NSRect">proposedVisibleRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>allocateGState</sel>
<desc>
Tell the view to maintain a private gstate object which
encapsulates all the information about drawing, such as coordinate
transforms, line widths, etc. If you do not invoke this method,
a gstate object is constructed each time the view is lockFocused.
Allocating a private gstate may improve the performance of views
that are focused a lot and have a lot of customized drawing
parameters.
<p>
View subclasses should override the setUpGstate method to set these
custom parameters.
</desc>
</method>
<method type="NSView*">
<sel>ancestorSharedWithView:</sel>
<arg type="NSView*">aView</arg>
<desc>
<p>
Returns <code>self</code> if <var>aView</var> is the receiver or <var>aView</var> is a
subview of the receiver, the ancestor view shared by <var>aView</var> and the receiver,
if any, <var>aView</var> if it is an ancestor of the receiver, otherwise returns
<code>nil</code>.
</p>
</desc>
</method>
<method type="BOOL">
<sel>autoresizesSubviews</sel>
<desc>
</desc>
</method>
<method type="unsigned int">
<sel>autoresizingMask</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>autoscroll:</sel>
<arg type="NSEvent*">theEvent</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>beginPage:</sel>
<arg type="int">ordinalNum</arg>
<sel>label:</sel>
<arg type="NSString *">aString</arg>
<sel>bBox:</sel>
<arg type="NSRect">pageRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>beginPageSetupRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>placement:</sel>
<arg type="NSPoint">location</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>beginPrologueBBox:</sel>
<arg type="NSRect">boundingBox</arg>
<sel>creationDate:</sel>
<arg type="NSString*">dateCreated</arg>
<sel>createdBy:</sel>
<arg type="NSString *">anApplication</arg>
<sel>fonts:</sel>
<arg type="NSString*">fontNames</arg>
<sel>forWhom:</sel>
<arg type="NSString *">user</arg>
<sel>pages:</sel>
<arg type="int">numPages</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>beginSetup</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>beginTrailer</sel>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>bounds</sel>
<desc>
</desc>
</method>
<method type="float">
<sel>boundsRotation</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>canDraw</sel>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>centerScanRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="NSPoint">
<sel>convertPoint:</sel>
<arg type="NSPoint">aPoint</arg>
<sel>fromView:</sel>
<arg type="NSView*">aView</arg>
<desc>
</desc>
</method>
<method type="NSPoint">
<sel>convertPoint:</sel>
<arg type="NSPoint">aPoint</arg>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>convertRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>fromView:</sel>
<arg type="NSView*">aView</arg>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>convertRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>toView:</sel>
<arg type="NSView*">aView</arg>
<desc>
</desc>
</method>
<method type="NSSize">
<sel>convertSize:</sel>
<arg type="NSSize">aSize</arg>
<sel>fromView:</sel>
<arg type="NSView*">aView</arg>
<desc>
</desc>
</method>
<method type="NSSize">
<sel>convertSize:</sel>
<arg type="NSSize">aSize</arg>
<sel>toView:</sel>
<arg type="NSView*">aView</arg>
<desc>
</desc>
</method>
<method type="NSData*">
<sel>dataWithEPSInsideRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>discardCursorRects</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>display</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>displayIfNeeded</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>displayIfNeededIgnoringOpacity</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>displayIfNeededInRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>displayIfNeededInRectIgnoringOpacity:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>displayRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>displayRectIgnoringOpacity:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>dragFile:</sel>
<arg type="NSString*">fullPath</arg>
<sel>fromRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>slideBack:</sel>
<arg type="BOOL">slideBack</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>dragImage:</sel>
<arg type="NSImage*">anImage</arg>
<sel>at:</sel>
<arg type="NSPoint">imageLoc</arg>
<sel>offset:</sel>
<arg type="NSSize">mouseOffset</arg>
<sel>event:</sel>
<arg type="NSEvent *">theEvent</arg>
<sel>pasteboard:</sel>
<arg type="NSPasteboard*">pboard</arg>
<sel>source:</sel>
<arg type="id">sourceObject</arg>
<sel>slideBack:</sel>
<arg type="BOOL">slideBack</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>drawPageBorderWithSize:</sel>
<arg type="NSSize">borderSize</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>drawRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
This method is invoked to handle drawing inside the view.
The default NSView's implementation does nothing;
subclasses might override it to draw something inside the
view. Since NSView's implementation is guaranteed to be
empty, you should not call super's implementation when you
override it in subclasses. drawRect: is invoked when the
focus has already been locked on the view; you can use
arbitrary postscript functions in drawRect: to draw inside
your view; the coordinate system in which you draw is the
view's own coordinate system (this means for example that
you should refer to the rectangle covered by the view
using its bounds, and not its frame). The argument of
drawRect: is the rectangle which needs to be redrawn. In
a lossy implementation, you can ignore the argument and
redraw the whole view; if you are aiming at performance,
you may want to redraw only what is inside the rectangle
which needs to be redrawn; this usually improves drawing
performance considerably.
</desc>
</method>
<method type="void">
<sel>drawSheetBorderWithSize:</sel>
<arg type="NSSize">borderSize</arg>
<desc>
</desc>
</method>
<method type="NSScrollView*">
<sel>enclosingScrollView</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>endHeaderComments</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>endPage</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>endPageSetup</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>endPrologue</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>endSetup</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>endTrailer</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>fax:</sel>
<arg type="id">sender</arg>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>frame</sel>
<desc>
</desc>
</method>
<method type="float">
<sel>frameRotation</sel>
<desc>
</desc>
</method>
<method type="int">
<sel>gState</sel>
<desc>
Returns an identifier that represents the view's gstate object,
which is used to encapsulate drawing information about the view.
Most of the time a gstate object is created from scratch when
the view is focused, so if the view is not currently focused or
allocateGState has not been called, then this method will
return 0.
</desc>
</method>
<method type="float">
<sel>heightAdjustLimit</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>hitTest:</sel>
<arg type="NSPoint">aPoint</arg>
<desc>
<p>Returns the subview, lowest in the receiver's hierarchy, which contains
<var>aPoint</var></p>
</desc>
</method>
<method type="id">
<sel>initWithFrame:</sel>
<arg type="NSRect">frameRect</arg>
<desc>
</desc>
</method>
<method type="NSInterfaceStyle">
<sel>interfaceStyle</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>isDescendantOf:</sel>
<arg type="NSView*">aView</arg>
<desc>
<p>
Returns <code>YES</code> if <var>aView</var> is an ancestor of the receiver.
</p>
</desc>
</method>
<method type="BOOL">
<sel>isFlipped</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>isOpaque</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>isRotatedFromBase</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>isRotatedOrScaledFromBase</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>knowsPageRange:</sel>
<arg type="NSRangePointer">range</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>knowsPagesFirst:</sel>
<arg type="int*">firstPageNum</arg>
<desc>
</desc>
</method>
<method type="NSPoint">
<sel>locationOfPrintRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>lockFocus</sel>
<desc>
</desc>
</method>
<method type="NSMenu*">
<sel>menuForEvent:</sel>
<arg type="NSEvent*">theEvent</arg>
<desc>
<p>As of yet, unimplemented.</p>
</desc>
</method>
<method type="BOOL">
<sel>mouse:</sel>
<arg type="NSPoint">aPoint</arg>
<sel>inRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
<p>Returns whether or not <var>aPoint</var> lies within <var>aRect</var>.</p>
</desc>
</method>
<method type="BOOL">
<sel>needsDisplay</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>needsPanelToBecomeKey</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>nextKeyView</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>nextValidKeyView</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>opaqueAncestor</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>performKeyEquivalent:</sel>
<arg type="NSEvent*">theEvent</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>performMnemonic:</sel>
<arg type="NSString*">aString</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>postsBoundsChangedNotifications</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>postsFrameChangedNotifications</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>previousKeyView</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>previousValidKeyView</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>print:</sel>
<arg type="id">sender</arg>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>rectForPage:</sel>
<arg type="int">pageNumber</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>reflectScrolledClipView:</sel>
<arg type="NSClipView*">aClipView</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>registerForDraggedTypes:</sel>
<arg type="NSArray*">pboardTypes</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>releaseGState</sel>
<desc>
Frees the gstate object, if there is one. Note that the next time
the view is lockFocused, the gstate will be allocated again.
</desc>
</method>
<method type="void">
<sel>removeCursorRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>cursor:</sel>
<arg type="NSCursor*">aCursor</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>removeFromSuperview</sel>
<desc>
<p>
Removes the receiver from its superviews list of subviews,
by invoking the superviews [-removeSubview:] method, and
marks the rectangle that the reciever occupied in the
superview as needing redisplay.
</p>
<p>
This is dangerous to use during display, since it alters the
rectangles needing display.
</p>
</desc>
</method>
<method type="void">
<sel>removeFromSuperviewWithoutNeedingDisplay</sel>
<desc>
<p>
Removes the receiver from its superviews list of subviews,
by invoking the superviews [-removeSubview:] method.
</p>
</desc>
</method>
<method type="void">
<sel>removeSubview:</sel>
<arg type="NSView*">aView</arg>
<desc>
<p>
Removes the view from the receivers list of subviews
and from the responder chain.
</p>
<p>
Also invokes [aView -viewWillMoveToWindow: nil] to handle
removal of aView (and recursively, its children) from its
window - performing tidyup by invalidating cursor rects etc.
</p>
</desc>
<standards><NotMacOS-X/><NotOpenStep/></standards>
</method>
<method type="void">
<sel>removeTrackingRect:</sel>
<arg type="NSTrackingRectTag">aTag</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>renewGState</sel>
<desc>
Invalidates the view's gstate object so it will be set up
again using setUpGState the next time the view is focused.
</desc>
</method>
<method type="void">
<sel>replaceSubview:</sel>
<arg type="NSView*">oldView</arg>
<sel>with:</sel>
<arg type="NSView*">newView</arg>
<desc>
<p>
Removes <var>oldView</var> from the receiver and places <var>newView</var> in its place.
</p>
</desc>
</method>
<method type="void">
<sel>resetCursorRects</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>resizeSubviewsWithOldSize:</sel>
<arg type="NSSize">oldFrameSize</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>resizeWithOldSuperviewSize:</sel>
<arg type="NSSize">oldFrameSize</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>rotateByAngle:</sel>
<arg type="float">angle</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>scaleUnitSquareToSize:</sel>
<arg type="NSSize">newUnitSize</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>scrollClipView:</sel>
<arg type="NSClipView*">aClipView</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>scrollPoint:</sel>
<arg type="NSPoint">aPoint</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>scrollRect:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>scrollRectToVisible:</sel>
<arg type="NSRect">aRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setAutoresizesSubviews:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setAutoresizingMask:</sel>
<arg type="unsigned int">mask</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setBounds:</sel>
<arg type="NSRect">boundsRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setBoundsOrigin:</sel>
<arg type="NSPoint">newOrigin</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setBoundsRotation:</sel>
<arg type="float">angle</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setBoundsSize:</sel>
<arg type="NSSize">newSize</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setFrame:</sel>
<arg type="NSRect">frameRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setFrameOrigin:</sel>
<arg type="NSPoint">newOrigin</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setFrameRotation:</sel>
<arg type="float">angle</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setFrameSize:</sel>
<arg type="NSSize">newSize</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setInterfaceStyle:</sel>
<arg type="NSInterfaceStyle">interfaceStyle</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setNeedsDisplay:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setNeedsDisplayInRect:</sel>
<arg type="NSRect">invalidRect</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setNextKeyView:</sel>
<arg type="NSView*">aView</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setPostsBoundsChangedNotifications:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setPostsFrameChangedNotifications:</sel>
<arg type="BOOL">flag</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setToolTip:</sel>
<arg type="NSString*">string</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>setUpGState</sel>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>shouldDelayWindowOrderingForEvent:</sel>
<arg type="NSEvent*">theEvent</arg>
<desc>
</desc>
</method>
<method type="BOOL">
<sel>shouldDrawColor</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>sortSubviewsUsingFunction:</sel>
<arg type="int (*)(id,id,void*)">compare</arg>
<sel>context:</sel>
<arg type="void*">context</arg>
<desc>
</desc>
</method>
<method type="NSArray*">
<sel>subviews</sel>
<desc>
</desc>
</method>
<method type="NSView*">
<sel>superview</sel>
<desc>
</desc>
</method>
<method type="int">
<sel>tag</sel>
<desc>
</desc>
</method>
<method type="NSString*">
<sel>toolTip</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>translateOriginToPoint:</sel>
<arg type="NSPoint">newOrigin</arg>
<desc>
</desc>
</method>
<method type="void">
<sel>unlockFocus</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>unregisterDraggedTypes</sel>
<desc>
</desc>
</method>
<method type="void">
<sel>viewWillMoveToSuperview:</sel>
<arg type="NSView*">newSuperview</arg>
<desc>
<p>Notifies the receiver that its superview is being changed to
<var>newSuperview</var>.</p>
</desc>
</method>
<method type="void">
<sel>viewWillMoveToWindow:</sel>
<arg type="NSWindow*">newWindow</arg>
<desc>
<p>Notifies the receiver that it will now be a view of <var>newWindow</var>.</p>
</desc>
</method>
<method type="id">
<sel>viewWithTag:</sel>
<arg type="int">aTag</arg>
<desc>
</desc>
</method>
<method type="NSRect">
<sel>visibleRect</sel>
<desc>
</desc>
</method>
<method type="float">
<sel>widthAdjustLimit</sel>
<desc>
</desc>
</method>
<method type="NSWindow*">
<sel>window</sel>
<desc>
<p>
Returns the window in which the receiver resides.
</p>
</desc>
</method>
<method type="void">
<sel>writeEPSInsideRect:</sel>
<arg type="NSRect">aRect</arg>
<sel>toPasteboard:</sel>
<arg type="NSPasteboard*">pboard</arg>
<desc>
</desc>
</method>
</class>
</chapter>
</body>
</gsdoc>