Gif Object

Overview

The Gif object creates, opens, resizes, manages and saves GIF images. This object was introduced in version 2.0 and is covered in detail in Chapter 9 - GIF Output.

Member List

Properties

Binary As Variant (Read-only)

Returns a binary array of bytes representing an output GIF image. This property is useful for saving images in the database as BLOBs.

See also: Chapter 9 - GIF Output.

BrushColor As Long (Read/Write)

Specifies a brush color index for the current frame. Affects the inside areas of a bar, circle, ellipse, quadrilateral and pie, unless BrushSolid is set to False.

See also: Section 9.2 - AspJpeg's GIF Output Support.

BrushSolid As Boolean (Read/Write)

Specifies whether the brush for the current frame is solid or transparent. True (solid) by default.

See also: Section 9.2 - AspJpeg's GIF Output Support.

CurrentFrame As Long (Read/Write)

Returns or specifies the current frame within a GIF image. All drawing operations are always performed on the current frame. The frame index is 1-based and must be between 1 and FrameCount.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Delay As Long (Read/Write)

Returns or specifies the delay (in 100ths of a second) of the current frame in an animated GIF. 100 (1 second) by default.

See also: Section 9.2 - AspJpeg's GIF Output Support, Section 9.7.2 - Other Animation Management Properties.

DisposalMethod As Long (Read/Write)

Controls the way frames in an animated GIF replace each other. Valid values are:

  1. Leave the current image in place and draw the next image on top of it. This is the default method.
  2. The canvas should be restored to the background color before the next image is rendered.
  3. The canvas should be restored to its previous state before the current image is drawn.

See also: Section 9.4 - Using External Images as Frames, Section 9.7.2 - Other Animation Management Properties.

FontAlign As Long (Read/Write)

Specifies text alignment for the PrintTextEx method. Valid values are: 0 - left (default), 1 - right, 2 - center and 3 - justified. If a value other than 0 is specified, the FontWidth property must also be specified. This property does not affect the PrintText method.

See also: Section 9.2 - AspJpeg's GIF Output Support.

FontFamily As String (Read/Write)

Specifies font family such as "Arial" or "Courier New". A system-default font is used if this property is not specified, or the specified font is not found. This property is to be used in conjunction with the PrintText method. It does not affect the PrintTextEx method.

See also: Section 9.2 - AspJpeg's GIF Output Support.

FontRotation As Long (Read/Write)

Specifies text rotation angle (in degrees, rotation is counter-clockwise) for both the PrintText and PrintTextEx methods. 0 (horizontal) by default.

See also: Section 9.2 - AspJpeg's GIF Output Support.

FontSize As Long (Read/Write)

Specifies font size for both PrintText and PrintTextEx methods, in pixels. 24 by default.

See also: Section 9.2 - AspJpeg's GIF Output Support.

FontSpacing As Long (Read/Write)

Specifies line spacing adjustment (in pixels) for the PrintTextEx method. A positive value increases the default line spacing, a negative value decreases it.

See also: Section 9.2 - AspJpeg's GIF Output Support.

FontWidth As Long (Read/Write)

Specifies the width of an area in which a text string drawn via PrintTextEx is to be inscribed. Activates word wrapping if necessary. This property must also be set if the FontAlign property is set to a value other than 0 (left alignment).

See also: Section 9.2 - AspJpeg's GIF Output Support.

FrameCount As Long (Read/Write)

Returns the total number of frames in the GIF image.

See also: Section 9.2 - AspJpeg's GIF Output Support.

FrameHeight As Long (Read/Write)
Returns or specifies the height of the current frame in pixels.
FrameOffsetX As Long (Read/Write)
Returns or specifies the horizontal offset of the current frame in pixels.
FrameOffsetY As Long (Read/Write)
Returns or specifies the vertical offset of the current frame in pixels.
FrameToSave As Long (Read/Write)

