ApiPictureForm

new ApiPictureForm()

Class representing a document picture form.

Properties

Name Type Description
scaleFlag ScaleFlag

The condition to scale an image in the picture form: "always", "never", "tooBig" or "tooSmall".

lockAspectRatio boolean

Specifies if the aspect ratio of the picture form is locked or not.

respectBorders boolean

Specifies if the form border width is respected or not when scaling the image.

shiftX percentage

Horizontal picture position inside the picture form measured in percent:

  • 0 - the picture is placed on the left;
  • 50 - the picture is placed in the center;
  • 100 - the picture is placed on the right.
shiftY percentage

Vertical picture position inside the picture form measured in percent:

  • 0 - the picture is placed on top;
  • 50 - the picture is placed in the center;
  • 100 - the picture is placed on the bottom.

Methods

Name Description
Clear

Clears the current form.

Copy

Copies the current form (copies with the shape if it exists).

GetClassType

Returns a type of the ApiFormBase class.

GetFormKey

Returns the current form key.

GetFormType

Returns a type of the current form.

GetImage

Returns an image in the base64 format from the current picture form.

GetPicturePosition

Returns the picture position inside the current form.

GetScaleFlag

Returns the current scaling condition of the picture form.

GetText

Returns the text from the current form. This method is used only for text and combo box forms.

GetTextPr

Returns the text properties from the current form. This method is used only for text and combo box forms.

GetTipText

Returns the tip text of the current form.

GetWrapperShape

Returns a shape in which the form is placed to control the position and size of the fixed size form frame. The null value will be returned for the inline forms.

IsFixed

Checks if the current form is fixed size.

IsLockAspectRatio

Checks if the aspect ratio of the current picture form is locked or not.

IsRequired

Checks if the current form is required.

IsRespectBorders

Checks if the form border width is respected or not.

SetBackgroundColor

Sets the background color to the current form.

SetBorderColor

Sets the border color to the current form.

SetFormKey

Sets a key to the current form.

SetImage

Sets an image to the current picture form.

SetLockAspectRatio

Locks the aspect ratio of the current picture form.

SetPicturePosition

Sets the picture position inside the current form:

  • 0 - the picture is placed on the left/top;
  • 50 - the picture is placed in the center;
  • 100 - the picture is placed on the right/bottom.
SetPlaceholderText

Sets the placeholder text to the current form. Can't be set to checkbox or radio button.

SetRequired

Specifies if the current form should be required.

SetRespectBorders

Respects the form border width when scaling the image.

SetScaleFlag

Sets the scaling condition to the current picture form.

SetTextPr

Sets the text properties to the current form. This method is used only for text and combo box forms.

SetTipText

Sets the tip text to the current form.

ToFixed

Converts the current form to a fixed size form.

ToInline

Converts the current form to an inline form. Picture form can't be converted to an inline form, it's always a fixed size object.

Example

Copy code
builder.CreateFile("docx");
var oDocument = Api.GetDocument();
var oPictureForm = Api.CreatePictureForm({"key": "Personal information", "tip": "Upload your photo", "required": true, "placeholder": "Photo"});
var oParagraph = oDocument.GetElement(0);
oParagraph.AddElement(oPictureForm);
oPictureForm.SetImage("https://api.onlyoffice.com/content/img/docbuilder/examples/user-profile.png");
oPictureForm.SetLockAspectRatio(true);
oPictureForm.SetScaleFlag("tooBig");
oPictureForm.SetPicturePosition(70, 70);
oPictureForm.SetRespectBorders(true);
var sScaleFlag = oPictureForm.GetScaleFlag();
var aPosition = oPictureForm.GetPicturePosition();
var bLock = oPictureForm.IsLockAspectRatio();
var bRespectBorders = oPictureForm.IsRespectBorders();
oParagraph = Api.CreateParagraph();
oParagraph.AddText("Picture scale flag: " + sScaleFlag);
oParagraph.AddLineBreak();
oParagraph.AddText("The aspect ratio of the first picture form in this document is locked: " + bLock);
oParagraph.AddLineBreak();
oParagraph.AddText("The borders of the first picture form in this document are respected when scaling the image: " + bRespectBorders);
oDocument.Push(oParagraph);
oParagraph = Api.CreateParagraph();
oParagraph.AddText("Picture position: ");
oParagraph.AddLineBreak();
for (let i = 0; i < aPosition.length; i++ ){
    var nShift = aPosition[i];
    oParagraph.AddText("" + nShift);
    oParagraph.AddLineBreak();
}
oDocument.Push(oParagraph);
builder.SaveFile("docx", "ApiPictureForm.docx");
builder.CloseFile();

Resulting document