画像ビューワの項目

ImageViewerは、各々がそれ自身の画像データ、サイズとオプションの追加の変換を格納して、一つ以上の項目をサポートします。

アイテムを用いて

項目にアクセスするために、ImageViewer.Itemsプロパティを使います。これは型ImageViewerItemsで、項目を簡単に追加/削除/取得/設定/列挙するための標準ICollectionとIListインターフェースを実装します。

メンバ	説明
ImageViewerItems.Add	ビューワに新しい項目を追加します
ImageViewerItems.Insert	指定されたインデックスで、新しい項目をビューワに挿入します。
ImageViewerItems.Remove	ビューワから項目を削除します
ImageViewerItems.RemoveAt	ビューワから指定されたインデックスで項目を削除します
ImageViewerItems.Clear	ビューワからすべての項目を削除します
ImageViewerItems.Item	指定されたインデックスで項目を取得または設定します
ImageViewerItems.Contains	項目がビューワであるかどうか決定します
ImageViewerItems.IndexOf	指定された項目のインデックスを取得します

項目リストまたは項目のプロパティが変更したとき、以下のイベントは画像ビューワで発生します：

メンバ	説明
ItemChanged	項目が変更したとき、発生します
ItemError	項目画像データを設定している間エラーが発生したとき、発生します
SelectedItemsChanged	選択した項目の値の数が変わると発生します。

上記の標準的なコレクション操作へのn追加、ImageViewerItemsは以下をサポートします：

メンバ	説明
GetSelected	ビューワにおいて現在の選択した項目を返します。
選択	ビューワ内で項目を選択します。
AddFromImage	RasterImageオブジェクトから項目を追加します。
InsertFromImage	RasterImageオブジェクトから指定されたインデックスにて項目を挿入します。
AddFromImageUrl	画像ファイルをポイントしているURLから、項目を追加します
InsertFromImageUrl	画像ファイルをポイントしているURLから、指定されたインデックスで項目を挿入します
AddFromImageFile	ディスク上で画像ファイルから項目を追加します
InsertFromImageFile	ディスク上で画像ファイルから指定されたインデックスで項目を挿入します。
UpdateImage	項目のRasterImageオブジェクトを置換または設定します。
UpdateUrl	画像ファイルをポイントするURLから項目の画像データを置換または設定します。
AddFromSvgUrl	SVGとしてのロードをサポートするimageまたは文書ファイルをポイントするURLからの項目を追加します。
InsertFromSvgUrl	imageをポイントしているURLからの指定されたインデックスまたはSVGとしてロードをサポートする文書ファイルで項目を挿入します
AddFromSvgFile	SVGとしてのロードをサポートするimageまたは文書ファイルを格納するディスクファイルからの項目を追加します。
InsertFromSvgFile	image imageを格納しているディスクファイルからの指定されたインデックスまたはSVGとしてロードをサポートする文書ファイルで項目を挿入します
UpdateSvgDocument	項目のSvgDocumentオブジェクトを置換または設定します。

項目は、レイアウトシステムを用いて表示するために準備されます。詳細については、「画像ビューワのレイアウト」を参照してください。

新しい項目は、以下のどれを用いてでも、ビューワに追加されることができます：

RasterImageオブジェクト内のラスター画像データから。
SvgDocumentオブジェクト内のSVG画像データから。
ラスターまたはSVG画像データを格納しているURLから
空項目（画像データなし。ジャストサイズ情報）

下記のコードスニペットのために。下記のスニペットでWindows.Formsによる画像ビューワの利用で使われるcodeを置換します、そして、説明されるcodeを追加します。

汎用的なCode


            // Create a new image viewer instance with a vertical layout
            ImageViewerViewLayout viewLayout = new ImageViewerVerticalViewLayout();
            ImageViewer imageViewer = new ImageViewer(viewLayout);
            // Set some properties
            imageViewer.Dock = DockStyle.Fill;
            imageViewer.BackColor = Color.Bisque;
            // Add a border (need some padding as well)
            imageViewer.ImageBorderThickness = 1;
            imageViewer.ItemPadding = new Padding(imageViewer.ImageBorderThickness);
            // Add it to the form
            this.Controls.Add(imageViewer);
            imageViewer.BringToFront();
            // Add pan/zoom interactive mode. Click and drag to pan the image and ctrl-click
            // and drag to zoom in/out
            imageViewer.InteractiveModes.Add(new ImageViewerPanZoomInteractiveMode());