0 by default. If set to a valid 1-based frame index, instructs the Gif object to only save the specified frame when a Save method is called. This property is mostly useful for debugging only.

See also: Section 9.7.3 - Saving Individual Frames.

FrameWidth As Long (Read/Write)
Returns or specifies the width of the current frame in pixels.
Height As Long (Read/Write)

Returns or specifies the overall height of a GIF image in pixels. This property does not affect the size of individual frames within the image. If an image has no frames yet, callings AddFrame or AddImage for the first time sets the Height to that of the frame being added.

See also: Section 9.4 - Using External Images as Frames.

Loops As Long (Read/Write)

Returns or specifies the number of times an animated GIF runs its sequence before stopping. 0 by default which means the sequence runs indefinitely.

See also: Section 9.7.2 - Other Animation Management Properties.

PaletteItem(Global As Boolean, Index as Long) As Long (Read/Write)

This parameterized property returns or specifies an RGB component of a palette item pointed to by Index in a palette specified by Global. If Global is True, the global palette is used, otherwise the local palette pertaining to the current frame is used. Index must be an integer between 0 and PaletteSize * 3 - 1. For example, PaletteItem(True, 4) refers to the Green component of the 2nd entry of the global palette.

See also: Section 9.5 - Palette Management.

PaletteSize(Global As Boolean) As Long (Read/Write)

This parameterized property returns or specifies the number of entries in a palette. If Global is True, the global palette is used, otherwise the local palette pertaining to the current frame is used. Setting a palette size to 0 effectively removes the palette.

See also: Section 9.5 - Palette Management.

PenColor As Long (Read/Write)

Specifies a pen color index for the current frame. This property affects all drawing methods and also PrintText and PrintTextEx.

See also: Section 9.2 - AspJpeg's GIF Output Support.

PenWidth As Long (Read/Write)

Specifies a pen width for the current frame. This property affects all drawing methods.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Pixels(Col As Long, Row as Long) As Long (Read/Write)
This parameterized property returns or sets the color index for a pixel specified by (Col, Row) within the current frame.
Quantization As Long (Read/Write)

Controls the quality of true-color to 256-color conversion when AddImage is called. Valid values are from 1 to 30, 1 being the highest quality but also the slowest speed. The default value is 20 which provides an adequate balance between speed and quality. Setting this property to anything below 10 is not recommended for performance considerations.

See also: Section 9.4 - Using External Images as Frames.

TranspColor As Short (Read/Write)

Returns or specifies the transparent color index for the current frame. Setting this property has a side effect of setting the TranspColorSet property to True.

See also: Section 9.6 - Transparency.

TranspColorSet As Boolean (Read/Write)

Returns True if the current frame has a transparent color index associated with it. The index itself is returned via the TranspColor property. Setting this property to False effectively removes a transparent color from the current frame.

See also: Section 9.6 - Transparency.

Width As Long (Read/Write)

Returns or specifies the overall width of a GIF image in pixels. This property does not affect the size of individual frames within the image. If an image has no frames yet, callings AddFrame or AddImage for the first time sets the Width to that of the frame being added.

See also: Section 9.4 - Using External Images as Frames.

Methods

Sub AddFrame(Width As Long, Height As Long, OffsetX As Long, OffsetY As Long)

Adds an empty frame to the image with the specified width, height, and offsets. The newly added frame becomes the current one and is filled with color index 0. It has no local palette. The new frame is added to the end of the animation sequence.

If this is the first frame in the image, the overall image width and height are assigned the values from the new frame.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub AddImage(Image As ASPJpeg, OffsetX As Long, OffsetY As Long)

Adds a new frame populated with Image which is an instance of the ASPJpeg object. This method performs a true-color to 256-color conversion. The speed and quality of the conversion is determined by the Quantization property.

The new frame is assigned a 256-color local palette computed from the image being converted for optimal quality.

See also: Section 9.4 - Using External Images as Frames

