Module org.autogui

Package org.autogui.base.mapping

Class GuiReprValue

java.lang.Object

org.autogui.base.mapping.GuiReprValue

All Implemented Interfaces:

GuiRepresentation

Direct Known Subclasses:

GuiReprCollectionElement, GuiReprCollectionTable, GuiReprEmbeddedComponent, GuiReprObjectPane, GuiReprPropertyPane, GuiReprValueBooleanCheckBox, GuiReprValueDocumentEditor, GuiReprValueEnumComboBox, GuiReprValueFilePathField, GuiReprValueImagePane, GuiReprValueLabel, GuiReprValueNumberSpinner, GuiReprValueStringField

public class GuiReprValue
extends Object
implements GuiRepresentation

a value component associated with GuiTypeValue. matching Class with the subclass implementing matchValueType(Class).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GuiReprValue.NamedValue	pair object for a value and a String name, can be converted to a JSON object member.
static class	GuiReprValue.ObjectSpecifier	an auxiliary information for specifying a property value.
static class	GuiReprValue.ObjectSpecifierIndex	the indexed specifier for specifying an element in a list
static class	GuiReprValue.ObjectSpecifierNothing	special specifier, can be obtained by NONE

Nested classes/interfaces inherited from interface org.autogui.base.mapping.GuiRepresentation

GuiRepresentation.GuiReprNone

Field Summary

Fields

Modifier and Type	Field	Description
static GuiReprValue.ObjectSpecifierNothing	NONE	special specifier for non-indexed property values without caching.
static GuiReprValue.ObjectSpecifierNothing	NONE_WITH_CACHE

Constructor Summary

Constructors

Constructor	Description
GuiReprValue()

Method Summary

