mirror of
https://github.com/gnustep/libs-gui.git
synced 2025-04-25 18:30:56 +00:00
12af57fe8b
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/gui/trunk@24200 72102866-910b-0410-8b05-ffd578937521
129 lines
8.5 KiB
Text
129 lines
8.5 KiB
Text
@c GNUstep AppKit Guide
|
|
@c
|
|
@c Copyright (c) 2005-2006 Christopher Armstrong.
|
|
@c
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
@c under the terms of the GNU Free Documentation License, Version 1.2
|
|
@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
@c A copy of the license is included in the section entitled "GNU
|
|
@c Free Documentation License".
|
|
@c
|
|
@c This documentation is provided on an "AS IS" BASIS, WITHOUT WARRANTY
|
|
@c OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
|
|
@c TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
|
@c PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND USEFULNESS
|
|
@c OF THE DOCUMENTATION IS WITH YOU (THE LICENSEE). IN NO EVENT WILL THE COPYRIGHT
|
|
@c HOLDERS BE LIABLE FOR DAMAGES, INCLUDING ANY DIRECT, INDIRECT,
|
|
@c SPECIAL, GENERAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF
|
|
@c THE USE OR INABILITY TO USE THIS DOCUMENTATION (INCLUDING BUT NOT
|
|
@c LIMITED TO LOSS OF DATA, USE, OR PROFITS; PROCUREMENT OF SUBSTITUTE
|
|
@c GOODS AND SERVICES; OR BUSINESS INTERUPTION) HOWEVER CAUSED, EVEN
|
|
@c IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
@node images, fdl, dataexchange, Top
|
|
@chapter Images and Imageviews
|
|
|
|
@anchor{Images and Imageviews}
|
|
GNUstep provides mechanisms for the retreival and display of images. A number of objects beginning with @code{NSImage}@footnote{Including NSImage} exist, each with slightly different functions.
|
|
|
|
An @dfn{image} is represented using an instance of the @code{NSImage} class. You can create these using the path or URL of a file, raw image data or a pasteboard.
|
|
|
|
Images may contain zero or more image representations, or @dfn{imagereps}. For example, a photographic image may contain both black and white and colour representations, or representations at different resolutions. The purpose of this is to allow GNUstep to select the best representation for a particular device. GNUstep may select a lower-resolution representation for a screen, while selecting the highest resolution representation for printed output. If there was also a vector representation, it may choose to use it for printed output. An imagerep is represented by an instance of a @code{NSImageRep} subclass.
|
|
|
|
An image by itself is not enough for rendering. Images are rendered on a window using an @code{NSImageView} object. These let you set the alignment and scaling for displaying the image. They also let you set a graphical border using the @code{-setFrameStyle:} method. @code{NSImageView} is a control, so the normal control/cell model applies to it.
|
|
|
|
If you only need to display an image on it's own, use @code{NSImageView}. For more complicated image rendering, e.g. inside of custom views, use @code{NSImage} to draw or composite at a certain point.
|
|
|
|
@section Using NSImage
|
|
|
|
Whether using @code{NSImageView} or not, you will have to create an @code{NSImage} object. It provides a number of constructors for loading an image with a path, a URL or a data object (@code{NSData}). Note that for loading from a file or URL, two sets of methods are provided. These have subtly different meanings, as shown below:
|
|
|
|
@table @code
|
|
|
|
@item -initWithContentsOfFile:
|
|
@itemx -initWithContentsOfURL:
|
|
These methods load the image from the specified location, and create image representations for rendering later.
|
|
|
|
@item -initByReferencingFile:
|
|
@itemx -initByReferencingURL:
|
|
These methods don't actually load the image straight away. Instead, when you try to composite or draw the image at a location, it loads the image from disk and generates a representation at that time.
|
|
|
|
@end table
|
|
|
|
From here, an image can be drawn within a view using any of the drawing/compositing/dissolving methods. You can also get at the imagereps using the @code{-representations} method (amongst others).
|
|
|
|
@section Drawing Images
|
|
|
|
@code{NSImage} provides a number of methods for drawing an image. It also provides quite a number means to control how an image is composited at its destination.@footnote{Note that many of the mechanisms provided for compositing may not be supported in some backends i.e. the Windows backend.} @dfn{Compositing} refers to the way the image is rendered onto the destination surface.
|
|
|
|
Simply drawing an image into your view may be achieved with the @code{-drawRepresentation:inRect:} method. In other cases, you may wish to draw it onto a destination surface with a compositing operation, in which case you can use the @code{-drawAtPoint:fromRect:operation:fraction:} or @code{-drawInRect:fromRect:operation:fraction:} methods.
|
|
|
|
These take a rectangle from the source image, and composite it onto a destination surface. The compositing operation specifies how the image is blended with the destination surface, and is a constant in @code{NSCompositingOperation}. These constants define what the destination image looks like after a composite, as a result of combining the source and destination image. @footnote{These compositing operations are the same as those described in the (now well-studied) academic paper, @cite{Compositing Digital Images} by Thomas Porter and Tom Duff in 1984.}
|
|
@table @code
|
|
@item NSCompositeClear
|
|
The destination is left transparent.
|
|
|
|
@item NSCompositeCopy
|
|
The source image appears at the destination.
|
|
|
|
@item NSCompositeSourceOver
|
|
The source image appears wherever it is opaque, and the destination image elsewhere.
|
|
|
|
@item NSCompositeSourceIn
|
|
The source image appears wherever both the source and destination are opaque, and is transparent elsewhere.
|
|
|
|
@item NSCompositeSourceOut
|
|
The source image appears where the source image is opaque but the destination image is transparent, and is transparent elsewhere.
|
|
|
|
@item NSCompositeSourceAtop
|
|
The source image appears wherever both images are opaque, the destination appears wherever the destination is opaque but the source image is transparent, and the result is transparent elsewhere.
|
|
|
|
@item NSCompositeDestinationOver
|
|
The destination image appears wherever it is opaque, and the source image elsewhere.
|
|
|
|
@item NSCompositeDestinationIn
|
|
The destination image appears where both images are opaque, and the result is transparent elsewhere.
|
|
|
|
@item NSCompositeDestinationOut
|
|
The destination image appears wherever it is opaque but the source image is transparent, and it is transparent elsewhere.
|
|
|
|
@item NSCompositeDestinationAtop
|
|
The destination image appears wherever both images are opaque, the source image appears wherever the source image is opaque but the destination is transparent, and the result is transparent elsewhere.
|
|
|
|
@item NSCompositeXOR
|
|
The result of and exclusive OR operation between the bits defining the pixels in bothe images.
|
|
|
|
@item NSCompositePlusDarker
|
|
The result of adding the values of the colour components of the pixels in both images, with the result approaching zero as a limit.
|
|
|
|
@item NSCompositePlusLighter
|
|
The result of adding the values of the colour components of the pixels in both images, with the result approaching one as a limit.
|
|
@end table
|
|
|
|
The @var{fraction} parameter corresponds to the coverage of the source alpha channel with zero making the source transparent and one making the source fully opaque.
|
|
|
|
@section Working with image representations
|
|
|
|
Quite a number of classes inherit from @code{NSImageRep} to provide means to load different types of image formats, such as bitmaps, TIFF images, etc:
|
|
@table @code
|
|
@item NSBitmapImageRep
|
|
For bitmap (raster) images, @code{NSBitmapImageRep} is used. PNG, JPG and TIFF image file formats would be represented with the class.
|
|
|
|
You can retreive information about the image with methods such as @code{-bitsPerPixel} or @code{-isPlanar}. For image formats that can store metadata (such as resolution information or camera settings), the @code{-valueForProperty:} and @code{-setProperty:withValue:} methods can be used to manipulate it.
|
|
|
|
If necessary, it contains initialisers for instantiating it from raw data(@code{-initWithData:}) and from the display (@code{-initWithFocusedViewRect:}.
|
|
|
|
@item NSCachedImageRep
|
|
This image representation is cached bitmap left over from the result of executing some instructions or data. It lives inside an off-screen window.
|
|
|
|
@item NSCustomImageRep
|
|
These are representations which can be drawn in a manner that is defined by the application. You initialize these with a selector that is executed against a delegate object when @code{-draw} is called on the representation.
|
|
|
|
@item NSEPSImageRep
|
|
Unsupported.
|
|
|
|
@end table
|
|
|
|
The @code{NSImageRep} class itself also provides a number of methods for gaining information about what kinds of file formats GNUstep supports, and for instantiating images dynamically based on raw image data or the contents of a file or URL.
|
|
|
|
|