Sub Clear()
Removes all frames from the image. An empty image cannot be drawn on, resized, or saved.
Sub DrawArc(X As Long, Y As Long, Radius As Long, StartAngle As Long, ArcAngle As Long)

Draws an circular arc with a center in (X, Y) on the current frame. The arc radius is specified by Radius (in pixels). StartAngle specifies the angle (in degrees) of the arc's starting point, and ArcAngle specifies the arc's span, in the counterclockwise direction. Uses the current pen. Arcs are not filled.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawBar(Left As Long, Top As Long, Right As Long, Bottom As Long)

Draws a rectangle specified by the coordinates of its upper-left and lower-right corners (in pixels) on the current frame using the current pen and brush.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawCircle(X As Long, Y As Long, Radius As Long)

Draws a circle specified by its center coordinates and radius (in pixels) on the current frame using the current pen and brush.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawEllipse(Left As Long, Top As Long, Right As Long, Bottom As Long)

Draws an ellipse specified by the coordinates of its bounding rectangle (in pixels) on the current frame using the current pen and brush.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawLine(x1 As Long, y1 As Long, x2 As Long, y2 As Long)

Draws a line specified by the coordinates of its starting and ending points (in pixels) on the current frame using the current pen.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawPie(X As Long, Y As Long, Radius As Long, StartAngle As Long, EndAngle As Long)

Draws a pie-shaped wedge with a center in (X, Y) on the current frame. The radius is specified by Radius (in pixels). StartAngle specifies the angle (in degrees) of the arc's starting point, and EndAngle specifies the arc's ending point, in the counterclockwise direction. Uses the current pen and brush.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawQuad(X1 As Long, Y1 As Long, X2 As Long, Y2 As Long,X3 As Long, Y3 As Long,X4 As Long, Y4 As Long)

Draws a quadrilateral specified by the coordinates of its 4 corners on the current frame using the current pen and brush.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub DrawRoundRect(Left As Long, Top As Long, Right As Long, Bottom As Long, CornerWidth As Long, CornerHeight As Long)

Draws a rectangle with rounded corners on the current frame using the current pen and brush. The rectangle is specified by the coordinates of its upper-left and lower-right corners (in pixels). The corners are rounded by an ellipse with the width and height specified by CornerWidth andCornerHeight.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub FindClosestColor(Global As Boolean, R As Short, G As Short, B As Short)

Scans the specified palette and looks for a color closest to the RGB values specified, and returns its index. If Global is true, the global palette is scanned, otherwise the local palette pertaining to the current frame is scanned.

See also: 9.7.4 - Finding a Closest Color.

Sub MoveFrame(OriginalIndex As Long, DesiredIndex As Long)

Moves the frame specified by the first argument to a new location specified by the 2nd argument. If the current frame is affected by the move, the CurrentFrame property will change to reflect the new position of the current frame.

See also: 9.7.1 - Other Frame Management Methods.

Sub Open(Path As String)

Opens a GIF image from a file. Populates all the frames and assigns all the Gif object properties. Path must point to a GIF file, any other format will be rejected.

See also: 9.3 - GIF Image Resizing.

Sub OpenBinary(Image As Variant)

Same as Open but opens a GIF image from a binary source such as a recordset. Image must be a safe array of bytes containing a GIF image. All other formats will be rejected.

See also: 9.3 - GIF Image Resizing.

Sub PrintText(Image As Variant)

Same as Open but opens a GIF image from a binary source such as a recordset. Image must be a safe array of bytes containing a GIF image. All other formats will be rejected.

See also: 9.3 - GIF Image Resizing.

Function PrintTextEx(Text As String, X As Long, Y As Long, FontPath As String) As Long

Prints anti-aliased text using a TrueType/OpenType or Type 1 font specified by its physical path. Supports word wrapping, rotation, text alignment (to the left, right, center and justified) and adjustable line spacing.

