Introduction

ATImageBox Component

ATImageBox is a Delphi/C++Builder control which displays a scrollable image. It has such properties as ImageFitToWindow, ImageCenter, ImageScale etc, so it's easy for you to control the placement of an image. Image can be dragged by mouse and scrolled by keys and mouse wheel. An informational label can be displayed over the left-top control corner.

Screenshot of demo application

Predefined shortcuts:

Arrows | Scroll image by a "line size" (50 pixels)
Ctrl + Arrows | Scroll image to an edge (leftmost, rightmost, top, bottom)
Home, End, PgUp, PgDn | Scroll image by a "page size" (control size minus small gap)
Mouse Wheel | Scroll image vertically
Shift + Wheel | Scroll image horizontally
Ctrl + Wheel, Left mouse btn + Wheel | Change image scale

Note: To load Unicode-named image files you need to use Tnt Unicode Controls. After you install this library, enable its usage in the ATImageBoxOptions.inc file.


Installation

To install the component in the Delphi/C++Builder IDE:
  • Create a new package
  • Add ATImageBox.pas file to this package
  • Compile and install this package

Component will be installed into the "Samples" page of component pallette.


Usage: Properties

Properties

Image
(public, read-only) 		Image object. You need to access this object's LoadFromFile method to load new image. This object is of type TATImage, which is the same as TImage but with additional properties:
  • Resample: Enables image resampling after scaling.
  • ResampleDelay: Delay (in msec) between finishing of control resizing and beginning of the resampling operation.
  • ResampleBackColor: Color of image background. You need to pass the value of TATImageBox.Color here.

Notes:

  • Use Image.Cursor to change default control cursor.
  • Resampling option is not supported under Win9x.
ImageWidth
ImageHeight
(public, read-only) 		Original image width and height.
These values are updated when you call UpdateImageInfo method. You must call it immediately after you load a new image.
ImageScale
(public) 		Current image scale in percents (%).
On ImageScale assignment, ImageFitToWindow property becomes False.
ImageLabel
(public, read-only) 		TLabel object that is the label over the left-top control corner.
Access ImageLabel's properties to change appearance of a label: Visible, Caption, Font etc.
ImageFitToWindow Enables to fit image (proportionally) to the current control client area.
If ImageFitOnlyBig = True and image is smaller than control size, image will not be scaled.
ImageFitOnlyBig | Enables to fit only images larger than current control size.
ImageFitWidth | Enables to fit only image's width, not height.
ImageFitHeight Enables to fit only image's height, not width.
Both ImageFitWidth/ImageFitHeight cannot be set.
ImageCenter | Enables to center smaller images in control client area.
ImageKeepPosition | Enables to keep image relative position on scaling.
ImageDrag | Enables to drag large images by mouse.
ImageDragCursor Cursor used for image dragging state (default is crSizeAll).
To change cursor for default idle state, use Image.Cursor.
ImageScaleCursor Cursor used for image scaling state (default is crSizeNS).
Used when user scales image by (Left mouse button + Wheel) shortcut.
Focusable | Enables control to catch focus on mouse click.


Usage: Methods

Methods

procedure IncreaseImageScale(AIncrement: Boolean);

Increases (AIncrement = True) or decreases the current image scale using predefined set of scale values.
The minimal value in this set is 7, and the maximal is 1600.

procedure UpdateImageInfo;

Updates internal image info fields.
Must be called after you load a new image.
The typical image load procedure can look like this:

  procedure TFormMain.LoadImage(const AFileName: string);
  begin
    try
      try
        ATImageBox1.Image.Resample := True;
        ATImageBox1.Image.ResampleBackColor := ATImageBox1.Color;
        ATImageBox1.Image.Picture.LoadFromFile(AFileName);
      finally
        ATImageBox1.UpdateImageInfo;
      end;
    except
      Application.MessageBox('Could not load image', 'Error',
        MB_OK or MB_ICONERROR);
    end;
  end;


Usage: Events

Events

OnScroll | Fired on horizontal or vertical scrolling.
OnOptionsChange | Fired after some option has been changed by user. For example, image scale can be changed by (Left mouse button + Wheel) shortcut.
OnAfterPaint | Fired after image painting is done. You can use this event to perform some custom painting on the image, e.g. draw lines, circles etc. Canvas and painting rectangle are passed as parameters.


License

This package, unless otherwise stated in the particular source code file, is distributed under Mozilla Public License Version 1.1 (the "License"). You may obtain a copy of the License at http://www.mozilla.org/MPL/

Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.

Copyright © 2006-2007 Alexey Torgashin.


Versions history

1.7.5 (jan 2012):
  • Added: event OnAfterPaint.
1.7.4 (jun 2011):
  • Added: prop ImageFitWidth to fit only width.
  • Added: prop ImageFitHeight.
  • Changed: IncreaseScale minimal value is 1%.
1.7.2 (10.2007):
  • Added: Mouse shortcut for zoom: left button + wheel.
  • Changed: OnImageScaleChange event removed, OnOptionsChange added instead.
1.7.1 (08.2007):
  • Fixed: Resampling is now disabled for animated GIFs and metafiles.
  • Fixed: Resampling is now disabled under Win9x (it is supported only under NT).
1.7.0 (07.08.2007):
  • Added: Image object is now of type TATImage, and TATImage type supports additional Resample and ResampleDelay properties.
  • Added: Image's IncrementalDisplay property correctly handled.
  • Fixed: ImageFitToWindow works wrong in some cases.
1.6.2 (16.06.2007):
  • Added: Ctrl + Mouse Wheel changes image scale.
  • Added: IncreaseImageScale method.
  • Added: OnImageScaleChange event.
1.6.0 (28.03.2007):
  • Changed: License updated to MPL 1.1.
  • Fixed: ImageFitToWindow property work.
1.5.9 (04.03.2007):
  • Changed: Removed helper units ATx*.pas.
  • Changed: One event OnScroll instead of OnVScroll/OnHScroll.
  • Fixed: Flickering when ImageKeepPosition is on.
  • Added: Focusable property.
1.5.8 (28.02.2007):
  • Initial release; previously the code was a part of ATViewer component, so the such initial number.


Contacts

If you encounter problems with this component, or you have comments or suggestions, contact the author:

Alexey Torgashin
http://www.uvviewsoft.com