Description
Image data previously placed on the the clipboard is pasted into the ImageToDisplay.
-
Return Type
-
None
-
Syntax
-
object.EditPasteAoi [OptionFlags], [AlignLeftTop], [BlendPercent], [BlendOptionFlags]
The EditPasteAoi Method syntax has these parts: |
| object | An expression evaluating to an object of type McDisplay. | | OptionFlags | Optional. A mcEditPasteAoiOptionFlags enumeration, as described in settings. mcEditPasteAoiOptionFlags : These flags (along with the
| | AlignLeftTop | Optional. A Variant value. VARIANT : If given, this is a LONGPOINT or an array of two numeric values (x,y) that gives the alignment between the clipboard image and the ImageToDisplay. It is given as the offset of the left,top of the clipboard image into the ImageToDisplay; the values may be positive or negative. When the paste is previewed (OptionFlags mcepaofPreviewThePaste flag is set) then this offset is used as the intial blending alignment for the preview, otherwise it is used as the final paste alignment.
If the AlignLeftTop argument is not given, then it is set so that the left,top of the clipboard image AOI bounds is aligned with the left,top of the ImageToDisplay AOI bounds.
| | BlendPercent | Optional. A Long value. long : This value is used wherever a blending percentage is needed both during preview (OptionFlags mcepaofPreviewWithBlend flag is set) and/or during the apply of the paste (OptionFlags mcepaofApplyWithBlend flag is set). The BlendPercent specifies the percentage of the clipboard luminance that is to be blended into the ImageToDisplay; 100% is a full paste. If the default value of -1 is given, then the blend percentage is taken from the settings saved by Application.CommandDialogs("Preferences").Pages("PasteOptions").
| | BlendOptionFlags | Optional. A mcViewBlendStyle enumeration, as described in settings. mcViewBlendStyle : These blending flags are used wherever a blending is done both during preview (OptionFlags mcepaofPreviewWithBlend flag is set) and/or during the apply of the paste (OptionFlags mcepaofApplyWithBlend flag is set). However, whether or not the mcepaofPreviewWithBlend and/or mcepaofApplyWithBlend option flags are set, the BlendOptionFlags mvbsMaskBySourceAoi and/or mvbsMaskByDestAoi flags are always honored to determine if the blend/paste should be restricted to pixels interior to the source and/or destination AOI(s).
If the default value of mvbsUseSettings is given, then the blend percentage is taken from the settings saved by Application.CommandDialogs("Preferences").Pages("PasteOptions").
|
Settings The settings for OptionFlags are:
|
 | mcepaofUseSettings | -1 |
When given as the OptionFlags argument, then the EditPasteAoi options are determined from the settings saved by Application.CommandDialogs("Preferences").Pages("PasteOptions").
|
| mcepaofDefault | 0 |
No preview takes place, the paste is applied without blending (i.e., always 100), and the AOI after the paste is left unchanged (equivalent to the mcepaofAoiAfter_KeepDestUnchanged:IQL~mcEditPasteAoiOptionFlags~mcepaofAoiAfter_KeepDestUnchanged% option).
|
| mcepaofPreviewThePaste | 1 |
If there is an OwningView, then a McBlendTool is invoked on that McView to allow the user to position the pasting image. If there is no OwningView, then use of this flag is an error. In the default case (where OptionFlags are mcepaofDefault), then this flag is automatically turned off if there is no OwningView.
|
| mcepaofPreviewWithBlend | 2 |
During any user preview (see the mcepaofPreviewThePaste flag) the clipboard image is shown with blending, using the BlendPercent and BlendOptionFlags. If this flag is not set, then during preview the clipboard image is shown with 100 percent intensity, and no luminance masking is done. But in any case, the BlendOptionFlags mvbsMaskBySourceAoi and mvbsMaskByDestAoi flags are always honored during preview.
|
| mcepaofApplyWithBlend | 4 |
During the actual apply of the clipboard image into the ImageToDisplay the clipboard image is blended with the ImageToDisplay, using the BlendPercent and BlendOptionFlags. If this flag is not set, then the clipboard image is pasted into the ImageToDisplay with 100 percent intensity, and no luminance masking is done. But in any case, the BlendOptionFlags mvbsMaskBySourceAoi and mvbsMaskByDestAoi flags are always honored during the paste.
|
| mcepaofAoiAfter_PasteSrcAoi | 16 |
After the paste is applied to the ImageToDisplay, the aligned clipboard image's AOI is made the new AOI. If the clipboard image has no AOI, then a rectangular AOI encompasing its entire bounds is created.
|
| mcepaofAoiAfter_KeepDestUnchanged | 32 |
After the paste is applied to the ImageToDisplay, the ImageToDisplay's AOI is left unchanged.
|
| mcepaofAoiAfter_IntersectSrcAndDest | 48 |
After the paste is applied to the ImageToDisplay, the intersection between the ImageToDisplay's AOI and the aligned clipboard image's AOI is made the new AOI. If this intersection is empty, then there will be no ImageToDisplay AOI. If either the ImageToDisplay or the clipboard image has no AOI, then a rectangular AOI encompasing its entire bounds is created for use in creating the intersection.
|
| mcepaofAoiAfter_ClearToNone | 64 |
After the paste is applied to the ImageToDisplay, the ImageToDisplay's AOI is cleared.
|
| mcepaofAoiAfter_Mask | 112 |
Mask for the the mcepaofAoiAfter_... options. Only one of the mcepaofAoiAfter_... options may be set.
|
| mcepaofDoNotApplyThePaste | 256 |
If this flag is set, then the actual paste operation is not performed after the user completes the preview. Instead the preview McBlendTool is only started and it is the caller's responsibility to monitor when it ends and then take any further action. You would use this flag if you needed to perform some action after the user has set the paste position during the preview, but before the paste is done (e.g., to capture Undo information). Note that this flag makes no sense and is ignored unless a preview is being done. See the Remarks and Examples with the McDisplay.EditPasteAoi method for more information on how to monitor the McBlendTool completion.
|
The settings for BlendOptionFlags are:
|
| mvbsUseSettings | -1 |
This value is legal only for the McDisplay.EditPasteAoi BlendOptionFlags argument. When it is given as the BlendOptionFlags argument, then blend style values are determined from the settings saved by Application.CommandDialogs("Preferences").Pages("PasteOptions").
|
| mvbsNormal | 0 |
The blending formula is used for all pixels in the BlendingImage that intersect the ImageToDisplay. No LUT is applied to the BlendingImage when getting the RGB display values. When used as the McDisplay.EditPasteAoi BlendOptionFlags argument, then values for the BlendOptionFlags are determined from the settings saved by Application.CommandDialogs("Preferences").Pages("PasteOptions").
|
| mvbsLighter | 1 |
Blending only occurs if an ImageToDisplay pixel is brighter than the coresponding BlendingImage pixel. The comparison is done on the luminance channel if there is one (e.g., for monochrome or HSI image types, or by averaging all color channels (e.g., for RGB images). Note however that the blending for display is done on the RGB display intensities of both the BlendingImage and the ImageToDisplay.
|
| mvbsDarker | 2 |
Blending only occurs if an ImageToDisplay pixel is darker than the coresponding BlendingImage pixel. The comparison is done on the luminance channel if there is one (e.g., for monochrome or HSI image types, or by averaging all color channels (e.g., for RGB images). Note however that the blending for display is done on the RGB display intensities of both the BlendingImage and the ImageToDisplay.
|
| mvbsMaskBySourceAoi | 4 |
If set, pixels are only blended if they are within the BlendingImage's AOI.
|
| mvbsMaskByDestAoi | 8 |
If set, pixels are only blended if they are within the ImageToDisplay's AOI.
|
| mvbsBlendUsesSourceLUT | 16 |
If set, the BlendingImage's LookupTable property is used to get the LUT for the RGB display values. Use this flag (or the default of no LUT) if the blend is being used to align images that will stay separate.
|
| mvbsBlendUsesDestLUT | 32 |
If set, whatever LUT is being applied to the ImageToDisplay when getting the RGB display values is also used for getting the BlendingImage's RGB display values. Use this flag, if the blend is being used to align a source image that will be combined with the destination ImageToDisplay (e.g., as in a preview of an Edit Paste operation).
|
Remarks
EditPasteAoi is a flexible and powerful tool for merging into the ImageToDisplay an image previously placed on the clipboard by EditCopy or EditCut. The method has arguments for options that reflect the settings saved by Application.CommandDialogs("Preferences").Pages("PasteOptions"). In fact the default behavior for the method is to use the options that were last set in the Preferences dialog (see Example 1).
The operation is relatively straightforward when the mcepaofPreviewThePaste OptionFlags is not set (i.e., when no user preview of the paste is called for, see Example 2). In this case, the clipboard image is just blended into the ImageToDisplay at the given alignment with the given BlendingOptionFlags (the actual blending operation is performed with the MOpLib's McGeometry.Blend method; a 100ImageToDisplay:IQL~McDisplay~ImageToDisplay AOI is optionally changed based on the mcEditPasteAoiOptionFlags:IQL~mcEditPasteAoiOptionFlagsmcepaofPreviewThePaste:IQL~mcEditPasteAoiOptionFlags~mcepaofPreviewThePasteImageToDisplay:IQL~McDisplay~ImageToDisplayOwningView:IQL~McDisplay~OwningView is made the working McView:IQL~McViewmcEditPasteAoiOptionFlags:IQL~mcEditPasteAoiOptionFlags mcepaofDoNotApplyThePaste:IQL~mcEditPasteAoiOptionFlags~mcepaofDoNotApplyThePaste% bit makes you responsible for monitoring the ToolDeselected event and doing the actual paste. Example 4 shows how this might be done.
Exceptions
An ImageToDisplay must be set before you can use this method. “No image on the clipboard” is returned if no image has been placed on the clipboard. Use IsActionAvailable with one of the mcwaMcImageAoiToPaste, mcwaMcImageDisplayAreaToPaste or mcwaMcImageToPaste as the mcWhatAction WhatAction argument to determine if a desired clipboard image format is available.
Notes
The pasted image data may have been previously placed there by a call to the EditCopy or EditCut methods, or it may be a new image created from a bitmap placed on the clipboard by some other application.
If multiple image clipboard formats are available, their precedence is mcwcftMcImageAoi, mcwcftMcImageDisplayArea, mcwcftCF_DIB, mcwcftCF_BITMAP, and then mcwcftCF_ENHMETAFILE.
|
EditPasteAoi Method