Text - specifies the text string to be printed (in Unicode format). May contain CR/LF characters for multi-line display.

X, Y - coordinates of the lower-left corner of the first character of the first line, relative to the upper-left corner of the image.

FontPath - specifies a physical path to the font file. The font does not need to be properly registered on the system as long as the path to the font file is known.

Additional optional parameters are specified via the following properties:

PenColor - specifies the text color index.

FontRotation - specifies the rotation angle around the (X, Y) point in degrees. A positive value creates a counter-clockwise rotation.

FontSize - specifies font size in pixels.

FontSpacing - specifies an adjustment in pixels for the default line spacing when multi-line text is being rendered. A positive value increases the line spacing, a negative one decreases it.

FontWidth - specifies the width of an area in which the text string is to be inscribed. Word wrapping occurs if the text string does not fit in the area. This property must also be set if non-default text alignment is specified via FontAlign.

FontAlign - specifies text alignment. Valid values are: 0 - left (default), 1 - right, 2 - center, and 3 - justified. For values other than 0, FontWidth must also be specified.

Returns the width (in pixels) of the text string being drawn. If the string is split into multiple lines, returns the width of the longest line.

Sub RemoveFrame(Index As Long)

Removes the frame specified by its index. If the current frame is being removed, another frame becomes current, and the CurrentFrame property may change.

See also: Section 9.2 - AspJpeg's GIF Output Support.

Sub Resize(Optional NewWidth, Optional NewHeight, Optional Interpolation)

Resizes the current image while preserving its transparency and animation. If either NewWidth or NewHeight arguments are specified (but not both) the omitted argument is calculated automatically to preserve the original aspect ratio. Interpolation is 0 (nearest-neighbor algorithm) by default. Using other algorithms may cause undesired artifacts when resizing certain animated images.

See also: Section 9.3 - GIF Image Resizing.

Sub Save(Path As String)

Saves the resultant GIF image to disk. If a file specified by Path already exists, it will be overwritten.

See also: Chapter 9 - GIF Output.

Function SaveUnique(Path As String) As String

Same as Save but generates a unique filename if the file specified by Path already exists. A unique name is generated to avoid overwriting an existing file by appending a number in parentheses after the filename, such as image(1).jpg, image(2).jpg, etc. Returns the filename (without the path) under which the image ends up being saved.

See also: Chapter 9 - GIF Output.

Sub SendBinaryOptional ContentDisposition)

Sends the resultant image directly to the client browser by internally calling Response.BinaryWrite. Automatically sets the Content-Type header to "image/gif".

If ContentDisposition is set, also sets the "Content-Disposition" header to a value specified by this argument. A typical value for this argument is

filename=image_name.gif"

or

"attachment;filename=image_name.gif"

You can only use this method in an IIS environment.

See also: Chapter 9 - GIF Output.

Sub SetPalette(Global As Boolean, Palette As Variant)

Specifies a new palette by supplying an array of RGB values for all entries at once.

If Global is set to True, the global palette is changed, otherwise the local palette pertaining to the current frame is changed.

Palette is a safe array of numbers that are treated as consecutive RGB values of all palette entries. The size of the array must be 3 multiplied by a valid GIF palette size (2, 4, 8, ..., 256 entries.)

See also: 9.5 - Palette Management.

Sub SetStockPalette(Global As Boolean, Type As Long)

Specifies a built-in (or "stock") palette by number.

If Global is set to True, the global palette is changed, otherwise the local palette pertaining to the current frame is changed.

Type selects one of the available stock palettes. The valid values are:

  1. 216 web-safe colors.
  2. 16 standard HTML colors.
  3. 256 grayscale colors.

See also: 9.5.3 - Stock Palettes.

Other Products
AspUpload
AspEmail
AspEmail.NET
AspJpeg.NET
AspHEIF
AspPDF
AspPDF.NET
AspEncrypt
AspGrid
AspUser