Skip to content

Commit

Permalink
Update SurveyModel API descriptions (#6924)
Browse files Browse the repository at this point in the history 
* Update `SurveyModel` API descriptions

* Final reviews

* Apply suggestions from code review

Co-authored-by: annnke <anna.bakulina@devexpress.com>

---------

Co-authored-by: annnke <anna.bakulina@devexpress.com>
  • Loading branch information
@RomanTsukanov @annnke
RomanTsukanov and annnke committed Sep 12, 2023
1 parent 3d1d912 commit 6b339bc
Show file tree
Hide file tree
Showing 3 changed files with 202 additions and 213 deletions.
2 changes: 1 addition & 1 deletion src/question_textbase.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ export class QuestionTextBase extends Question {
return super.isEmpty() || this.value === "";
}
/**
* Gets or sets a value that specifies when to update the question value.
* Specifies when to update the question value.
*
* Possible values:
*
Expand Down
120 changes: 59 additions & 61 deletions src/survey-events-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ export interface CompletingEvent extends CompleteBaseEvent {
*/
allow: boolean;
/**
* Obsolete. Use `allow` instead.
* Obsolete. Use `options.allow` instead.
*/
allowComplete: boolean;
}
Expand All @@ -133,19 +133,19 @@ export interface CompleteEvent extends CompleteBaseEvent {
*/
showSaveInProgress: (text?: string) => void;
/**
* Obsolete. Use `showSaveInProgress` instead.
* Obsolete. Use `options.showSaveInProgress` instead.
*/
showDataSaving: (text?: string) => void;
/**
* Obsolete. Use `showSaveError` instead.
* Obsolete. Use `options.showSaveError` instead.
*/
showDataSavingError: (text?: string) => void;
/**
* Obsolete. Use `showSaveSuccess` instead.
* Obsolete. Use `options.showSaveSuccess` instead.
*/
showDataSavingSuccess: (text?: string) => void;
/**
* Obsolete. Use `clearSaveMessages` instead.
* Obsolete. Use `options.clearSaveMessages` instead.
*/
showDataSavingClear: (text?: string) => void;
}
Expand All @@ -155,7 +155,7 @@ export interface ShowingPreviewEvent {
*/
allow: boolean;
/**
* Obsolete. Use `allow` instead.
* Obsolete. Use `options.allow` instead.
*/
allowShowPreview: boolean;
}
Expand Down Expand Up @@ -205,7 +205,7 @@ export interface CurrentPageChangingEvent extends CurrentPageChangedEvent {
*/
allow: boolean;
/**
* Obsolete. Use `allow` instead.
* Obsolete. Use `options.allow` instead.
*/
allowChanging: boolean;
}
Expand Down Expand Up @@ -262,11 +262,11 @@ export interface ElementAddedEvent {
*/
parent: PanelModelBase;
/**
* Obsolete. Use `page` instead.
* Obsolete. Use `options.page` instead.
*/
rootPanel: any;
/**
* Obsolete. Use `parent` instead.
* Obsolete. Use `options.parent` instead.
*/
parentPanel: any;
/**
Expand Down Expand Up @@ -335,31 +335,29 @@ export interface ValidatePanelEvent extends PanelEventMixin {
}
export interface ErrorCustomTextEvent {
/**
* the error name. The following error names are available:
* required, requireoneanswer, requirenumeric, exceedsize, webrequest, webrequestempty, otherempty,
* uploadingfile, requiredinallrowserror, minrowcounterror, keyduplicationerror, custom
* A validation error type: `"required"`, `"requireoneanswer"`, `"requirenumeric"`, `"exceedsize"`, `"webrequest"`, `"webrequestempty"`, `"otherempty"`, `"uploadingfile"`, `"requiredinallrowserror"`, `"minrowcounterror"`, `"keyduplicationerror"`, or `"custom"`
*/
name: string;
/**
* an instance of Question, Panel or Survey object to where error is located
* A survey element to which the validation error belongs.
*/
obj: Question | PanelModel | SurveyModel;
/**
* an instance of the `SurveyError` object
* A validation error.
*/
error: SurveyError;
/**
* an error text
* An error message. You can assign a custom message to this parameter.
*/
text: string;
}
export interface ValidatedErrorsOnCurrentPageEvent extends PageEventMixin {
/**
* the list of questions that have errors
* An array of questions with validation errors.
*/
questions: Array<Question>;
/**
* the list of errors
* An array of validation errors.
*/
errors: Array<SurveyError>;
}
Expand Down Expand Up @@ -420,23 +418,23 @@ export interface ProgressTextEvent {

export interface TextProcessingEvent {
/**
* a property name is going to be rendered
* The name of the property that contains the text to process.
*/
name: string;
/**
* SurveyJS element (a question, panel, page, or survey) where the string is going to be rendered
* A survey element (question, panel, page, or survey) in which the text will be rendered.
*/
element: Question | PanelModel | PageModel | SurveyModel;
}
export interface TextMarkdownEvent extends TextProcessingEvent {
/**
* an HTML content. It is `null` by default. Use this property to specify the HTML content rendered instead of `options.text`
* A string with Markdown content. Convert this content to HTML and assign the result to the `options.html` parameter.
*/
html?: string;
text: string;
/**
* a text that is going to be rendered
* A property to which you should assign HTML content.
*/
text: string;
html?: string;
}
export interface TextRenderAsEvent extends TextProcessingEvent {
/**
Expand Down Expand Up @@ -535,28 +533,25 @@ export interface ClearFilesEvent extends LoadFilesEvent {
}
export interface LoadChoicesFromServerEvent extends QuestionEventMixin {
/**
* a result that comes from the server as it is
* A query result as it came from the server.
*/
serverResult: any;
/**
* the loaded choices. You can change the loaded choices to before they are assigned to question
* An array of loaded choices. You can modify this array.
*/
choices: Array<ItemValue>;
}
export interface ProcessTextValueEvent {
/**
* the value of the processing text
* The name of the value being processed (the text in curly brackets).
*/
value: any;
name: string;
/**
* a boolean value. Set it to `true` if you want to use the value and set it to `false` if you don't
* The value being processed. You can change this parameter's value.
*/
value: any;
isExists: boolean;
canProcess: boolean;
/**
* the name of the processing value, for example, "state" in our example
*/
name: string;
returnDisplayValue: boolean;
}
export interface UpdateQuestionCssClassesEvent extends QuestionEventMixin, UpdateElementCssClassesEventMixin { }
Expand Down Expand Up @@ -588,13 +583,13 @@ export interface FocusInQuestionEvent extends QuestionEventMixin {
export interface FocusInPanelEvent extends PanelEventMixin { }
export interface ShowingChoiceItemEvent extends QuestionEventMixin {
/**
* A Boolean value that specifies item visibility. Set it to `false` to hide the item.
* A choice item.
*/
visible: boolean;
item: ItemValue;
/**
* The choice item as specified in the [choices](https://surveyjs.io/Documentation/Library?id=QuestionSelectBase#choices) array.
* A Boolean value that specifies item visibility. Set it to `false` to hide the item.
*/
item: ItemValue;
visible: boolean;
}
export interface ChoicesLazyLoadEvent extends QuestionEventMixin {
/**
Expand Down Expand Up @@ -636,7 +631,7 @@ export interface MatrixBeforeRowAddedEvent extends MatrixDynamicQuestionEventMix
*/
allow: boolean;
/**
* Obsolete. Use `allow` instead.
* Obsolete. Use `options.allow` instead.
*/
canAddRow: boolean;
}
Expand Down Expand Up @@ -830,62 +825,65 @@ export interface DynamicPanelGetTabTitleEvent extends PanelDynamicQuestionEventM
}
export interface IsAnswerCorrectEvent extends QuestionEventMixin {
/**
* you may change the default number of correct or incorrect answers in the question, for example for matrix, where each row is a quiz question
* The number of correct answers in a matrix where each row is considered as one quiz question.
*/
correctAnswers: number;
/**
* The number of incorrect answers in a matrix where each row is considered as one quiz question.
*/
incorrectAnswers: number;
/**
* returns `true`, if an answer is correct, or `false`, if the answer is not correct. Use questions' `value` and `correctAnswer` properties to return the correct value
* A Boolean property that specifies whether the answer is correct (`true`) or incorrect (`false`). Use the `options.question.value` and `options.question.correctAnswer` properties to check the answer.
*/
result: boolean;
}
export interface DragDropAllowEvent {
/**
* an element after the target element is dragging. It can be `null` if parent container (page or panel) is empty or dragging element to the first position within the parent container
* A survey element being dragged.
*/
insertAfter: IElement;
target: IElement;
/**
* an element before the target element is dragging. It can be `null` if parent container (page or panel) is empty or dragging an element after the last element in a container
* A survey element from which `target` is being dragged. This parameter is `null` if `target` is being dragged from the [Toolbox](https://surveyjs.io/survey-creator/documentation/toolbox).
*/
insertBefore: IElement;
source: IElement;
/**
* a page or panel where target element is dragging
* A survey element before which the target element will be placed. This parameter is `null` if the parent container (page or panel) has no elements or if the target element will be placed below all other elements within the container.
*/
parent: ISurveyElement;
insertBefore: IElement;
/**
* a source element. It can be `null`, if it is a new element, dragging from toolbox
* A survey element after which `target` will be placed. This parameter is `null` if the parent container (page or panel) has no elements or if `target` will be placed above all other elements within the container.
*/
source: IElement;
insertAfter: IElement;
/**
* a target element that is dragged
* A parent container (page or panel) within which `target` will be placed.
*/
target: IElement;
parent: ISurveyElement;
/**
* set it to `false` to disable dragging
* A Boolean property that you can set to `false` if you want to cancel the drag and drop operation.
*/
allow: boolean;
}
export interface ScrollingElementToTopEvent {
/**
* an element that is going to be scrolled on top
* A survey element that will be scrolled to the top.
*/
element: ISurveyElement;
/**
* a question that is going to be scrolled on top. It can be null if options.page is not null
* A unique element ID within the DOM.
*/
question?: Question;
elementId: string;
/**
* a page that is going to be scrolled on top. It can be null if options.question is not null
* A Boolean property that you can set to `true` if you want to cancel the scroll operation.
*/
page?: PageModel;
cancel: boolean;
/**
* set this property to true to cancel the default scrolling
* Obsolete. Use `options.element` instead.
*/
cancel: boolean;
question?: Question;
/**
* the unique element DOM Id
* Obsolete. Use `options.element` instead.
*/
elementId: string;
page?: PageModel;
}
export interface GetQuestionTitleActionsEvent extends QuestionEventMixin, GetTitleActionsEventMixin { }
export interface GetPanelTitleActionsEvent extends PanelEventMixin, GetTitleActionsEventMixin { }
Expand All @@ -904,7 +902,7 @@ export interface GetMatrixRowActionsEvent extends QuestionEventMixin, GetActions
}
export interface ElementContentVisibilityChangedEvent {
/**
* Specifies which survey element content was collapsed or expanded
* A survey element that was expanded or collapsed.
*/
element: ISurveyElement;
}
Expand All @@ -916,7 +914,7 @@ export interface GetQuestionDisplayValueEvent extends QuestionEventMixin {
}
export interface GetExpressionDisplayValueEvent extends GetQuestionDisplayValueEvent {
/**
* The question value
* An expression value.
*/
value: any;
}
Expand Down

0 comments on commit 6b339bc

Please sign in to comment.