A form is an aggregate of named typed fields. More...

#include <VFS_form.h>

Public Member Functions
	VFS_form (QString base="")

virtual	~VFS_form ()

void	addBreak (int index=-1)
	Add a break field to a form. More...

void	append (QString name, VFS_form_field field, int index=-1)
	Append a field to the form. More...

void	applyDiff (QJsonObject diff, bool useAttributes=false)
	Apply a diff to this form. More...

bool	contains (QString field)
	Check if a field is part of a form. More...

QJsonValue	getOption (QString var, QString option)
	Fetch an option value from a form field if it exists. More...

QJsonValue	getValue (QString var)
	Fetch the value of a form field. More...

void	remove (QString name)
	Remove a field from the form. More...

void	removeIndexRange (int s, int e)
	Remove fields whose index is within a range. More...

void	replace (QString name, VFS_form_field field)
	Replace or append a field to the form. More...

void	setBase (QString baseForm)
	Set the 'class' that this form inherits from. More...

void	setHelp (QString helpText)
	Set the helptext for this form. More...

bool	setOption (QString var, QString option, QJsonValue o)
	Set an option on a form field if it exists. More...

bool	setValue (QString var, QJsonValue val)
	Set the value of a form field if it exists. More...

QJsonDocument	toJsonDocument (bool useAttributes=false)
	Return a form document as a QJsonDocument. More...

QJsonDocument	toSubclassDocument ()
	Return the form as a QJsonDocument, and include reference to its base. More...

Private Member Functions
QJsonValue	cleanValue (QJsonValue o, bool isValue=false)
	Normalize a form value recursively. More...

Private Attributes
QString	_baseForm
	The base json 'class' that this form will augment. Leave blank for no base. More...

int	_breakCount
	The break count, because all fields must have unique names, and addBreak will use this. More...

QJsonObject	_form
	The form itself, which is just a json object. More...

QString	_helpText
	The help text that will appear in a menu or modal for this form. More...

int	_index
	The index count used for autoindexing. More...

Detailed Description

A form is an aggregate of named typed fields.

Parameters

baseForm The base json 'class' that this will derive from.

A form can optionally build upon another form, in a kind of inheritance scheme.

Fields will be sorted by index when rendered, and can be autoindexed when added.

Forms can also be used by VFS_node instances to represent a model of data, which can be rendered using a form in a javascript client, for instance.

See also: Diffs; form

Definition at line 9 of file VFS_form.h.

Constructor & Destructor Documentation

◆ VFS_form()

VFS_form::VFS_form ( QString baseForm = "" )

explicit

Parameters

baseForm

Definition at line 33 of file VFS_form.cpp.

◆ ~VFS_form()

VFS_form::~VFS_form ( )

virtual

Definition at line 41 of file VFS_form.cpp.

Member Function Documentation

◆ addBreak()

void VFS_form::addBreak ( int index = -1 )

Add a break field to a form.

Parameters

index The index if provided, otherwise autoindex.

Definition at line 426 of file VFS_form.cpp.

◆ append()

void VFS_form::append	(	QString	name,
		VFS_form_field	field,
		int	index = `-1`
	)

Append a field to the form.

Parameters

name	The field name
field	The field itself
index	The index, or none if autoindexing is desired.

Definition at line 222 of file VFS_form.cpp.

◆ applyDiff()

void VFS_form::applyDiff	(	QJsonObject	diff,
		bool	useAttributes = `false`
	)

Apply a diff to this form.

Parameters

diff	The diff to apply
useAttributes	Whether or not to assume the diff data is in the "attributes" field of the diff object.

Todo:: This needs more debugging. Depending on input, the form can be munged into a bad state.

Definition at line 448 of file VFS_form.cpp.

◆ cleanValue()

QJsonValue VFS_form::cleanValue	(	QJsonValue	v,
		bool	isValue = `false`
	)

private

Normalize a form value recursively.

Parameters

v	A json value
isValue	whether the field being cleaned is "value".

Returns: The normalized value

Warning: This function needs to be bullet-proofed and production tested; it reveals some ambuguity in how forms are represented.; This may be moved into a master diff engine library in the future

Definition at line 78 of file VFS_form.cpp.

◆ contains()

bool VFS_form::contains ( QString field )

Check if a field is part of a form.

Parameters

field The field to check

Returns: boolean value

Definition at line 299 of file VFS_form.cpp.

◆ getOption()

QJsonValue VFS_form::getOption	(	QString	var,
		QString	option
	)

Fetch an option value from a form field if it exists.

Parameters

var	The field name
option	The option name

Returns: The option value or Null if the variable or option does not exist

Definition at line 408 of file VFS_form.cpp.

◆ getValue()

QJsonValue VFS_form::getValue ( QString var )

