Function Reference


_Excel_PictureAdd

Adds a picture on the specified workbook and worksheet

#include <Excel.au3>
_Excel_PictureAdd ( $oWorkbook, $vWorksheet, $sFile, $vRangeOrLeft [, $iTop = Default [, $iWidth = Default [, $iHeight = Default [, $bKeepRatio = True]]]] )

Parameters

$oWorkbook Excel workbook object
$vWorksheet Name, index or worksheet object to be written to. If set to keyword Default the active sheet will be used
$sFile Full path to picture file being added
$vRangeOrLeft Either an A1 range, a range object or an integer denoting the left position of the pictures upper left corner
$iTop [optional] If $vRangeOrLeft is an integer then $iTop is the top position of the pictures upper left corner.
$iWidth [optional] If specified, sets the width of the picture. If not specified, width will adjust automatically (default = Automatic)
$iHeight [optional] If specified, sets the height of the picture. If not specified, height will adjust automatically (default = Automatic)
$bKeepRatio [optional] Only used if $vRangeOrLeft is a multi-cell range (default = True)
    True will maintain image aspect ratio while staying within the bounds of $vRangeOrLeft.
    False will fill the $vRangeOrLeft regardless of original aspect ratio.

Return Value

Success: a Shape object that represents the new picture.
Failure: 0 and sets @error.
@error: 1 - $oWorkbook is not an object or not a workbook object
2 - $vWorksheet name or index are invalid or $vWorksheet is not a worksheet object. @extended is set to the COM error code
3 - $vRangeOrLeft is invalid. @extended is set to the COM error code
4 - Error occurred when adding picture. @extended is set to the COM error code
5 - $sFile does not exist

Remarks

If $vRangeOrLeft is a multi cell range $iWidth and $iHeight will be ignored (to specify width/height not based on range width/height, specify a single cell $vRangeOrLeft).

If only one of $iWidth and $iHeight is specified, the other (set to default) will be scaled to maintain the original aspect ratio of the picture.
If both $iWidth and $iHeight are specified, the picture will use the specified values regardless of original aspect ratio of the picture.
If neither $iWidth nor $iHeight are specified, the picture will be auto sized to the size of the original picture.

$bKeepRatio will be ignored unless a multi cell range is specified (see Parameters for details).

Example

#include <Excel.au3>
#include <MsgBoxConstants.au3>

; Create application object and open an example workbook
Local $oExcel = _Excel_Open()
If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example", "Error creating the Excel application object." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
; Create new Workbook
Local $oWorkbook = _Excel_BookNew($oExcel)
If @error Then
    MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example", "Error creating workbook." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
    _Excel_Close($oExcel)
    Exit
EndIf

; *****************************************************************************
; Insert and resize the picture into a range of cells. Aspect ratio retained
; *****************************************************************************
Local $sPicture = @ScriptDir & "\Extras\_Excel.jpg"
_Excel_PictureAdd($oWorkbook, Default, $sPicture, "B2:D8")
If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 1", "Error inserting picture." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 1", "Picture inserted/resized at 'B2:D8', aspect ratio retained.")

; *****************************************************************************
; Insert the picture without resizing.
; *****************************************************************************
_Excel_PictureAdd($oWorkbook, Default, $sPicture, "F8")
If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 2", "Error inserting picture." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 2", "Picture inserted at 'F8' without resizing.")

; *****************************************************************************
; Insert the picture with a defined size/height.
; *****************************************************************************
_Excel_PictureAdd($oWorkbook, Default, $sPicture, "A8", Default, 300, 250)
If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 3", "Error inserting picture." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 3", "Picture inserted at 'A8' with defined size/height, aspect ratio ignored")

; *****************************************************************************
; Insert the picture with a defined size/height.
; *****************************************************************************
_Excel_PictureAdd($oWorkbook, Default, $sPicture, 250, 300, 300, 250)
If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 4", "Error inserting picture." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 4", "Picture inserted at position 250/300' with defined size/height, aspect ratio ignored")

; *****************************************************************************
; Insert the picture with a defined size/height.
; *****************************************************************************
_Excel_PictureAdd($oWorkbook, Default, $sPicture, "F2:H9", Default, Default, Default, False)
If @error Then Exit MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 5", "Error inserting picture." & @CRLF & "@error = " & @error & ", @extended = " & @extended)
MsgBox($MB_SYSTEMMODAL, "Excel UDF: _Excel_PictureAdd Example 5", "Picture inserted/resized at 'F2:H9', aspect ratio ignored.")