Modifier and Type	Method	Description
void	addHistoryValue(GuiMappingContext context, Object value)
static <T> T	castOrMake(Class<T> cls, Object o, Supplier<T> v)	cast o if o is a non-null and specified type cls, otherwise call v.
boolean	checkAndUpdateSource(GuiMappingContext context)	the class supposes that the parent is a GuiReprPropertyPane: [propName: [objectPane]].
static void	convertLog(String msg, Object from, Object to, GuiMappingContext context)
Object	createNewValue(GuiMappingContext context)
void	errorWhileAddHistoryValue(GuiMappingContext context, Object value, Throwable ex)	called from addHistoryValue(GuiMappingContext, Object) and special handling for IllegalAccessException which means an addition of a large object to the prefs store
Object	fromJson(GuiMappingContext context, Object target, Object json)	create a new value object from the JSON with treating the target as an old value, or update the target with the JSON contents.
Object	fromSource(Object o)
protected GuiUpdatedValue	fromSourceUpdated(GuiMappingContext context, GuiUpdatedValue v)
static Supplier<GuiReprValue.ObjectSpecifier>	getNoneSupplier()
GuiMappingContext.GuiSourceValue	getParentSource(GuiMappingContext context, GuiReprValue.ObjectSpecifier parentSpecifier)	obtain the current parent value from the parent context by calling getUpdatedSource(GuiMappingContext, ObjectSpecifier)
GuiMappingContext.GuiSourceValue	getUpdatedSource(GuiMappingContext context, GuiReprValue.ObjectSpecifier specifier)	call getUpdatedValue(GuiMappingContext, ObjectSpecifier) only if the context holds a value pane and 1) the current source is NONE or 2) GuiReprValue.ObjectSpecifier.isUsingCache()=false, and if NO_UPDATE, then return the current source from the context,
GuiUpdatedValue	getUpdatedValue(GuiMappingContext context, GuiReprValue.ObjectSpecifier specifier)	obtain the current value of the context.
Object	getUpdatedValueWithoutNoUpdate(GuiMappingContext context, GuiReprValue.ObjectSpecifier specifier)	call getUpdatedValue(GuiMappingContext, ObjectSpecifier) and never return NO_UPDATE
GuiUpdatedValue	getValue(GuiMappingContext context, GuiMappingContext.GuiSourceValue parentSource, GuiReprValue.ObjectSpecifier specifier, GuiMappingContext.GuiSourceValue prev)	obtain the property value from parentSource as an owner.
GuiUpdatedValue	getValueCollectionElement(GuiMappingContext context, GuiMappingContext.GuiSourceValue collection, GuiReprValue.ObjectSpecifier elementSpecifier, GuiMappingContext.GuiSourceValue prev)	a table pane returns an element in a collection
int	getValueCollectionSize(GuiMappingContext context, GuiMappingContext.GuiSourceValue collection, GuiReprValue.ObjectSpecifier specifier)	a table pane returns the size of a collection
Class<?>	getValueType(GuiMappingContext context)	obtains the value type from the context.
Object	getValueWithoutNoUpdate(GuiMappingContext context, GuiMappingContext.GuiSourceValue parentSource, GuiReprValue.ObjectSpecifier specifier)	call getValue(GuiMappingContext, GuiMappingContext.GuiSourceValue, GuiReprValue.ObjectSpecifier, GuiMappingContext.GuiSourceValue) and never return NO_UPDATE
boolean	isEditable(GuiMappingContext context)
boolean	isFromJsonTakingMapWithContextNameEntry(GuiMappingContext context)
boolean	isHistoryValueStored(Object value)
boolean	isHistoryValueStored(GuiMappingContext context, Object value)	currently checked by isHistoryValueSupported(GuiMappingContext)
boolean	isHistoryValueSupported()
boolean	isHistoryValueSupported(GuiMappingContext context)	checks whether the context supports the value history feature or not.
boolean	isUpdateContextSourceByUpdateFromGui(GuiMappingContext context)
boolean	match(GuiMappingContext context)	match the representation with the typeElement of the context, and if succeed, it sets this representation to the context, and it might create sub-contexts for recursive matches *
boolean	matchValueType(Class<?> cls)
void	setSource(GuiMappingContext context, Object value)
Object	toJson(GuiMappingContext context, Object source)	convert the source into JSON format
Object	toParentSource(GuiMappingContext context, GuiMappingContext.GuiSourceValue v)
Object	toSource(Object o)
String	toString()
Object	toUpdateValue(GuiMappingContext context, Object value)	called from a GUI element in order to update the it's value.
static Object	unwrapNoUpdate(GuiMappingContext.GuiSourceValue prev, GuiUpdatedValue ret)
Object	update(GuiMappingContext context, GuiMappingContext.GuiSourceValue parentSource, Object newValue, GuiReprValue.ObjectSpecifier specifier)	set a new value to an property of an object, which specified by the context using GuiMappingContext.execute(Callable) if the type is a GuiTypeMemberProperty, update the property by GuiTypeMemberProperty.executeSet(Object, Object) if parent is a property GuiReprPropertyPane or a collection element GuiReprCollectionElement, obtain the parent source of the parent, and update the parent with the source and newValue.
Object	updateCollectionElement(GuiMappingContext context, GuiMappingContext.GuiSourceValue collection, Object newValue, GuiReprValue.ObjectSpecifier elementSpecifier)	a table pane updates an specified element
void	updateFromGui(GuiMappingContext context, Object newValue, GuiReprValue.ObjectSpecifier specifier, GuiTaskClock viewClock)	call the setter by editing on GUI, and GuiMappingContext.updateSourceFromGui(Object).
Object	updateWithParentSource(GuiMappingContext context, Object newValue, GuiReprValue.ObjectSpecifier specifier)	obtain the parent source by getUpdatedSource(GuiMappingContext, GuiReprValue.ObjectSpecifier) and call update(GuiMappingContext, GuiMappingContext.GuiSourceValue, Object, GuiReprValue.ObjectSpecifier)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.autogui.base.mapping.GuiRepresentation

continueCheckAndUpdateSourceForChildren, fromHumanReadableString, fromJsonWithNamed, isJsonSetter, isTaskRunnerUsedFor, matchAndSetNotifiersAsInit, setNotifiersTree, shutdown, toHumanReadableString, toJsonWithNamed, toStringHeader

Field Details

NONE

public static GuiReprValue.ObjectSpecifierNothing NONE

special specifier for non-indexed property values without caching. the parent of the specifier always this instance (cyclic).

NONE_WITH_CACHE

public static GuiReprValue.ObjectSpecifierNothing NONE_WITH_CACHE

Constructor Details

GuiReprValue

public GuiReprValue()

Method Details

match

public boolean match(GuiMappingContext context)

Description copied from interface: GuiRepresentation

match the representation with the typeElement of the context, and if succeed, it sets this representation to the context, and it might create sub-contexts for recursive matches *

Specified by:

match in interface GuiRepresentation

Parameters:

context - the context of the repr.

Returns:

the matching result

getValueType

public Class<?> getValueType(GuiMappingContext context)

obtains the value type from the context. the implementation checks the context is a property, or an element value

Parameters:

context - the context

Returns:

a property type class, a element value class, or null

matchValueType

public boolean matchValueType(Class<?> cls)

checkAndUpdateSource

public boolean checkAndUpdateSource(GuiMappingContext context)

the class supposes that the parent is a GuiReprPropertyPane: [propName: [objectPane]]. then, the parent of source and this source are a same value; and the parent is already checkAndUpdateSource and a new value is supplied. the method uses getUpdatedValue(GuiMappingContext, ObjectSpecifier) with the NONE specifier.

As additional side-effect, the updated value will be added to the value-history if supported by addHistoryValue(GuiMappingContext, Object), and the value will also be set as a new source value by setSource(GuiMappingContext, Object)

Specified by:

checkAndUpdateSource in interface GuiRepresentation

Parameters:

context - the source context

Returns:

the source context is updated or not

addHistoryValue

public void addHistoryValue(GuiMappingContext context,
 Object value)

errorWhileAddHistoryValue

public void errorWhileAddHistoryValue(GuiMappingContext context,
 Object value,
 Throwable ex)

called from addHistoryValue(GuiMappingContext, Object) and special handling for IllegalAccessException which means an addition of a large object to the prefs store

Parameters:

context - the context object

value - the added value

ex - the exception caught

Since:

1.2

setSource

public void setSource(GuiMappingContext context,
 Object value)

getValue

public GuiUpdatedValue getValue(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue parentSource,
 GuiReprValue.ObjectSpecifier specifier,
 GuiMappingContext.GuiSourceValue prev)
                         throws Throwable

obtain the property value from parentSource as an owner.

In this class, support following cases:

• the type is a GuiTypeMemberProperty
• other types: use methods of GuiTypeValue with prev and parentSource as the inherited value

Parameters:

context - the context holding the repr.

parentSource - the property owner. if no value then nothing will happen for properties

specifier - the specifier of the value

prev - a previous value compared to the obtained value

Returns:

an obtained property value (nullable) or GuiUpdatedValue.NO_UPDATE if the value is equivalent to the previous value.

Throws:

Throwable - might be caused by executing method invocations.

convertLog

public static void convertLog(String msg,
 Object from,
 Object to,
 GuiMappingContext context)

toParentSource

public Object toParentSource(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue v)

fromSourceUpdated

protected GuiUpdatedValue fromSourceUpdated(GuiMappingContext context,
 GuiUpdatedValue v)

getValueWithoutNoUpdate

public Object getValueWithoutNoUpdate(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue parentSource,
 GuiReprValue.ObjectSpecifier specifier)
                               throws Throwable

call getValue(GuiMappingContext, GuiMappingContext.GuiSourceValue, GuiReprValue.ObjectSpecifier, GuiMappingContext.GuiSourceValue) and never return NO_UPDATE

Parameters:

context - the context

parentSource - the property owner. if null then nothing will happen for properties

specifier - the specifier of the value

Returns:

an obtained value or null

Throws:

Throwable - might be caused by executing method invocation

unwrapNoUpdate

public static Object unwrapNoUpdate(GuiMappingContext.GuiSourceValue prev,
 GuiUpdatedValue ret)

getUpdatedValue

public GuiUpdatedValue getUpdatedValue(GuiMappingContext context,
 GuiReprValue.ObjectSpecifier specifier)
                                throws Throwable

obtain the current value of the context. This is called from checkAndUpdateSource(GuiMappingContext), and invoke getParentSource(GuiMappingContext, GuiReprValue.ObjectSpecifier) and getValue(GuiMappingContext, GuiMappingContext.GuiSourceValue, GuiReprValue.ObjectSpecifier, GuiMappingContext.GuiSourceValue)

Parameters:

context - target context,

specifier - the specifier of the value

Returns:

the current value (nullable) or GuiUpdatedValue.NO_UPDATE

Throws:

Throwable - might be caused by executing method invocations.

getUpdatedValueWithoutNoUpdate

public Object getUpdatedValueWithoutNoUpdate(GuiMappingContext context,
 GuiReprValue.ObjectSpecifier specifier)
                                      throws Throwable

call getUpdatedValue(GuiMappingContext, ObjectSpecifier) and never return NO_UPDATE

Parameters:

context - the context

specifier - the specifier of the value

Returns:

original source (nullable), never NO_UPDATE

Throws:

Throwable - might be caused by executing method invocation

getUpdatedSource

public GuiMappingContext.GuiSourceValue getUpdatedSource(GuiMappingContext context,
 GuiReprValue.ObjectSpecifier specifier)
                                                  throws Throwable

call getUpdatedValue(GuiMappingContext, ObjectSpecifier) only if the context holds a value pane and 1) the current source is NONE or 2) GuiReprValue.ObjectSpecifier.isUsingCache()=false, and if NO_UPDATE, then return the current source from the context,

Parameters:

context - the context

specifier - the specifier of the value

Returns:

the updated value as a source-value or the current source value of the context

Throws:

Throwable - might be cause d by executing method invocation

getParentSource

public GuiMappingContext.GuiSourceValue getParentSource(GuiMappingContext context,
 GuiReprValue.ObjectSpecifier parentSpecifier)
                                                 throws Throwable

obtain the current parent value from the parent context by calling getUpdatedSource(GuiMappingContext, ObjectSpecifier)

Parameters:

context - the context of the repr.

parentSpecifier - the specifier of the parent value

Returns:

the source value of the parent

Throws:

Throwable - the action might cause an error

getValueCollectionElement

public GuiUpdatedValue getValueCollectionElement(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue collection,
 GuiReprValue.ObjectSpecifier elementSpecifier,
 GuiMappingContext.GuiSourceValue prev)
                                          throws Throwable

a table pane returns an element in a collection

Parameters:

context - the context of the repr

collection - a collection target

elementSpecifier - an element index i.e. GuiReprValue.ObjectSpecifierIndex

prev - the previous value of the element

Returns:

an element in the collection, default is null

Throws:

Throwable - an error while getting

getValueCollectionSize

public int getValueCollectionSize(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue collection,
 GuiReprValue.ObjectSpecifier specifier)
                           throws Throwable

a table pane returns the size of a collection

Parameters:

context - the context of the repr

collection - a collection target

specifier - the specifier of the collection

Returns:

the size of the collection, default is 1

Throws:

Throwable - an error while getting

updateCollectionElement

public Object updateCollectionElement(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue collection,
 Object newValue,
 GuiReprValue.ObjectSpecifier elementSpecifier)
                               throws Throwable

a table pane updates an specified element

Parameters:

context - the context of the repr

collection - a collection target

newValue - an element value

elementSpecifier - an element index i.e. GuiReprValue.ObjectSpecifierIndex

Returns:

the updated value

Throws:

Throwable - an error while updating

updateFromGui

public void updateFromGui(GuiMappingContext context,
 Object newValue,
 GuiReprValue.ObjectSpecifier specifier,
 GuiTaskClock viewClock)

call the setter by editing on GUI, and GuiMappingContext.updateSourceFromGui(Object).

• add newValue to the history by addHistoryValue(GuiMappingContext, Object)
• obtain parent source and update updateWithParentSource(GuiMappingContext, Object, ObjectSpecifier)
• check isUpdateContextSourceByUpdateFromGui(GuiMappingContext) and GuiMappingContext.updateSourceFromGui(Object): update the source and notify to listeners

Parameters:

context - the context of this repr.

newValue - the updated property value

specifier - the specifier of the value

viewClock - the clock value of sender view

isUpdateContextSourceByUpdateFromGui

public boolean isUpdateContextSourceByUpdateFromGui(GuiMappingContext context)

updateWithParentSource

public Object updateWithParentSource(GuiMappingContext context,
 Object newValue,
 GuiReprValue.ObjectSpecifier specifier)
                              throws Throwable

obtain the parent source by getUpdatedSource(GuiMappingContext, GuiReprValue.ObjectSpecifier) and call update(GuiMappingContext, GuiMappingContext.GuiSourceValue, Object, GuiReprValue.ObjectSpecifier)

Parameters:

context - the target context

newValue - a new value to be set to the property

specifier - the specifier of the value

Returns:

the returned value by updating

Throws:

Throwable - an error while getParentSource or update

update

public Object update(GuiMappingContext context,
 GuiMappingContext.GuiSourceValue parentSource,
 Object newValue,
 GuiReprValue.ObjectSpecifier specifier)
              throws Throwable

set a new value to an property of an object, which specified by the context