Fetch the value of a form field.

Parameters

var	The field name

Returns: The field value, or QJsonValue::Null if the field was not found.

Definition at line 361 of file VFS_form.cpp.

◆ remove()

void VFS_form::remove ( QString name )

Remove a field from the form.

Parameters

name	The field name

If the field is not found, the function will silently continue

Definition at line 244 of file VFS_form.cpp.

◆ removeIndexRange()

void VFS_form::removeIndexRange	(	int	s,
		int	e
	)

Remove fields whose index is within a range.

Parameters

s	The start index
e	The end index

This will remove fields where s <= index <= e

Definition at line 281 of file VFS_form.cpp.

◆ replace()

void VFS_form::replace	(	QString	name,
		VFS_form_field	field
	)

Replace or append a field to the form.

Parameters

name	The field name
field	The field itself

If the field exists, it will be replaced. The new field will take the index from the old field.

If the field doesn't exist, it will be added and autoindexed.

Definition at line 260 of file VFS_form.cpp.

◆ setBase()

void VFS_form::setBase ( QString baseForm )

Set the 'class' that this form inherits from.

Parameters

baseForm The base form

Definition at line 51 of file VFS_form.cpp.

◆ setHelp()

void VFS_form::setHelp ( QString helpText )

Set the helptext for this form.

Parameters

helpText The help text

Definition at line 61 of file VFS_form.cpp.

◆ setOption()

bool VFS_form::setOption	(	QString	var,
		QString	option,
		QJsonValue	o
	)

Set an option on a form field if it exists.

Parameters

var	The field name
option	The option name
o	The option value

Returns: Success or failure of setting the option. This will only fail if the variable does not exist.

Definition at line 385 of file VFS_form.cpp.

◆ setValue()

bool VFS_form::setValue	(	QString	var,
		QJsonValue	val
	)

Set the value of a form field if it exists.

Parameters

var	The field name
val	The field value

Returns: Success or failure of setting the value

Todo:: This needs more debugging. Depending on input, the form can be munged into a bad state.

Definition at line 313 of file VFS_form.cpp.

◆ toJsonDocument()

QJsonDocument VFS_form::toJsonDocument ( bool useAttributes = false )

Return a form document as a QJsonDocument.

Parameters

useAttributes Offset the values using an "attributes" field

Returns: The form as a QJsonDocument

Forms are ostensibly name:value pairs, but depending on the receiving side, an attributes offset may be needed.

{
   "a":245,
   "b":"something"
}

may become

{
   "attributes":   {
                       "a":245,
                       "b":"something"
                   },
   "help": "some help text about this form"
   "metadata": {}
}

depending on the receiving interpreter.

Note: Ideally this will become normalized in the future, and the useAttributes flag will go away.

Definition at line 147 of file VFS_form.cpp.

◆ toSubclassDocument()

QJsonDocument VFS_form::toSubclassDocument ( )

Return the form as a QJsonDocument, and include reference to its base.

Returns: The document as a QJsonDocument, with reference to its base 'class' document.

The result will always use the "attributes" form, and will contain a reference to the 'class' that this form builds on.

This is used, for instance, when you have a node that needs settings applied. The document itself will only contain the values of the settings, but the base 'class' will contain all of the widget parameters and cosmetic stuff. The client is responsible for pulling the base 'class' and doing the merge/diff.

See also: Diffs

Definition at line 178 of file VFS_form.cpp.

Member Data Documentation

◆ _baseForm

QString VFS_form::_baseForm

private

The base json 'class' that this form will augment. Leave blank for no base.

Definition at line 44 of file VFS_form.h.

◆ _breakCount

int VFS_form::_breakCount

private

The break count, because all fields must have unique names, and addBreak will use this.

Definition at line 42 of file VFS_form.h.

◆ _form

QJsonObject VFS_form::_form

private

The form itself, which is just a json object.

Definition at line 46 of file VFS_form.h.

◆ _helpText

QString VFS_form::_helpText

private

The help text that will appear in a menu or modal for this form.

Definition at line 45 of file VFS_form.h.

◆ _index

int VFS_form::_index

private

The index count used for autoindexing.

Definition at line 41 of file VFS_form.h.

The documentation for this class was generated from the following files:

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VFS_form()

◆ ~VFS_form()

Member Function Documentation

◆ addBreak()

◆ append()

◆ applyDiff()

◆ cleanValue()

◆ contains()

◆ getOption()

◆ getValue()

◆ remove()

◆ removeIndexRange()

◆ replace()

◆ setBase()

◆ setHelp()

◆ setOption()

◆ setValue()

◆ toJsonDocument()

◆ toSubclassDocument()

Member Data Documentation

◆ _baseForm

◆ _breakCount

◆ _form

◆ _helpText

◆ _index