dotsTheMachineConfiguration Class Reference

Overview

Singleton to organize machine-specific defaults.

dotsTheMachineConfiguration organizes values for configuring a particular computer, such as its IP address, screen dimensions, or path for locating files.

dotsTheMachineConfiguration starts out with a set of "factory default" values which are valid but not always useful. From there it can read and write custom values stored in an .xml file. If an .xml file with a standard name is on the Matlab path, dotsTheMachineConfiguration automatically loads values from that file. See dotsTheMachineConfiguration.getHostFilename() for the machine-specific name to use for the standard .xml file.

dotsTheMachineConfiguration.writeUserSettingsFile() opens a dialog for saving custom values. It suggests the machine-specific, standard name bu default. So this is an easy way to create an .xml file with custom values.

Values stored in .xml files are written out as Matlab expresssions, which can be passed to Matlab's built-in eval() function. So the .xml contents are human-readable.

.xml files can be edited outside of Matlab. New groups and values can be added, as long as new sections follow the structure of existing sections.

Inheritance diagram for dotsTheMachineConfiguration:

Properties and Events
Property	settings
	topsGroupedList that contains the current settings values More...
Property	settingsFile
	file name of the currently loaded settings file More...
Properties and Events inherited from dotsAllSingletonObjects
null	obj = theObject(varargin)
	Return the current class instance from the private constructor.
null	g = gui()
	Launch a grapical interface for the current instance.

Protected Properties
Property	defaultGroup = 'defaults'
	group name for generic defaults

Methods
	initialize (self)
	Restore dotsTheMachineConfiguration to a fresh state. More...
xDoc	settingsToXmlDocument (self)
	Create an xml document object that contains the current settings. More...
	settingsFromXmlDocument (self, xDoc)
	Read new settings from an xml document object. More...
	settingsToXmlFile (self, fileWithPath)
	Write an .xml file that contains the current settings. More...
	settingsFromXmlFile (self, fileWithPath)
	Read an .xml file that contains new settings. More...
hostFile	getHostFilename ()
	Get the standard settings file name for this host. More...
value	getDefaultValue (name)
	Get the value of a default setting by name. More...
	setDefaultValue (name, value)
	Set the value of a default setting by name. More...
values	getClassDefaults (className)
	Get all the default settings associated with a class. More...
	setClassDefaults (className, values)
	Set all the default settings associated with a class. More...
	applyClassDefaults (object, className)
	Assign class defaults to the given object. More...
	readUserSettingsFile (fileWithPath)
	Read an .xml file that contains new settings. More...
	writeUserSettingsFile (fileWithPath)
	Write an .xml file that contains the current settings. More...
Methods inherited from dotsAllSingletonObjects
null	reset (varargin)
	Restore a fresh state without deleting the current instance.
null	initialize (self)
	Restore a fresh state without deleting the current object, used by constructor and reset(). More...
	initializeLists (self, listNames)
	Create or refresh topsGroupedList instances.
	set (self, varargin)
	Set multiple properties.

Protected Methods
	setFactoryDefaults (self)
	Restore dotsTheMachineConfiguration to its factory state. More...

Static Methods
static obj	theObject (varargin)
	Access the current instance.
static	reset (varargin)
	Restore the current instance to a fresh state.
static g	gui ()
	Launch a graphical interface to view and set settings.

Private Methods
self	dotsTheMachineConfiguration (varargin)
	Constructor is private. More...

Constructor

dotsTheMachineConfiguration()

self dotsTheMachineConfiguration ( varargin  )

private

Constructor is private.

dotsTheMachineConfiguration is a singleton object, so its constructor is not accessible. Use dotsTheMachineConfiguration.theObject() to access the current instance.

Methods

initialize()

initialize

(

self

)

Restore dotsTheMachineConfiguration to a fresh state.

Discards the current settings values and attempts to reload values from one of the following sources, in order:

• the current settingsFile
• the default "host settings" file
• the hard-coded defaults

settingsToXmlDocument()

xDoc settingsToXmlDocument

(

self

)

Create an xml document object that contains the current settings.

Returns a new com.mathworks.xml Java document object which contains the settings from settings. Each value is converted to a string using the Snow Dots primitiveToString() utility.

settingsFromXmlDocument()

settingsFromXmlDocument	(	self	,
		xDoc
	)

Read new settings from an xml document object.

Parameters

xDoc	a com.mathworks.xml Java document object which contains settings values.

