ilog.views.graphlayout

Interface IlvGrapherPropertyAdapter

All Known Implementing Classes:

IltGrapherAdapter, IlvGrapherAdapter, IlvRotatedGraphModel

public interface IlvGrapherPropertyAdapter

An IlvGrapherPropertyAdapter supports saving graph layout parameters to named properties of an encapsulated IlvGrapher. It is implemented by subclasses of IlvGraphModel if they support this mechanism.

The typical calling sequence to save a grapher with layout parameter settings into an .ivl file for some attached layouts is:

 // convert the layout parameter into named properties
 if (layout1.supportsSaveParametersToNamedProperties())
   grapherParameterAdapter.saveParametersToNamedProperties(layout1, false);
 if (layout2.supportsSaveParametersToNamedProperties())
   grapherParameterAdapter.saveParametersToNamedProperties(layout2, false);
 if (layout3.supportsSaveParametersToNamedProperties())
   grapherParameterAdapter.saveParametersToNamedProperties(layout3, false);
 ...
 // save the grapher with the named properties
 grapherParameterAdapter.getGrapher().write("abcd.ivl");
 grapherParameterAdapter.removeParametersFromNamedProperties();
 

The typical calling sequence to read a grapher with layout parameter settings for some attached layouts is:

 // read the grapher with the named properties
 grapherParameterAdapter.getGrapher().read("abcd.ivl");
 // convert the named properties into layout parameters
 grapherParameterAdapter.loadParametersFromNamedProperties(layout1);
 grapherParameterAdapter.loadParametersFromNamedProperties(layout2);
 grapherParameterAdapter.loadParametersFromNamedProperties(layout3);
 ...
 grapherParameterAdapter.removeParametersFromNamedProperties();
 

Since:

JViews 8.8

Method Summary

Modifier and Type	Method and Description
IlvGrapher	getGrapher() Returns the IlvGrapher encapsulated by the adapter.
String	getLayoutPropertyPrefix(IlvGraphLayout layout) Returns the property name of the input layout, if it was most recently stored as a named property, or null if the layout was never stored.
String	getPreferredLayoutPropertyPrefix() Returns the property name of the preferred layout, or null if no preferred layout was stored.
boolean	loadParametersFromNamedProperties(IlvGraphLayout layout) Transfers the layout parameter settings from the named properties of the grapher back to the layout instance.
boolean	loadParametersFromNamedProperties(IlvGraphLayout layout, String propertyPrefix) Transfers the layout parameter settings from the named properties of the grapher back to the layout instance.
IlvGraphLayout	loadParametersFromNamedProperties(String propertyPrefix) Transfers the layout parameter settings from the named properties of the grapher back to a new layout instance.
boolean	loadPreferredLayoutsFromNamedProperties(IlvDefaultLayoutProvider layoutProvider, boolean withParameters, boolean traverse) Loads the preferred layout settings from the named properties of the grapher into an IlvDefaultLayoutProvider.
void	removeParametersFromNamedProperties() Removes all named properties that were used to store the graph layout parameter settings from the grapher.
void	removeParametersFromNamedProperties(Class layoutClass) Removes the named properties that were used to store the graph layout parameter settings from the grapher.
void	removeParametersFromNamedProperties(String propertyPrefix) Removes the named properties that were used to store the graph layout parameter settings from the grapher.
String	saveParametersToNamedProperties(IlvGraphLayout layout, boolean withDefaults) Transfers the layout parameter settings to named properties of the grapher.
String	saveParametersToNamedProperties(IlvGraphLayout layout, String propertyPrefix, boolean withDefaults) Transfers the layout parameter settings to named properties of the grapher.
boolean	savePreferredLayoutsToNamedProperties(IlvDefaultLayoutProvider layoutProvider, boolean withParameters, boolean withDefaults, boolean traverse) Transfers the preferred layout settings to named properties of the grapher.
void	setPreferredLayoutPropertyPrefix(String propertyPrefix) Sets the property name of the preferred layout.

