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, bool showSplashScreen, bool maximizeWindow, bool useExistingInstance, string extraParameters)
	Opens the FormLayout with TFORMer Designer.
void	Dispose ()
	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
DataFieldUsage	GetDataFieldUsage (string dataFieldName)
	Retrieves the usage of a specific DataField in a FormLayout.
override string	ToString ()
	Returns a string representation of the instance.
Properties
string	Comment [get, set]
	Gets/Sets the comment for the FormLayout.
string	Description [get, set]
	Gets/Sets the description of the FormLayout.
string	Filename [get, set]
	Gets/Sets the filename of the FormLayout.
string	Name [get, set]
	Gets/Sets the name of the FormLayout.
FormLayout	Next [get]
	Gets the next FormLayout in the Project.

---

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.JobTrayControlName).
• 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.RepositoryName)
• The Project name as defined by the user in TFORMer Designer (see Job.ProjectName)
• The FormLayout name as defined by the user in TFORMer Designer (see Job.FormName)

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.RepositoryName)

Note:

Do not use Job.ProjectName and Job.FormName 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.FirstDataField and DataField.Next. 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.GlobalProject;

  if (project != null)
  {
    Console.Write(project.ToString());

    // Retrieve the first (and only) FormLayout
    FormLayout formlayout = project.FirstFormLayout;
    if (formlayout != null)
    {
      Console.Write(formlayout.ToString());
    }
  }

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

  // Retrieve the first Project 
  Project project = repository.FirstProject;

  while (project != null)
  {
    Console.Write(project.ToString());

    // Retrieve the first FormLayout in this Project
    FormLayout formlayout = project.FirstFormLayout;

    while (formlayout != null)
    {
      Console.Write(formlayout.ToString());

      // Get the next FormLayout in this Project
      formlayout = formlayout.Next;
    }

    // Get the next Project
    project = project.Next;
  } 

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,
		bool	showSplashScreen,
		bool	maximizeWindow,
		bool	useExistingInstance,
		string	extraParameters
	)

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

(

)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

DataFieldUsage GetDataFieldUsage

(

string

dataFieldName

)

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.GlobalProject;

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

  // Iterate all DataFields within the Project
  DataField datafield = project.FirstDataField;
  while (datafield != null)
  {
    Console.Write(datafield.ToString());

    // Retrieve the usage of the DataFields in the FormLayout
    switch (formlayout.GetDataFieldUsage (datafield.Name))
    {
      case DataFieldUsage.Calculated: Console.Write ("--> The value of this DataField is computed within the FormLayout"); break;
      case DataFieldUsage.Invalid   : Console.Write ("--> Invalid usage - contact TEC-IT"); break;
      case DataFieldUsage.Normal    : Console.Write ("--> The DataField is used within the FormLayout; its value can be set"); break;
      case DataFieldUsage.NotUsed   : Console.Write ("--> This DataField is not used in this FormLayout"); break;
      case DataFieldUsage.Parameter : Console.Write ("--> This is a system DataField (like the page number) used within the FormLayout"); break;
    }
    Console.WriteLine();
    datafield = datafield.Next;
  }

override string ToString

(

)

Returns a string representation of the instance.

Returns:

A string representation of the instance

---

Property Documentation

string Comment [get, set]

Gets/Sets the comment for the FormLayout.

Returns:

The comment for the FormLayout.

string Description [get, set]

Gets/Sets the description of the FormLayout.

Returns:

The description of the FormLayout.

string Filename [get, set]

Gets/Sets the filename of the FormLayout.

Returns:

The filename of the FormLayout.

string Name [get, set]

Gets/Sets the name of the FormLayout.

Returns:

The name of the FormLayout.

FormLayout Next [get]

Gets the next FormLayout in the Project.

To retrieve the first FormLayout within a Project (or the GlobalProject) refer to Project.FirstFormLayout. 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.GlobalProject.

Returns:

The next FormLayout object available or null.

See also:

Project