Discards the current settings and populates settings with values from xDoc. Uses eval() to convert stored value strings to Matlab variables. xDoc should resemble the document objects returned from settingsToXmlDocument().

xDoc may be a partial list of settings. Missing settings will be filled in with default values from setFactoryDefaults().

settingsToXmlFile()

settingsToXmlFile	(	self	,
		fileWithPath
	)

Write an .xml file that contains the current settings.

Parameters

fileWithPath

the file name, which may contain a path, where to write xml data.

Writes an .xml file containing the current settings, at the given fileWithPath. Uses settingsToXmlDocument() to covert the current settings to a com.mathworks.xml Java document object, then writes the document object to file.

Since the resulting .xml file contains human-readable strings, the settings in it can be edited from any text editor. The only constraint is that the strings produce valid variables when passed to Matlab's eval() function.

The static methods dotsTheMachineConfiguration.readUserSettingsFile() and dotsTheMachineConfiguration.writeUserSettingsFile() may be more convenient to use.

settingsFromXmlFile()

settingsFromXmlFile	(	self	,
		fileWithPath
	)

Read an .xml file that contains new settings.

Parameters

fileWithPath

the file name, which may contain a path, where to find xml data.

Reads an .xml file containing the new settings from the given fileWithPath. Uses settingsFromXmlDocument() to parse the file then uses Matlab's eval() to convert stored strings to Matlab variable and stores them in settings. Discards any previous settings.

The static methods dotsTheMachineConfiguration.readUserSettingsFile() and dotsTheMachineConfiguration.writeUserSettingsFile() may be more convenient to use.

setFactoryDefaults()

setFactoryDefaults ( self  )

protected

Restore dotsTheMachineConfiguration to its factory state.

Discards the current settings values and loads the hard-coded factory defaults.

getHostFilename()

hostFile getHostFilename

(

)

Get the standard settings file name for this host.

Returns the standard file name for an .xml settings file on this host, suitable for automatic loading.

getDefaultValue()

value getDefaultValue

(

name

)

Get the value of a default setting by name.

Parameters

name	string name of a default setting

Returns the default value with the given name, or [] if there is no default with that name.

setDefaultValue()

setDefaultValue	(	name	,
		value
	)

Set the value of a default setting by name.

Parameters

name	string name of a default setting
value	new value to store under name

Stores a new default value under the given name, or creates a new default with the given name.

getClassDefaults()

values getClassDefaults

(

className

)

Get all the default settings associated with a class.

Parameters

className

class name or object to get defaults for

className must be a string class name, or an object, in which case the object's class name is determined with the built-in class() function. Returns a struct containing all of the default settings associated with the given className. Struct fields correspond to class properties. If there are no default values associates with className, returns [].

setClassDefaults()

setClassDefaults	(	className	,
		values
	)

Set all the default settings associated with a class.

Parameters

className	class name or object to get defaults for
values	struct of defaults to associate with className

className must be a string class name, or an object, in which case the object's class name is determined with the built-in class() function. values must be a struct containing default settings to associate with className. The fields of values must correspond to class properties.

applyClassDefaults()

applyClassDefaults	(	object	,
		className
	)

Assign class defaults to the given object.

Parameters

object	an object to receive default values
className	optional, class to impose on object

object must be an object to receive default property values. By default, uses class(object) to determine which group of default values to assign to object. If className is the string name of a class, applies this group of defaults instead.

If there are no default values associates with object or className, does nothing. Returns the updated object.

readUserSettingsFile()

readUserSettingsFile

(

fileWithPath

)

Read an .xml file that contains new settings.

Parameters

fileWithPath

the file name, which may contain a path, where to find xml data.

If fileWithPath is missing, opens a dialog for chosing a suitable file.

writeUserSettingsFile()

writeUserSettingsFile

(

fileWithPath

)

Write an .xml file that contains the current settings.

Parameters

fileWithPath

the file name, which may contain a path, where to write xml data.

If fileWithPath is missing, opens a dialog for chosing a suitable file.

Properties and Events

settings

Property settings

topsGroupedList that contains the current settings values

Settings groups are strings, such as class names. Group mnemonics are strings, such as property names.

settingsFile

Property settingsFile

file name of the currently loaded settings file

settingsFile may contain an absolute path along with the name of a settings .xml file. If settingsFile is empty or Matlab cannot locate it with the built-in exist() function, dotsTheMachineConfiguration will use default settings values.

---

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

• dotsTheMachineConfiguration.m