Method Detail

getGrapher

IlvGrapher getGrapher()

Returns the IlvGrapher encapsulated by the adapter.

saveParametersToNamedProperties

String saveParametersToNamedProperties(IlvGraphLayout layout,
                                       boolean withDefaults)

Transfers the layout parameter settings to named properties of the grapher.

If you want to store layout parameter settings into .ivl files, this method should be called before IlvGrapher.write(ilog.views.io.IlvOutputStream). It creates objects of class IlvGraphLayoutGrapherProperty, IlvGraphLayoutNodeProperty, and IlvGraphLayoutLinkProperty, stores the layout parameter settings in these objects, and adds the objects as persistent named properties with a unique property name to the grapher.

The named properties contain a copy of the parameter settings. It is possible to save the parameter settings, change the parameters temporarily in the working instance of layout, and restore the saved values later using the method loadParametersFromNamedProperties(ilog.views.graphlayout.IlvGraphLayout). This can be nested, because the last saved parameters are loaded first.

To avoid wasting memory, it is recommended that you remove the properties when they are no longer needed, for example, immediately after writing to a file or to an output stream. It is possible to transfer and store the parameter settings of multiple layouts at the same time. The typical calling sequence to save a grapher with layout parameter settings for some attached layouts is:

 if (layout1.supportsSaveParametersToNamedProperties())
   grapherParameterAdapter.saveParametersToNamedProperties(layout1, false);
 if (layout2.supportsSaveParametersToNamedProperties())
   grapherParameterAdapter.saveParametersToNamedProperties(layout2, false);
 if (layout3.supportsSaveParametersToNamedProperties())
   grapherParameterAdapter.saveParametersToNamedProperties(layout3, false);
 ...
 grapherParameterAdapter.getGrapher().write("abcd.ivl");
 grapherParameterAdapter.removeParametersFromNamedProperties();
 

If false is passed for the argument withDefaults, the layout properties are persistent only if they contain parameters that are not default values. As a result, the .ivl files will be smaller. If true is passed for the argument withDefaults, the layout properties are always persistent, and the default values of the layout parameter settings are also written to files by the next call of IlvGrapher.write(ilog.views.io.IlvOutputStream).

If the input layout does not support saving parameters to named properties, a RuntimeException is thrown.

Parameters:

layout - The layout instance to be saved. It should be attached to this grapher adapter.

withDefaults - If true, the layout properties are always persistent. If false, they are persistent only if nondefault parameter settings exist (that is, if the property is saved to an .ivl file, the default parameter settings are not saved).

Returns:

The generated, unique property name that is used to store the layout properties.

See Also:

loadParametersFromNamedProperties(ilog.views.graphlayout.IlvGraphLayout), removeParametersFromNamedProperties(), IlvGraphLayout.supportsSaveParametersToNamedProperties(), IlvNamedProperty

saveParametersToNamedProperties

String saveParametersToNamedProperties(IlvGraphLayout layout,
                                       String propertyPrefix,
                                       boolean withDefaults)

Transfers the layout parameter settings to named properties of the grapher. The name for the properties is generated from the propertyPrefix and the layout instance. This method is used internally to recursively transfer the parameters of sublayout instances of a parent layout to properties.

If the input layout does not support saving parameters to named properties, a RuntimeException is thrown.

Parameters:

layout - The layout instance to be saved. It should be attached to this grapher adapter.

propertyPrefix - The prefix of the generated unique property name that is used to store the layout properties.

withDefaults - If true, the layout properties are always persistent. If false, they are persistent only if nondefault parameter settings exist (that is, if the the property is saved to an .ivl file, the default parameter settings are not saved).

Returns:

The generated, unique property name that is used to store the layout properties.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), IlvGraphLayout.supportsSaveParametersToNamedProperties()

savePreferredLayoutsToNamedProperties

boolean savePreferredLayoutsToNamedProperties(IlvDefaultLayoutProvider layoutProvider,
                                              boolean withParameters,
                                              boolean withDefaults,
                                              boolean traverse)