• using GuiMappingContext.execute(Callable)
• if the type is a GuiTypeMemberProperty, update the property by GuiTypeMemberProperty.executeSet(Object, Object)
• if parent is a property GuiReprPropertyPane or a collection element GuiReprCollectionElement, obtain the parent source of the parent, and update the parent with the source and newValue. This will be done by parent's updateWithParentSource(GuiMappingContext, Object, ObjectSpecifier)
• otherwise call GuiTypeValue.writeValue(Object, Object) or a similar method

Parameters:

context - the target context

parentSource - the property owner

newValue - a new value to be set to the property

specifier - the specifier of the value

Returns:

newValue which will need to be passed to GuiMappingContext.updateSourceFromGui(Object), or null if error

Throws:

Throwable - an error while updating

isHistoryValueSupported

public boolean isHistoryValueSupported()

Returns:

if true, updateFromGui(GuiMappingContext, Object, ObjectSpecifier, GuiTaskClock) automatically add the value to the preferences. the default impl. returns true.

isHistoryValueStored

public boolean isHistoryValueStored(Object value)

Parameters:

value - the tested value, or null at loading

Returns:

if true, actually the value is stored to the preferences store

isHistoryValueStored

public boolean isHistoryValueStored(GuiMappingContext context,
 Object value)

currently checked by isHistoryValueSupported(GuiMappingContext)

Parameters:

context - the context object

value - stored value

Returns:

true if the context supports storing the value as a history

Since:

1.2

isHistoryValueSupported

public boolean isHistoryValueSupported(GuiMappingContext context)

checks whether the context supports the value history feature or not. it can be controlled by the annotation parameter "history".

Parameters:

context - the context object

Returns:

true if the context supports storing history values

Since:

1.2

isEditable

public boolean isEditable(GuiMappingContext context)

Parameters:

context - the context of the repr.

Returns:

the result of GuiTypeMemberProperty.isWritable() and so on.

toUpdateValue

public Object toUpdateValue(GuiMappingContext context,
 Object value)

called from a GUI element in order to update the it's value. subclass can change to returned type and convert the value to the type. a typical use case is just down-casting and converting null to an empty object.

Parameters:

context - the context of the repr.

value - the current value

Returns:

the updated value

toJson

public Object toJson(GuiMappingContext context,
 Object source)

Description copied from interface: GuiRepresentation

convert the source into JSON format

Specified by:

toJson in interface GuiRepresentation

Parameters:

context - a context holds the representation

source - the converted object

Returns:

JSON objects representing the source; String, Number, Boolean, List, Map or null

fromJson

public Object fromJson(GuiMappingContext context,
 Object target,
 Object json)

Description copied from interface: GuiRepresentation

create a new value object from the JSON with treating the target as an old value, or update the target with the JSON contents. the behavior can be varied by each representation, confirmed by GuiRepresentation.isJsonSetter().

Specified by:

fromJson in interface GuiRepresentation

Parameters:

context - a context holds the representation

target - the target object or null

json - JSON objects representing the target String, Number, Boolean, List, Map or null

Returns:

created object from the json, target if provided, or null.

isFromJsonTakingMapWithContextNameEntry

public boolean isFromJsonTakingMapWithContextNameEntry(GuiMappingContext context)

Parameters:

context - the target context

Returns:

true means fromJson(GuiMappingContext, Object, Object) takes a map with the entry named GuiMappingContext.getName()

createNewValue

public Object createNewValue(GuiMappingContext context)
                      throws Throwable

Throws:

Throwable

castOrMake

public static <T> T castOrMake(Class<T> cls,
 Object o,
 Supplier<T> v)

cast o if o is a non-null and specified type cls, otherwise call v. used in toJson(GuiMappingContext, Object).

Type Parameters:

T - the required type

Parameters:

cls - the required class T

o - the current value, nullable

v - the falling-back supplier

Returns:

o or the result of v

toString

public String toString()

Overrides:

toString in class Object

fromSource

public Object fromSource(Object o)

Parameters:

o - a raw-object which can be directly passed to type-element's executing methods

Returns:

a wrapped object for clients of the representation

toSource

public Object toSource(Object o)

Parameters:

o - a wrapped object for clients of the representation

Returns:

a raw-object which can be directly passed to type-element's executing methods

getNoneSupplier

public static Supplier<GuiReprValue.ObjectSpecifier> getNoneSupplier()

Returns:

a lambda for returning NONE