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 TFormer_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 TFormer_SetRepositoryName)
• The Project name as defined by the user in TFORMer Designer (see TFormer_SetProjectName)
• The FormLayout name as defined by the user in TFORMer Designer (see TFormer_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 TFormer_SetRepositoryName)

Note:

Do not use TFormer_SetProjectName and TFormer_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 TFormer_GetFirstProjectVarIt or you may iterate through all available data-fields using TFormer_GetFirstProjectVarIt and TFormer_GetNextProjectVarIt. If you want to know, whether the returned DataField is actually used you can use the method TFormer_ProjectVarItGetUsage.

Sample

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

  ERRCODE         eCode             = ErrOk;
  HFORM_ITERATOR  itForm            = NULL;
  LPCSTR          pszFormDescription= NULL;
  BOOL            bFormValid        = FALSE;

  // Retrieve first form of the global Project   
  // A stand-alone FormLayout contains only the global Project, the global Project contains the FormLayout  
  LPCSTR          pszProjectName    = NULL; // use global project

  // Retrieve the first (and only) FormLayout
  itForm      = TFormer_GetFirstFormIt (hTForm, pszProjectName, &eCode);
  bFormValid  = (itForm != NULL);

  if (bFormValid && eCode == ErrOk)
  {
    pszFormDescription = TFormer_FormItGetDescription (itForm, &eCode);
    printf ("description: ");
    if (pszFormDescription != NULL && eCode == ErrOk)
      printf (pszFormDescription);
    printf ("\n");
  }    

  // release iterator
  TFormer_FreeFormIt (itForm);

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

  ERRCODE           eCode           = ErrOk;
  HPROJECT_ITERATOR itProject       = NULL;
  BOOL              bProjectValid   = FALSE;
  LPCSTR            pszProjectName  = NULL;
  HFORM_ITERATOR    itForm          = NULL;
  BOOL              bFormValid      = FALSE;
  LPCSTR            pszFormName     = NULL;    

  // Retrieve the first Project 
  itProject     = TFormer_GetFirstProjectIt (hTForm, &eCode);  
  bProjectValid = (itProject != NULL);

  // TYPE_E_ELEMENTNOTFOUND should not be treated as error
  if (eCode == TYPE_E_ELEMENTNOTFOUND)
    eCode = ErrOk;

  while (bProjectValid && eCode == ErrOk)
  {
    pszProjectName = TFormer_ProjectItGetName (itProject, &eCode);

    if (pszProjectName != NULL && eCode == ErrOk)
    {
      printf ("project name: '%s'\n", pszProjectName);

      itForm    = TFormer_GetFirstFormIt (hTForm, pszProjectName, &eCode);
      bFormValid= (itForm != NULL);

      // TYPE_E_ELEMENTNOTFOUND should not be treated as error
      if (eCode == TYPE_E_ELEMENTNOTFOUND)
        eCode = ErrOk;

      while (bFormValid && eCode == ErrOk)
      {
        pszFormName = TFormer_FormItGetName (itForm, &eCode);
    
        if (pszFormName != NULL && eCode == ErrOk)
          printf ("  form name: '%s'\n", pszFormName);

        // Get the next FormLayout in this Project
        bFormValid = (TFormer_GetNextFormIt (itForm) == ErrOk);
      }

      TFormer_FreeFormIt (itForm);
    }

    // Get the next Project
    bProjectValid = (TFormer_GetNextProjectIt (itProject) == ErrOk);
  }

  TFormer_FreeProjectIt (itProject);