Transfers the preferred layout settings to named properties of the grapher.

If you want to store preferred layout settings into .ivl files, this method should be called before IlvGrapher.write(ilog.views.io.IlvOutputStream). It creates objects of class IlvGraphLayoutGrapherProperty, IlvGraphLayoutNodeProperty, and IlvGraphLayoutLinkProperty, stores the preferred layout settings in these objects, and adds the objects as persistent named properties with a unique property name to the grapher.

If false is passed for the argument withParameters, the parameters of the preferred layouts are not saved. Otherwise, the preferred layouts are saved with their parameters.

If false is passed for the argument withDefaults, the layout properties are persistent only if they contain parameters that are not default values. As a result, the .ivl files will be smaller. If true is passed for the argument withDefaults, the layout properties are always persistent, and the default values of the layout parameter settings are also written to files by the next call of IlvGrapher.write(ilog.views.io.IlvOutputStream).

If the input layout does not support saving parameters to named properties, a RuntimeException is thrown.

Parameters:

layoutProvider - The layout provider into which the choices of the preferred layouts for each graph and subgraph were stored.

withParameters - If true, the parameters of the preferred layouts are also stored. If false, only the name of the class of the preferred layout is saved.

withDefaults - If true, the layout parameters are always persistent. If false, they are persistent only if nondefault parameter settings exist (that is, if the the property is saved to an .ivl file, the default parameter settings are not saved). This parameter has no effect if the parameter withParameters is false.

traverse - If true, the method applies recursively to the subgraphs. Otherwise, the method applies only to this IlvGraphModel

Returns:

true if the preferred layout for at least one subgraph or the root graph has been saved, and false otherwise.

See Also:

loadPreferredLayoutsFromNamedProperties(ilog.views.graphlayout.IlvDefaultLayoutProvider, boolean, boolean), IlvGraphLayout.PerformLayout(ilog.views.graphlayout.IlvGraphModel, ilog.views.graphlayout.IlvLayoutProvider, boolean, boolean, boolean), IlvGraphModel.performLayout(ilog.views.graphlayout.IlvLayoutProvider, boolean, boolean, boolean)

loadParametersFromNamedProperties

boolean loadParametersFromNamedProperties(IlvGraphLayout layout)

Transfers the layout parameter settings from the named properties of the grapher back to the layout instance.

If you stored layout parameter settings into .ivl files using the method saveParametersToNamedProperties(ilog.views.graphlayout.IlvGraphLayout, boolean) and want to load them again, this method should be called after IlvManager.read(java.io.InputStream). It searches for a set of layout parameter properties that matches the class of the input layout, transfers the parameters to the layout instance, and removes this set of named layout properties from the grapher.

If multiple settings of parameters of different layout classes were saved, it loads the setting that fits the input layout class (for instance, it loads the tree layout settings if the input class is IlvTreeLayout). If multiple settings of parameters of the same layout class were saved, it loads the setting that was last saved by implementing the stack principle (the last-in, first-out principle).

The typical calling sequence to read a grapher with layout parameter settings for some attached layouts is:

 grapherParameterAdapter.getGrapher().read("abcd.ivl");
 grapherParameterAdapter.loadParametersFromNamedProperties(layout1);
 grapherParameterAdapter.loadParametersFromNamedProperties(layout2);
 grapherParameterAdapter.loadParametersFromNamedProperties(layout3);
 ...
 grapherParameterAdapter.removeParametersFromNamedProperties();
 

In this example, the final call of removeParametersFromNamedProperties is recommended to avoid wasting memory when it is not known whether all layout properties were loaded.

Parameters:

layout - The layout instance whose parameters are to be loaded. It should be attached to this grapher adapter.

Returns:

true if layout parameters for the input layout were stored in named properties of the grapher, false otherwise.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), removeParametersFromNamedProperties(), IlvGraphLayoutGrapherProperty.transfer(ilog.views.graphlayout.IlvGraphLayout), IlvGraphLayoutNodeProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic), IlvGraphLayoutLinkProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic)

