Merge pull request '[forms][bu] Fix methods description' (#6) from release/v9.0.0 into master

Reviewed-on: https://git.onlyoffice.com/ONLYOFFICE/sdkjs-forms/pulls/5

apiBuilder.js

@@ -58,12 +58,12 @@
 	/**
 	 * Common form properties.
 	 * @typedef {Object} FormPrBase
-	 * @property {string} key - Form key.
-	 * @property {string} tip - Form tip text.
-	 * @property {string} tag - Form tag.
+	 * @property {string} key - The form key.
+	 * @property {string} tip - The form tip text.
+	 * @property {string} tag - The form tag.
 	 * @property {string} role - The role to fill out form.
 	 * @property {boolean} required - Specifies if the form is required or not.
-	 * @property {string} placeholder - Form placeholder text.
+	 * @property {string} placeholder - The form placeholder text.
 	 * @see office-js-api/Examples/Enumerations/FormPrBase.js
 	 */
 
@@ -185,19 +185,19 @@
 	 * Creates a text field with the specified text field properties.
 	 * @memberof Api
 	 * @typeofeditors ["CDE", "CFE"]
-	 * @param {TextFormPr} oFormPr - Text field properties.
+	 * @param {TextFormPr} formPr - Text field properties.
 	 * @returns {ApiTextForm}
 	 * @see office-js-api/Examples/Forms/Api/Methods/CreateTextForm.js
 	 */
-	Api.prototype.CreateTextForm = function(oFormPr)
+	Api.prototype.CreateTextForm = function(formPr)
 	{
 		return executeNoFormLockCheck(function()
 		{
-			if (!oFormPr)
-				oFormPr = {};
+			if (!formPr)
+				formPr = {};
 			
-			let form = CreateCommonForm(oFormPr);
-			ApplyTextFormPr(form, oFormPr);
+			let form = CreateCommonForm(formPr);
+			ApplyTextFormPr(form, formPr);
 			CheckForm(form);
 			return new AscBuilder.ApiTextForm(form);
 		}, this);
@@ -206,26 +206,26 @@
 	 * Creates a checkbox / radio button with the specified checkbox / radio button properties.
 	 * @memberof Api
 	 * @typeofeditors ["CDE", "CFE"]
-	 * @param {CheckBoxFormPr} oFormPr - Checkbox / radio button properties.
+	 * @param {CheckBoxFormPr} formPr - Checkbox / radio button properties.
 	 * @returns {ApiCheckBoxForm}
 	 * @see office-js-api/Examples/Forms/Api/Methods/CreateCheckBoxForm.js
 	 */
-	Api.prototype.CreateCheckBoxForm = function(oFormPr)
+	Api.prototype.CreateCheckBoxForm = function(formPr)
 	{
 		return executeNoFormLockCheck(function()
 		{
-			if (!oFormPr)
-				oFormPr = {};
+			if (!formPr)
+				formPr = {};
 			
-			oFormPr["placeholder"] = undefined;
+			formPr["placeholder"] = undefined;
 			
 			var oCC;
 			var oCheckboxPr = new AscCommon.CSdtCheckBoxPr();
-			if (GetBoolParameter(oFormPr["radio"], false))
+			if (GetBoolParameter(formPr["radio"], false))
 			{
 				oCheckboxPr.CheckedSymbol   = 0x25C9;
 				oCheckboxPr.UncheckedSymbol = 0x25CB;
-				oCheckboxPr.GroupKey        = GetStringParameter(oFormPr["key"], "Group1");
+				oCheckboxPr.GroupKey        = GetStringParameter(formPr["key"], "Group1");
 			}
 			else
 			{
@@ -256,7 +256,7 @@
 			
 			function private_PerformAddCheckBox()
 			{
-				oCC = CreateCommonForm(oFormPr);
+				oCC = CreateCommonForm(formPr);
 				oCC.ApplyCheckBoxPr(oCheckboxPr);
 			}
 			
@@ -281,25 +281,25 @@
 	 * Creates a combo box / dropdown list with the specified combo box / dropdown list properties.
 	 * @memberof Api
 	 * @typeofeditors ["CDE", "CFE"]
-	 * @param {ComboBoxFormPr} oFormPr - Combo box / dropdown list properties.
+	 * @param {ComboBoxFormPr} formPr - Combo box / dropdown list properties.
 	 * @returns {ApiComboBoxForm}
 	 * @see office-js-api/Examples/Forms/Api/Methods/CreateComboBoxForm.js
 	 */
-	Api.prototype.CreateComboBoxForm = function(oFormPr)
+	Api.prototype.CreateComboBoxForm = function(formPr)
 	{
 		return executeNoFormLockCheck(function()
 		{
-			if (!oFormPr)
-				oFormPr = {};
+			if (!formPr)
+				formPr = {};
 			
 			var oPr = new AscCommon.CSdtComboBoxPr();
 			oPr.AddItem(AscCommon.translateManager.getValue("Choose an item"), "");
 			
-			var oCC = CreateCommonForm(oFormPr);
+			var oCC = CreateCommonForm(formPr);
 			
-			let sPlaceholder = GetStringParameter(oFormPr["placeholder"], undefined);
+			let sPlaceholder = GetStringParameter(formPr["placeholder"], undefined);
 			
-			let arrList = GetArrayParameter(oFormPr["items"], []);
+			let arrList = GetArrayParameter(formPr["items"], []);
 			for (let nIndex = 0, nCount = arrList.length; nIndex < nCount; ++nIndex)
 			{
 				let oItem = arrList[nIndex];
@@ -316,9 +316,9 @@
 						oPr.AddItem(sDisplay, sValue);
 				}
 			}
-			oPr.SetAutoFit(GetBoolParameter(oFormPr["autoFit"], false));
+			oPr.SetAutoFit(GetBoolParameter(formPr["autoFit"], false));
 			
-			if (!GetBoolParameter(oFormPr["editable"], false))
+			if (!GetBoolParameter(formPr["editable"], false))
 			{
 				if (sPlaceholder)
 				{
@@ -351,27 +351,27 @@
 	 * Creates a picture form with the specified picture form properties.
 	 * @memberof Api
 	 * @typeofeditors ["CDE", "CFE"]
-	 * @param {PictureFormPr} oFormPr - Picture form properties.
+	 * @param {PictureFormPr} formPr - Picture form properties.
 	 * @returns {ApiPictureForm}
 	 * @see office-js-api/Examples/Forms/Api/Methods/CreatePictureForm.js
 	 */
-	Api.prototype.CreatePictureForm = function(oFormPr)
+	Api.prototype.CreatePictureForm = function(formPr)
 	{
 		return executeNoFormLockCheck(function()
 		{
-			if (!oFormPr)
-				oFormPr = {};
+			if (!formPr)
+				formPr = {};
 			
 			if (GetStringParameter("placeholder", null))
-				oFormPr["placeholder"] = AscCommon.translateManager.getValue("Click to load image");
+				formPr["placeholder"] = AscCommon.translateManager.getValue("Click to load image");
 			
-			var oCC = CreateCommonForm(oFormPr);
+			var oCC = CreateCommonForm(formPr);
 			oCC.ApplyPicturePr(true);
 			oCC.ConvertFormToFixed();
 			
 			let oPr = new AscCommon.CSdtPictureFormPr();
 			
-			let sScale = GetStringParameter(oFormPr["scaleFlag"], undefined);
+			let sScale = GetStringParameter(formPr["scaleFlag"], undefined);
 			switch (sScale)
 			{
 				case "always":
@@ -388,10 +388,10 @@
 					break;
 			}
 			
-			oPr.SetConstantProportions(GetBoolParameter(oFormPr["lockAspectRatio"], true));
-			oPr.SetRespectBorders(GetBoolParameter(oFormPr["respectBorders"], false));
-			oPr.SetShiftX(Math.max(0, Math.min(100, GetNumberParameter(oFormPr["shiftX"], 50))) / 100);
-			oPr.SetShiftY(Math.max(0, Math.min(100, GetNumberParameter(oFormPr["shiftY"], 50))) / 100);
+			oPr.SetConstantProportions(GetBoolParameter(formPr["lockAspectRatio"], true));
+			oPr.SetRespectBorders(GetBoolParameter(formPr["respectBorders"], false));
+			oPr.SetShiftX(Math.max(0, Math.min(100, GetNumberParameter(formPr["shiftX"], 50))) / 100);
+			oPr.SetShiftY(Math.max(0, Math.min(100, GetNumberParameter(formPr["shiftY"], 50))) / 100);
 			
 			oCC.SetPictureFormPr(oPr);
 			
@@ -403,53 +403,74 @@
 	 * Creates a date form with the specified date form properties.
 	 * @memberof Api
 	 * @typeofeditors ["CDE", "CFE"]
-	 * @param {DateFormPr} oFormPr - Date form properties.
+	 * @param {DateFormPr} formPr - Date form properties.
 	 * @returns {ApiDateForm}
 	 * @see office-js-api/Examples/Forms/Api/Methods/CreateDateForm.js
 	 */
-	Api.prototype.CreateDateForm = function(oFormPr)
+	Api.prototype.CreateDateForm = function(formPr)
 	{
 		return executeNoFormLockCheck(function()
 		{
-			if (!oFormPr)
-				oFormPr = {};
+			if (!formPr)
+				formPr = {};
 			
-			let form = CreateCommonForm(oFormPr);
-			ApplyDateFormPr(form, oFormPr);
+			let form = CreateCommonForm(formPr);
+			ApplyDateFormPr(form, formPr);
 			CheckForm(form);
 			return new AscBuilder.ApiDateForm(form);
 		}, this);
 	};
+	/**
+	 * Creates a complex form with the specified complex form properties.
+	 * @memberof Api
+	 * @typeofeditors ["CDE", "CFE"]
+	 * @param {FormPrBase} formPr - Complex form properties.
+	 * @returns {ApiComplexForm}
+	 * @see office-js-api/Examples/Forms/Api/Methods/CreateComplexForm.js
+	 */
+	Api.prototype.CreateComplexForm = function(formPr)
+	{
+		return executeNoFormLockCheck(function()
+		{
+			if (!formPr)
+				formPr = {};
+
+			let form = CreateCommonForm(formPr);
+			ApplyComplexFormPr(form);
+			CheckForm(form);
+			return new AscBuilder.ApiComplexForm(form);
+		}, this);
+	};
 	/**
 	 * Inserts a text box with the specified text box properties over the selected text.
 	 * @memberof ApiDocument
 	 * @typeofeditors ["CDE", "CFE"]
-	 * @param {TextFormInsertPr} oFormPr - Properties for inserting a text field.
+	 * @param {TextFormInsertPr} formPr - Properties for inserting a text field.
 	 * @returns {ApiTextForm}
 	 * @see office-js-api/Examples/Forms/ApiDocument/Methods/InsertTextForm.js
 	 */
-	ApiDocument.prototype.InsertTextForm = function(oFormPr)
+	ApiDocument.prototype.InsertTextForm = function(formPr)
 	{
 		return executeNoFormLockCheck(function()
 		{
-			if (!oFormPr)
-				oFormPr = {};
+			if (!formPr)
+				formPr = {};
 			
 			let logicDocument = this.Document;
-			let placeholder   = GetStringParameter(oFormPr["placeholder"], undefined);
-			if (GetBoolParameter(oFormPr["placeholderFromSelection"], false))
+			let placeholder   = GetStringParameter(formPr["placeholder"], undefined);
+			if (GetBoolParameter(formPr["placeholderFromSelection"], false))
 				placeholder = logicDocument.GetSelectedText();
 			
-			if (!GetBoolParameter(oFormPr["keepSelectedTextInForm"], true))
+			if (!GetBoolParameter(formPr["keepSelectedTextInForm"], true))
 				logicDocument.RemoveBeforePaste();
 			
 			let contentControl = logicDocument.AddContentControl(c_oAscSdtLevelType.Inline);
 			if (!contentControl)
 				return null;
 			
-			ApplyCommonFormPr(contentControl, oFormPr);
+			ApplyCommonFormPr(contentControl, formPr);
 			SetFormPlaceholder(contentControl, placeholder);
-			ApplyTextFormPr(contentControl, oFormPr, true);
+			ApplyTextFormPr(contentControl, formPr, true);
 			CheckForm(contentControl);
 			return new AscBuilder.ApiTextForm(contentControl);
 		}, this);
@@ -459,7 +480,7 @@
 	 * Class representing a collection of form roles.
 	 * @constructor
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
+	 * @typeofeditors ["CDE", "CFE"]
 	 */
 	function ApiFormRoles(oform)
 	{
@@ -467,23 +488,22 @@
 	}
 	
 	/**
-	 * Role properties.
+	 * The date form properties.
 	 * @typedef {FormPrBase | DateFormPrBase} DateFormPr
 	 * @see office-js-api/Examples/Enumerations/DateFormPr.js
 	 */
 	
 	/**
-	 * Role properties.
+	 * The role properties.
 	 * @typedef {Object} RoleProperties
-	 * @property {string} color
-	 * @see office-js-api/Examples/Enumerations/RolePr.js
+	 * @property {string} color - The role color.
+	 * @see office-js-api/Examples/Enumerations/RoleProperties.js
 	 */
 	
 	/**
-	 * Get the collection of form roles.
-	 *
+	 * Returns a collection of form roles.
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
+	 * @typeofeditors ["CDE", "CFE"]
 	 * @returns {ApiFormRoles}
 	 * @see office-js-api/Examples/Forms/ApiDocument/Methods/GetFormRoles.js
 	 */
@@ -493,12 +513,12 @@
 	};
 	
 	/**
-	 * Add new role.
+	 * Adds a new form role.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
+	 * @typeofeditors ["CDE", "CFE"]
 	 * @param {string} name - The name of role being added.
-	 * @param {RoleProperties} props - Properties for the new role.
+	 * @param {RoleProperties} props - The role properties.
 	 * @returns {boolean}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/Add.js
 	 */
@@ -516,12 +536,12 @@
 		return true;
 	};
 	/**
-	 * Remove role.
+	 * Removes a role with the specified name.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
+	 * @typeofeditors ["CDE", "CFE"]
 	 * @param {string} name - The name of role to be removed.
-	 * @param {string} [delegateRole] - The name of the role to which all forms binded to this role will be delegated.
+	 * @param {string} [delegateRole] - The name of the role to which all forms bound to this role will be delegated.
 	 * @returns {boolean}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/Remove.js
 	 */
@@ -533,10 +553,10 @@
 		return this.oform.removeRole(name, delegateRole);
 	};
 	/**
-	 * Get the number of roles.
+	 * Returns a number of form roles.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
+	 * @typeofeditors ["CDE", "CFE"]
 	 * @returns {number}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/GetCount.js
 	 */
@@ -548,10 +568,10 @@
 		return this.oform.getAllRoles().length;
 	};
 	/**
-	 * List all roles.
+	 * Lists all available roles.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
+	 * @typeofeditors ["CDE", "CFE"]
 	 * @returns {string[]}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/GetAllRoles.js
 	 */
@@ -569,11 +589,11 @@
 		return result;
 	};
 	/**
-	 * Check if a role with the specified name exists.
+	 * Checks if a role with the specified name exists.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
-	 * @param {string} name - The name of role.
+	 * @typeofeditors ["CDE", "CFE"]
+	 * @param {string} name - The role name.
 	 * @returns {boolean}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/HaveRole.js
 	 */
@@ -582,11 +602,11 @@
 		return this.oform && this.oform.haveRole(name);
 	};
 	/**
-	 * Get the color of the specified role
+	 * Returns the RGB color of the specified role.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
-	 * @param {string} name - The name of role.
+	 * @typeofeditors ["CDE", "CFE"]
+	 * @param {string} name - The role name.
 	 * @returns {null | {r:byte, g:byte, b:byte}}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/GetRoleColor.js
 	 */
@@ -606,12 +626,12 @@
 		};
 	};
 	/**
-	 * Set the color of the specified role
+	 * Sets the color for the specified role.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
-	 * @param {string} name - The name of role.
-	 * @param {string} color - The specified color.
+	 * @typeofeditors ["CDE", "CFE"]
+	 * @param {string} name - The role name.
+	 * @param {string} color - The role color.
 	 * @returns {boolean}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/SetRoleColor.js
 	 */
@@ -629,11 +649,11 @@
 		return true;
 	};
 	/**
-	 * Move role up in filling order.
+	 * Moves a role up in filling order.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
-	 * @param {string} name - The name of role.
+	 * @typeofeditors ["CDE", "CFE"]
+	 * @param {string} name - The role name.
 	 * @returns {boolean}
 	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/MoveUp.js
 	 */
@@ -645,13 +665,13 @@
 		return this.oform.moveUpRole(name);
 	};
 	/**
-	 * Move role down in filling order.
+	 * Moves a role down in filling order.
 	 * @memberof ApiFormRoles
 	 * @since 9.0.0
-	 * @typeofeditors ["CFE"]
-	 * @param {string} name - The name of role.
+	 * @typeofeditors ["CDE", "CFE"]
+	 * @param {string} name - The role name.
 	 * @returns {boolean}
-	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/MoveUp.js
+	 * @see office-js-api/Examples/Forms/ApiFormRoles/Methods/MoveDown.js
 	 */
 	ApiFormRoles.prototype.MoveDown = function(name)
 	{
@@ -663,16 +683,16 @@
 	////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 	// Private area
 	////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
-	function CreateCommonForm(oFormPr)
+	function CreateCommonForm(formPr)
 	{
 		let contentControl = new AscCommonWord.CInlineLevelSdt();
 		
-		ApplyCommonFormPr(contentControl, oFormPr);
+		ApplyCommonFormPr(contentControl, formPr);
 		
-		let placeholder = oFormPr ? GetStringParameter(oFormPr["placeholder"], undefined) : undefined;
+		let placeholder = formPr ? GetStringParameter(formPr["placeholder"], undefined) : undefined;
 		SetFormPlaceholder(contentControl, placeholder);
 		
-		let tag = oFormPr ? GetStringParameter(oFormPr["tag"], undefined) : undefined;
+		let tag = formPr ? GetStringParameter(formPr["tag"], undefined) : undefined;
 		if (tag)
 			contentControl.SetTag(tag);
 		
@@ -722,6 +742,11 @@
 
 		form.ApplyDatePickerPr(datePickerPr);
 	}
+	function ApplyComplexFormPr(form)
+	{
+		let complexFormPr = new AscWord.CSdtComplexFormPr();
+		form.SetComplexFormPr(complexFormPr);
+	}
 	function CheckForm(form)
 	{
 		CheckFormKey(form);
@@ -778,8 +803,9 @@
 	Api.prototype["CreateTextForm"]     = Api.prototype.CreateTextForm;
 	Api.prototype["CreatePictureForm"]  = Api.prototype.CreatePictureForm;
 	Api.prototype["CreateDateForm"]		= Api.prototype.CreateDateForm;
-	Api.prototype["CreateCheckBoxForm"] = Api.prototype.CreateCheckBoxForm;	
+	Api.prototype["CreateCheckBoxForm"] = Api.prototype.CreateCheckBoxForm;
 	Api.prototype["CreateComboBoxForm"] = Api.prototype.CreateComboBoxForm;
+	Api.prototype["CreateComplexForm"]	= Api.prototype.CreateComplexForm;
 	
 	ApiDocument.prototype["InsertTextForm"] = ApiDocument.prototype.InsertTextForm;
 	ApiDocument.prototype["GetFormRoles"]   = ApiDocument.prototype.GetFormRoles;