FormLayout Class Reference

Provides access to a FormLayout which is referenced by a Repository or available as stand-alone FormLayout. More...

List of all members.

Public Member Functions
void	design (String designer, boolean showSplashScreen, boolean maximizeWindow, boolean useExistingInstance, String extraParameters) throws TFormerException
	Opens the FormLayout with TFORMer Designer.
void	dispose () throws TFormerException
	Releases the resources allocated by this instance.
void	dump (PrintStream s) throws IOException, TFormerException
	Dumps the current instance into a text stream.
String	getComment () throws TFormerException
	Gets the comment for the FormLayout.
DataFieldUsage	getDataFieldUsage (String dataFieldName) throws TFormerException
	Retrieves the usage of a specific DataField in a FormLayout.
String	getDescription () throws TFormerException
	Gets the description of the FormLayout.
String	getFileName () throws TFormerException
	Gets the filename of the FormLayout.
String	getName () throws TFormerException
	Gets the name of the FormLayout.
FormLayout	getNext () throws TFormerException
	Gets the next FormLayout in the Project.
void	setComment (String sComment) throws TFormerException
	Sets the comment for the FormLayout.
void	setDescription (String sDescription) throws TFormerException
	Sets the description of the FormLayout.
void	setFileName (String sFilename) throws TFormerException
	Sets the filename of the FormLayout.
void	setName (String sName) throws TFormerException
	Sets the name of the FormLayout.
String	toString ()
	Returns a string representation of the instance.

---

Detailed Description

Provides access to a FormLayout which is referenced by a Repository or available as stand-alone FormLayout.

Overview

A FormLayout is a document which was created with TFORMer Designer. This class is used to retrieve or set information belonging to a FormLayout.

A typical FormLayout contains static content (like a logo), dynamic content (like a DataField) and a number of properties which are used to describe the FormLayout and its behavior during print-time. Each FormLayout is member of exactly one Project (in the case of a Repository) or the GlobalProject (in the case of a stand-alone FormLayout).

Note:

It is not possible to change the appearance of the FormLayout (like adding new elements or bands) with this class. Design tasks are supported by TFORMer Designer only.

Repository-based FormLayouts

General

• Each FormLayout referenced from within a Repository is a member of exactly one Project.
• DataFields defined within a Project are only usable by FormLayouts which are member of this Project.
• The so-called GlobalProject is allocated by default and is exclusively used to define DataFields and DataSources which are available for all FormLayouts (regardless of their actual Project membership). It can not store references to a FormLayout.
• The Repository also stores JobTrayControl objects (see Job.setJobTrayControlName).
• A Repository uses the file extension *.tfr.

Printing

When printing a specific FormLayout within a Repository 3 parameters must be specified to identify the FormLayout:

• The Repository name (which is identical to the filename of the Repository, see Job.setRepositoryName)
• The Project name as defined by the user in TFORMer Designer (see Job.setProjectName)
• The FormLayout name as defined by the user in TFORMer Designer (see Job.setFormName)

Stand-Alone FormLayout

General

• A stand-alone FormLayout can be used on its own and can be imagined like a very simple type of Repository which contains exactly one Project (namely the GlobalProject).
• A stand-alone FormLayout stores the DataField definitions, JobTrayControl definitions, DataSource definitions as well as the FormLayout itself. It is not able to share DataField definitions with other FormLayouts and can not contain user-defined Project objects.
• A stand-alone FormLayout uses the file extension *.tff.

Printing

When printing a Job using a stand-alone FormLayout 1 parameter must be specified:

• The Repository name (which is identical to the filename of the stand-alone FormLayout, see Job.setRepositoryName)

Note:

Do not use Job.setProjectName and Job.setFormName when using a stand-alone FormLayout!

Determining Used DataFields

In order to access the data-fields in a FormLayout you may either use the method Project.getDataField or you may iterate through all available data-fields using Project.getFirstDataField and DataField.getNext. If you want to know, whether the returned DataField is actually used you can use the method FormLayout.getDataFieldUsage.

Sample

To retrieve the FormLayout object within a stand-alone FormLayout do the following:

  // Retrieve the global Project 
  // A stand-alone FormLayout contains only the global Project, the global Project contains the FormLayout
  Project project = repository.getGlobalProject ();

  if (project != null)
  {
    System.out.println (project.toString());

    // Retrieve the first (and only) FormLayout
    FormLayout formlayout = project.getFirstFormLayout ();
    if (formlayout != null)
    {
      System.out.println (formlayout.toString());
    }
  }

To retrieve all FormLayout objects within a Repository do the following:

  // Retrieve the first Project 
  Project project = repository.getFirstProject ();

  while (project != null)
  {
    System.out.println (project.toString());

    // Retrieve the first FormLayout in this Project
    FormLayout formlayout = project.getFirstFormLayout ();

    while (formlayout != null)
    {
      System.out.println (formlayout.toString());

      // Get the next FormLayout in this Project
      formlayout = formlayout.getNext ();
    }

    // Get the next Project
    project = project.getNext ();
  } 

