# 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 "Extras\HelpFileInternals.au3"

    #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 = _Extras_PathFull("_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.")