項目を追加して、削除すること

以下のcodeは新しい項目を作成して、RasterImageとしてTIFファイルをロードして、項目の画像データとしてそれを設定して、ビューワに項目を追加します：


            // Create an item
            ImageViewerItem item = new ImageViewerItem();
            // Load an image into it
            using (RasterCodecs codecs = new RasterCodecs())
               item.Image = codecs.Load(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif", 1);
            // Add it to the viewer
            imageViewer.Items.Add(item);

またはビューワをURLを設定することによって、それ（内部のRasterCodecsインスタンスを使う）をロードさせることによって：


            // Create an item
            ImageViewerItem item = new ImageViewerItem();
            // Load an image into it
            item.Url = new Uri(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif");
            // Add it to the viewer
            imageViewer.Items.Add(item);

ImageViewerItemインスタンスを作成することなく直接項目を追加するために、ImageViewerItemsのメソッドを使うこともできます：


            // Add an item directly
            using (RasterCodecs codecs = new RasterCodecs())
            {
               RasterImage rasterImage = codecs.Load(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif", 1);
               imageViewer.Items.AddFromImage(rasterImage, 1);
            }

または直接RasterImageオブジェクトを作成することのないファイルから：


            // Add an item directly from a disk file
            imageViewer.Items.AddFromImageFile(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif", 1);

またはURLから


            // Add an item directly from a URL
            imageViewer.Items.AddFromImageUrl(new Uri(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif"));

上の場合に、メソッドから戻り値を用いて更なる変更のために追加されるか、ImageViewer.Itemsコレクションにアクセスしている項目を簡単に得ることができます。

ImageViewerは、SVG項目も追加することをサポートします。SVGとしてロードをサポートするSVGファイルまたは任意の文書形式でありえます。このcodeはSVGとしてPDFファイルからページをロードして、それのために項目を追加します：


            // Create an item
            ImageViewerItem item = new ImageViewerItem();
            // Load a page from a PDF file as SVG and set it in the item
            using (RasterCodecs codecs = new RasterCodecs())
               item.SvgDocument = codecs.LoadSvg(@"C:\Users\Public\Documents\LEADTOOLS Images\Leadtools.pdf", 1, null) as SvgDocument;
            // Add it to the viewer
            imageViewer.Items.Add(item);

同様に、RasterImageを使うことに、ビューワをURLを設定することによってSVGドキュメントをロードさせることができます。追加の手順は必要とされます：


            // Create an item
            ImageViewerItem item = new ImageViewerItem();
            // Tell the item to load the data in the URL as SVG, not a RasterImage
            item.LoadUrlAsSvg = true;
            // Load an image into it
            item.Url = new Uri(@"C:\Users\Public\Documents\LEADTOOLS Images\Leadtools.pdf");
            // Add it to the viewer
            imageViewer.Items.Add(item);

AddFromSvgDocument、AddFromSvgUrlまたはAddFromSvgFileは、RasterImage対応する物が説明したのと同じ方法を機能します。

以下のcodeは、ビューワに4つの項目を追加します：


            // Add an item directly
            using (RasterCodecs codecs = new RasterCodecs())
            {
               for (int i = 1; i <= 4; i++)
               {
                  string fileName = string.Format(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr{0}.tif", i);
                  RasterImage rasterImage = codecs.Load(fileName, 1);
                  imageViewer.Items.AddFromImage(rasterImage, 1);
               }
            }
            // pan and zoom to see all the images on top of each other

複数の項目が追加される（または削除されるか、更新される）間、常に、更新処理からビューワを無効にすることが推奨されます。そうすることは、それが中間状態である間、ビューワがその変換と再描画を更新して資源を無駄にしないことを確実にします：


            // Disable any updates till we are done
            imageViewer.BeginUpdate();
            // Add an item directly
            using (RasterCodecs codecs = new RasterCodecs())
            {
               for (int i = 1; i <= 4; i++)
               {
                  string fileName = string.Format(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr{0}.tif", i);
                  RasterImage rasterImage = codecs.Load(fileName, 1);
                  imageViewer.Items.AddFromImage(rasterImage, 1);
               }
            }
            // Update now
            imageViewer.EndUpdate();
            // pan and zoom to see all the images on top of each other

複数の項目で、特定の場所で項目を追加することは、時々目的です。これは、パラメーターとして新しい項目のインデックスを受け取るImageViewerItems.Insertを用いて、簡単に達成されることができます。すべての直接Addメソッド（AddFromImageなど）には、対応する挿入メソッドもあります（InsertFromImageなど）。

ビューワから項目を削除することは、以下のように実行されます。上のコード例から開始して、以下を追加します：


            // Remove the first item
            imageViewer.Items.RemoveAt(0);

もう一度デモを実行して、ビューワが2ページから開始して4の代わりに3つの項目を示している点に注意します。ImageViewerItems.Removeは、その参照によって項目を削除するのに用いられることができます。ImageViewerItems.Clearは、ビューワからすべての項目を削除します（そして、ActiveItemプロパティをnullに設定する）

項目とイメージサイズの関係

各々のImageViewerItemには、項目とそのimageのサイズを決定するために、2つのプロパティがあります：

メンバ	説明
ImageViewerItem.Size	任意のマージン、境界とパディングを含む全部の項目のサイズ
ImageViewerItem.ImageSize	ピクセルのイメージサイズ

「image」または「ドキュメント」ビューワとしてコントロールを使うとき、その後ほとんどの場合、これらの2つの値は同じことです、そして、imageは全部の項目領域を占めます。

「imageリスト」または「サムネイル」ビューワとしてコントロールを使うとき、そして項目の大きさをたとえばテキスト記述の余地を残すイメージサイズより大きくすることは、望ましいです。

両方の場合とも、各項目はそれ自身の項目とイメージサイズをビューワの他のどの項目とはも様々にすることができます。

イメージサイズ

ビューワは、以下の状況に従いImageViewerItem.ImageSizeを計算して、設定します：

ImageViewerItem.ImageSizeの値	ImageViewerItem.ImageまたはImageViewerItem.SvgDocument	説明
LeadSize.Emptyまたは0,0	利用できる	画像データ（imageまたはSvgDocument）からの値を自動計算し、ImageViewerItem.ImageSize。に設定します。上のコードスニペットは、この自動計算に頼ります。
LeadSize.Emptyまたは0,0	設定されません	ImageViewerItem.ImageSizeは、空のままでいます。この項目は非表示となり、レイアウト計算には関わりません。サイズは、項目を表示状態にしようと思った場合に後から設定できます。
空でない	利用できる	ビューワは画像データから値を計算しません、代わりに、値が現状のまま使われます。ビューワは、サイズと一致するために変換またはレンダリングを計算するとき、画像データを自動的に伸縮させます。
空でない	利用できない	画像データが指定されたサイズであるときに項目を処理します。変換計算でこの値を使用しますが、画像データは描画しません。データが利用できるまで、ImageViewerVirtualizerは実際のimageのプレースホルダを提出するために広範囲にこのモードを使用します。このモードが、カスタムレンダリング画像データに使われることもできます。

項目の大きさ

ビューワは、以下の状況に従いImageViewerItem.Sizeを計算して、設定します：

ImageViewer.ItemSizeの値	ImageViewerItem.Sizeの値	説明
LeadSize.Emptyまたは0,0	LeadSize.Emptyまたは0,0	これは、デフォルトモードです。ビューワは上で計算されるImageViewer.ItemSizeの値を使って、ImageViewerItem.Sizeでそれを設定します。それゆえに、項目は両方とものために同じ値を持っています、そして、imageは完全な項目領域を占めます
空でない	LeadSize.Emptyまたは0,0	ビューワは、ImageViewerItem.SizeにImageViewer.ItemSizeの値を設定します。すべての項目は同じサイズを持っています、そして、各々のimageは置かれて、項目の中に自分達だけで場合によることをImageViewerItem.ImageSize値と配置にしました。ビューワが「imageリスト」または「サムネイルブラウザ」として使われるとき、このモードは役に立ちます。
LeadSize.Emptyまたは0,0	空でない	ビューワは、項目のサイズとして、ImageViewerItem.Sizeの値を使います。ImageViewerItem.ImageSizeが、この計算において、そして、どこにimageを項目に置くべきで、レンダリングするべきか決定するだけであるために使われません。
空でない	空でない	ビューワはImageViewer.ItemSizeを無視して、ImageViewerItem.Sizeを使います。

通常、ビューワが「imageリスト」または「サムネイルブラウザ」として使われるとき、ImageViewer.ItemSizeを指定された値に設定しました。これを達成するために、ItemSizeの値を目的のサムネイルサイズプラスパディングに設定します。たとえば、200×200ピクセル。次に、項目を追加します。独自のImageViewerItem.SizeをLeadSize.Empty。のデフォルト値に設定します。先に述べたように、ビューワは、同様に200×200ピクセルと等しいImageViewerItem.Sizeを更新します。このモードで検討すべきことは、各項目内部の画像をどのように表示するのか、です。画像リストモードでは、このサイズ（上記の場合は200 x 200ピクセル）の中の各画像に合うようにします。そのため、ImageViewer.ItemSizeMode の値をFitまたはFitAlwaysに設定します。

解像度

ImageViewerItemには、解像度プロパティもあります。表示する際に画像の論理サイズを検討することが求められる場合は、オリジナルの画像データの解像度（DPI）に設定します。

ImageViewer.UseDpiがtrueに設定されるとき、解像度が使われるだけです。ImageViewer.ScreenDpiと一緒のImageViewerItem.Resolutionの値が、imageを示す方法を計算するとき、使われます。

たとえば、一般的なA4ドキュメントイメージは、8.5×11インチです。imageが300×300の解像度を持っているならば、どちらが2550×3300ピクセルであることができますか。大部分のドキュメントビューワアプリケーションは、そのオリジナルのサイズでこのimageを示そうとします。言い換えると、imageは8.5インチの画面水平スペースと11インチの画面垂直スペースをとります。このコントロールのImageViewer.UseDpiプロパティを使用しない場合は、自分で次のように計算する必要があります。


            viewer.UseDpi = false;
            viewer.Zoom(screenResolution / imageResolution);

上のimageの場合、これは300で割った96（一般的な画面解像度）であるでしょう。または、ImageViewer.UseDpi値をTrueに設定できます。コントロールは上記の式を内部で使用して、以下のようにScaleFactorを1に設定したままにしておきます。


            viewer.UseDpi = true;
            viewer.Zoom(1);

このcodeは、最初のコードスニペットと同じ結果を生みます。

画面解像度がプログラムコードから得られることができる（Windows.Formsなどの）プラットホームでは、ImageViewer.ScreenDpiの値は、作成時に画像ビューアーによって自動的に設定されます。

画面解像度がプログラムコードから得られることができない（JavaScriptなどの）プラットホームでは、ImageViewer.ScreenDpiの値は、96のデフォルト値に設定されます。

ビューワに新しい項目を追加するとき、ImageViewerItem.Resolutionの値は確認されます。値が空である（または0,0）ならば、ビューワはこの情報がプログラムコードから得られることができる（Windows.Formsなどの）プラットホームでこの画像データからこの値を得ようとします。

解像度を自動で取得できないプラットフォーム（JavaScriptなど）では、ユーザーは自分で値を設定しなければなりません。たとえば、LEADTOOLS HTML 5ビューワデモは、この値を得て、項目のためにそれを設定するために、LEADTOOLS RESTサービスを使います。

どちらの場合も、ユーザーはこの値を手動で任意に変更できます。

image所有

RasterImageとSvgDocumentは、両方のIDisposableなオブジェクトです。結局、もはや必要でないとき、codeのいくつかの部分はこれらのオブジェクトを破棄する必要があります。これは、ImageViewer.AutoDisposeImagesプロパティを用いて制御されます。上の例に、trueのデフォルトに、このプロパティの値をそのままにしました。それゆえに、項目が削除されるとき、ビューワはimageまたはSVGドキュメントを破棄します。それを防ぐために、AutoDisposeImagesの値をfalseに設定します。

アクティブ項目

ImageViewerは常に項目を「アクティブ」として識別しておいて、ImageViewer.ActiveItemプロパティを通してこんなにアクセスできます。どんな項目もビューワにある限り、このプロパティはnullに設定されることができません。

項目が削除されるとき、ビューワはそれがアクティブな項目で、もしそうならば、新しい活動として次の最も近い項目を設定するかどうか、自動的に調べます。

ActiveItemは、下記のように単一の項目モードでビューワを使うとき、重要です。

単一の項目Mode

LEADTOOLSで出荷される主なデモなどの若干のアプリケーションは、画像ビューワで複数の項目を必要としないで、常にどちらにでも画像データがある単一の項目を持っています。

アプリケーションのこれらの型のために、画像ビューワはショートカットをImageViewer.Itemsコレクションにアクセスするか、ImageViewerItemを修正することを通常必要とするすべてのプロパティとメソッドに提供します。

これを達成するために、画像ビューワレイアウトはImageViewerSingleViewLayoutに設定されなければなりません、そして、空項目はImageViewer.Itemsで設定されなければなりません。画像ビューワがいつでもアクティブな項目を持っていなければならないため、この項目はActiveItemであるでしょう。これは、正確にデフォルトのコンストラクタ（code）を用いてImageViewerの新しいインスタンスを作成するとき、起こることです：


            // Create a new image viewer instance using the default constructor
            ImageViewer imageViewer = new ImageViewer();
            // Set some properties
            imageViewer.Dock = DockStyle.Fill;
            // Add it to the form
            this.Controls.Add(imageViewer);
            // Verify that we have a view layout, and it is of type single
            Debug.Assert(imageViewer.ViewLayout != null && imageViewer.ViewLayout is ImageViewerSingleViewLayout);
            // Verify that we have a single item
            Debug.Assert(imageViewer.Items.Count == 1);
            // Verify that we have an active item
            Debug.Assert(imageViewer.ActiveItem != null);
            // Load an image into it
            using (RasterCodecs codecs = new RasterCodecs())
               imageViewer.Image = codecs.Load(@"C:\Users\Public\Documents\LEADTOOLS Images\Ocr1.tif", 1);
            // Show the image size
            MessageBox.Show("ImageSize: " + imageViewer.ImageSize.ToString());

ImageViewer.Imageプロパティは、ImageViewer.ActiveItem.Imageへの近道です。詳細については、「画像ビューワのシングルアイテムモード」を参照してください。

ビューワが任意の項目を持っていないならば、すべてのメンバがnull（またはデフォルト値）を返す点に注意します。

追加項目操作とプロパティ

ImageViewerItemクラスは、以下のメンバもサポートします：

メンバ	説明
IsVisibleな	ビューワで項目の表示/非表示設定を制御します。見えない項目は、提出されもしないし、レイアウト計算にも参加しません
IsEnabled	項目が有効にされるかどうか決定します。非アクティブな項目は提出されて、レイアウト計算に参加するが、対話モードイベントに反応しません
IsSelected	項目が選択した状態であるかどうか決定します。選択されたアイテムは、選ばれていない項目と違って提出されるかもしれません
IsHovered	項目がマウスを置いた状態であるかどうか決定します。マウスを置いた項目は、違う形で提出されるかもしれません
ClipImageToContent	画像サイズまたは変換により、項目の境界の外側に座標が表示される場合は、項目領域の内側に画像のレンダリングを制限するかどうかを決定します。
ImageVerticalAlignment	imageがどのように項目境界内で垂直に位置合わせされるか決定します
ImageHorizontalAlignment	imageがどのように項目境界内で水平に位置合わせされるか決定します
テキスト	この項目に関連づけられるテキスト文字列。ページ番号またはファイル名または他のどのテキストデータも示すのに用いられることができます
TextVerticalAlignment	テキストがどのように項目境界内で垂直に位置合わせされるか決定します
TextHorizontalAlignment	テキストがどのように項目境界内で水平に位置合わせされるか決定します
フローター	これのフローターimage項目。
FloaterTransform	position、scaleとimageと関連するフローターimageの回転
FloaterOpacity	フローターの不透明度を制御します。完全にフローターを非表示にするのに用いられることもできます
PageNumber	項目ページ番号。ビューワであるドキュメントのオリジナルのページ番号を保持するのに用いられることができます
PageCount	imageプロパティにおけるページの数
ImageRegionToFloater	フローターにimageで見つけられるリージョンを変換します
CombineFloater	現在のimageでフローターを結合します
タグ	ユーザー定義データ

参照