Attention:

The FormLayout is only valid as long as it is available in the Project. If it is removed from the Project all instances of the FormLayout become invalid immediately.

Note:

Thread-safety: A single instance of this class must not be used by different threads.

---

Member Function Documentation

void design	(	String	designer,
		boolean	showSplashScreen,
		boolean	maximizeWindow,
		boolean	useExistingInstance,
		String	extraParameters
	)		throws TFormerException

Opens the FormLayout with TFORMer Designer.

TFORMer SDK on its own cannot be used for editing a FormLayout. Use this method to invoke TFORMer Designer.

Note:

Make sure that your purchased license model fits your requirements. If you are creating applications which are distributed to 3rd party you may need to redistribute TFORMer Designer as well.

Parameters:

designer	The path and name of the TFORMer Designer executable. If null then the method tries to find the executable automatically
showSplashScreen	If set to true the splash screen is shown
maximizeWindow	If set to true the TFORMer Designer windows is maximized
useExistingInstance	If set to true the form-layout will be opened in an already running TFORMer Designer instance
extraParameters	Additional parameters that will be passed to TFORMer Designer

void dispose

(

)

throws TFormerException

Releases the resources allocated by this instance.

Call this method in every case (even in case of exceptions) is this instance is not required anymore.

void dump

(

PrintStream

s

)

throws IOException, TFormerException

Dumps the current instance into a text stream.

Parameters:

s	Instance of the stream

String getComment

(

)

throws TFormerException

Gets the comment for the FormLayout.

Returns:

The comment for the FormLayout.

DataFieldUsage getDataFieldUsage

(

String

dataFieldName

)

throws TFormerException

Retrieves the usage of a specific DataField in a FormLayout.

Parameters:

dataFieldName

Name of the DataField to be queried

Returns:

A valid object instance or null

See also:

DataField

Sample: To query all DataField-objects within a stand-alone FormLayout refer to the code below. The same principle can be used for a Repository-based FormLayout.

  // Retrieve the global Project
  // A stand-alone FormLayout contains only the global Project, the global Project holds the FormLayout and all DataField definitions
  Project project = repository.getGlobalProject ();

  // Retrieve the one and only FormLayout within the stand-alone FormLayout
  FormLayout formlayout = project.getFirstFormLayout ();

  // Iterate all DataFields within the Project
  DataField datafield = project.getFirstDataField ();
  while (datafield != null)
  {
    System.out.println (datafield.toString());

    // Retrieve the usage of the DataFields in the FormLayout
    switch (formlayout.getDataFieldUsage (datafield.getName ()))
    {
      case Calculated: System.out.println  ("--> The value of this DataField is computed within the FormLayout"); break;
      case Invalid   : System.out.println  ("--> Invalid usage - contact TEC-IT"); break;
      case Normal    : System.out.println  ("--> The DataField is used within the FormLayout; its value can be set"); break;
      case NotUsed   : System.out.println  ("--> This DataField is not used in this FormLayout"); break;
      case Parameter : System.out.println  ("--> This is a system DataField (like the page number) used within the FormLayout"); break;
    }
    
    datafield = datafield.getNext ();
  }

String getDescription

(

)

throws TFormerException

Gets the description of the FormLayout.

Returns:

The description of the FormLayout.

String getFileName

(

)

throws TFormerException

Gets the filename of the FormLayout.

Returns:

The filename of the FormLayout

String getName

(

)

throws TFormerException

Gets the name of the FormLayout.

Returns:

The name of the FormLayout

FormLayout getNext

(

)

throws TFormerException

Gets the next FormLayout in the Project.

To retrieve the first FormLayout within a Project (or the GlobalProject) refer to Project.getFirstFormLayout. When using a stand-alone FormLayout this property always returns null. In this case only one FormLayout is available - it can be retrieved via Repository.getGlobalProject.

Returns:

The next FormLayout object available or null.

See also:

Project

void setComment

(

String

sComment

)

throws TFormerException

Sets the comment for the FormLayout.

Parameters:

sComment

The comment for the FormLayout

void setDescription

(

String

sDescription

)

throws TFormerException

Sets the description of the FormLayout.

Parameters:

sDescription

The description of the FormLayout

void setFileName

(

String

sFilename

)

throws TFormerException

Sets the filename of the FormLayout.

Parameters:

sFilename

The filename of the FormLayout

void setName

(

String

sName

)

throws TFormerException

Sets the name of the FormLayout.

Parameters:

sName

The name of the FormLayout

String toString

(

)

Returns a string representation of the instance.

Returns:

A string representation of the instance