loadParametersFromNamedProperties

boolean loadParametersFromNamedProperties(IlvGraphLayout layout,
                                          String propertyPrefix)

Transfers the layout parameter settings from the named properties of the grapher back to the layout instance.

It searches for a set of layout parameter properties that has the property prefix string in the property name. It transfers the parameters to the layout instance and removes this set of named layout properties from the grapher.

This method can also be used when the property prefix string is the full property name.

Parameters:

layout - The layout instance whose parameters are to be loaded. It should be attached to this grapher adapter.

propertyPrefix - The prefix of the unique property name that was used to store the layout properties.

Returns:

true if layout parameters for the input layout were stored in named properties of the grapher, false otherwise.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), IlvGraphLayoutGrapherProperty.transfer(ilog.views.graphlayout.IlvGraphLayout), IlvGraphLayoutNodeProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic), IlvGraphLayoutLinkProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic)

loadParametersFromNamedProperties

IlvGraphLayout loadParametersFromNamedProperties(String propertyPrefix)

Transfers the layout parameter settings from the named properties of the grapher back to a new layout instance. It returns the new layout instance that will be attached to this grapher adapter.

It searches for a set of layout parameter properties that has the property prefix string in the property name. If a corresponding set of properties is found, it creates a new layout instance that fits the layout properties, transfers the parameters to the new layout instance, and removes this set of named layout properties from the grapher.

This method can be used when the property prefix string is the full property name. However, it cannot be used if this grapher adapter was internally created during IlvGraphLayout.attach(IlvGrapher). It can only be used if this grapher adapter was explicitly allocated.

Note that the method throws a RuntimeException in the following cases:

• This grapher adapter was internally created during IlvGraphLayout.attach(IlvGrapher).
• If the new layout class cannot be located.
• If the new layout class represents an abstract class, an interface, an array class, a primitive type, or void; or if the instantiation fails for some other reason.
• If the new layout class or its initializer is not accessible.

Parameters:

propertyPrefix - The prefix of the unique property name that was used to store the layout properties.

Returns:

The new layout instance whose parameters are loaded successfully, and null if the parameters are not loaded.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), IlvGraphLayoutGrapherProperty.transfer(ilog.views.graphlayout.IlvGraphLayout), IlvGraphLayoutNodeProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic), IlvGraphLayoutLinkProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic)

loadPreferredLayoutsFromNamedProperties

boolean loadPreferredLayoutsFromNamedProperties(IlvDefaultLayoutProvider layoutProvider,
                                                boolean withParameters,
                                                boolean traverse)

Loads the preferred layout settings from the named properties of the grapher into an IlvDefaultLayoutProvider.

Notice that this method first calls the method IlvDefaultLayoutProvider.detachLayouts(ilog.views.graphlayout.IlvGraphModel, boolean) on layoutProvider, passing as arguments this adapter and traverse. This ensures that any layout instance that may have been previously specified as the preferred layout for layoutProvider gets removed from the provider and the corresponding graphs are detached from these layout instances.

Note that, if the layout instance is null, the method throws a RuntimeException in the following cases:

• If a preferred layout class cannot be located.
• If the preferred layout class represents an abstract class, an interface, an array class, a primitive type, or void; or if the instantiation fails for some other reason.
• If the preferred layout class or its initializer is not accessible.

Parameters:

layoutProvider - The layout provider into which the choices of the preferred layouts for each graph and subgraph are stored.

withParameters - If true, the parameters of the preferred layouts are also read (if any). If false, the preferred layout instance keeps its default settings.

traverse - If true, the method applies recursively to the subgraphs. Otherwise, the method applies only to this IlvGraphModel

Returns:

true if layout parameters for at least one of the input layout were loaded from named properties of the grapher, false otherwise.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), IlvGraphLayoutGrapherProperty.transfer(ilog.views.graphlayout.IlvGraphLayout), IlvGraphLayoutNodeProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic), IlvGraphLayoutLinkProperty.transfer(ilog.views.graphlayout.IlvGraphLayout, ilog.views.IlvGraphic), savePreferredLayoutsToNamedProperties(ilog.views.graphlayout.IlvDefaultLayoutProvider, boolean, boolean, boolean), IlvGraphLayout.PerformLayout(ilog.views.graphlayout.IlvGraphModel, ilog.views.graphlayout.IlvLayoutProvider, boolean, boolean, boolean), IlvGraphModel.performLayout(IlvLayoutProvider, boolean, boolean, boolean)

removeParametersFromNamedProperties

void removeParametersFromNamedProperties()

Removes all named properties that were used to store the graph layout parameter settings from the grapher.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), IlvGraphLayoutGrapherProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter), IlvGraphLayoutNodeProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter), IlvGraphLayoutLinkProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter)

removeParametersFromNamedProperties

void removeParametersFromNamedProperties(String propertyPrefix)

Removes the named properties that were used to store the graph layout parameter settings from the grapher. It removes only those layout properties that have the property prefix string in the property name.

This method can also be used when the property prefix string is the full property name.

Parameters:

propertyPrefix - The prefix of the unique property name that was used to store the layout properties.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), IlvGraphLayoutGrapherProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter), IlvGraphLayoutNodeProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter), IlvGraphLayoutLinkProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter)

removeParametersFromNamedProperties

void removeParametersFromNamedProperties(Class layoutClass)

Removes the named properties that were used to store the graph layout parameter settings from the grapher. It removes only those layout properties that fit the input layout class. For instance, if the input class is IlvTreeLayout, it removes all layout properties that are related to the Tree Layout.

Parameters:

layoutClass - The layout class.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), IlvGraphLayoutGrapherProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter), IlvGraphLayoutNodeProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter), IlvGraphLayoutLinkProperty.dispose(ilog.views.graphlayout.IlvGrapherPropertyAdapter)

setPreferredLayoutPropertyPrefix

void setPreferredLayoutPropertyPrefix(String propertyPrefix)

Sets the property name of the preferred layout. This can be used after the layout parameters were saved as named properties. Example:

 if (layout.supportsSaveParametersToNamedProperties()) {
   property = grapherParameterAdapter.saveParametersToNamedProperties(layout, false);
   grapherParameterAdapter.setPreferredLayoutPropertyPrefix(property);
 }
 ...
 grapherParameterAdapter.getGrapher().write("abcd.ivl");
 grapherParameterAdapter.removeParametersFromNamedProperties();
 

If the file is loaded and the parameters are transfered to a default layout provider later, it will take this layout as the preferred layout.

Parameters:

propertyPrefix - The prefix of the unique property name that was used to store the layout properties.

See Also:

getPreferredLayoutPropertyPrefix(), savePreferredLayoutsToNamedProperties(ilog.views.graphlayout.IlvDefaultLayoutProvider, boolean, boolean, boolean), loadPreferredLayoutsFromNamedProperties(ilog.views.graphlayout.IlvDefaultLayoutProvider, boolean, boolean)

getPreferredLayoutPropertyPrefix

String getPreferredLayoutPropertyPrefix()

Returns the property name of the preferred layout, or null if no preferred layout was stored.

See Also:

setPreferredLayoutPropertyPrefix(java.lang.String)

getLayoutPropertyPrefix

String getLayoutPropertyPrefix(IlvGraphLayout layout)

Returns the property name of the input layout, if it was most recently stored as a named property, or null if the layout was never stored.

This method can be used to retrieve the property name before loading the parameters into the layout instance in order to test whether the layout should be the preferred layout.

Parameters:

layout - The layout.

See Also:

saveParametersToNamedProperties(IlvGraphLayout, boolean), loadParametersFromNamedProperties(IlvGraphLayout), getPreferredLayoutPropertyPrefix()