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]]]] )
| $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. |
| 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 |
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).
#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.")