Layouts

Functions
Boolean_t	TecUtilNewLayout (void)
	Delete all frames and data sets (clear the current layout).
Boolean_t	TecUtilOpenLayout (const char *FName, StringList_pa AltInstructions, Boolean_t Append)
	Open and read in a new layout file.
Boolean_t	TecUtilOpenLayoutX (ArgList_pa ArgList)
	Open and read in a new layout file.
Boolean_t	TecUtilSaveLayout (const char *FName, Boolean_t UseRelativePaths)
	Save the current layout to a file.
Boolean_t	TecUtilSaveLayoutX (ArgList_pa ArgList)
	Save the current layout to a file.
Boolean_t	TecUtilDataSetAddJournalCommand (const char *CommandProcessorIDString, const char *Instructions, const char *RawData)
	Adds a command to the data journal.
Boolean_t	TecUtilDataSetAddRawJournalCom (const char *Command)
	Adds a raw macro command to the data journal.
char *	TecUtilGetCurLayoutFName (void)
	Get the current layout file name.
Boolean_t	TecUtilStateIsProcessingJournal (void)
	Query Tecplot to find out if Tecplot is in the middle of processing the data journal.
Boolean_t	TecUtilStateIsProcessingLayout (void)
	Query Tecplot to find out if Tecplot is in the middle of processing a layout.

---

Function Documentation

Boolean_t TecUtilDataSetAddJournalCommand	(	const char *	CommandProcessorIDString,
		const char *	Instructions,
		const char *	RawData
	)

Adds a command to the data journal.

Note:

Using this function will render your layout files incompatibile with Tecplot 11.2-0-382 or earlier.

Parameters:

	CommandProcessorIDString	The ID string of the command processor. You must have registered a macro command callback with Tecplot to use this functionality. See TecUtilMacroAddCommandCallback for more information on registering a macro command callback
	Instructions	Command Instrunctions
	RawData	Raw Data. Please see TecUtilMacroRecordExtComRaw() for a description of the raw data format.

Returns:

Returns TRUE if successful, FALSE otherwise.

Precondition:

CommandProcessorIDString String must have a valid address and non-zero length.

Instructions String must have a valid address and non-zero length.

RawData Pointer must be a valid address or NULL.

Must have one or more frames.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilDataSetAddJournalCommand(
   &                   AddOnIDString,
   &                   Instructions,
   &                   RawData)
    CHARACTER*(*)   AddOnIDString
    CHARACTER*(*)   Instructions
    CHARACTER*(*)   RawData

Python Syntax:

  Results = TecUtil.DataSetAddJournalCommand(CommandProcessorIDString, Instructions, RawData)

  Input:
                  CommandProcessorIDString string
                  Instructions         string
                  RawData              string
  Output:
    Results[0]    ReturnVal            boolean

See also:

TecUtilMacroAddCommandCallback, TecUtilMacroRecordExtComRaw

Boolean_t TecUtilDataSetAddRawJournalCom

(

const char *

Command

)

Adds a raw macro command to the data journal.

Parameters:

Command

The raw macro command to add to the journal.

Returns:

Returns TRUE if successful (i.e., the command is valid and could be attached to the journal), FALSE otherwise.

Precondition:

Command String must have a valid address and non-zero length.

Must have one or more frames.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilDataSetAddRawJournalCom(Command)
    CHARACTER*(*) Command

Python Syntax:

  Results = TecUtil.DataSetAddRawJournalCom(Command)

  Input:
                  Command              string
  Output:
    Results[0]    ReturnVal            boolean

char* TecUtilGetCurLayoutFName

(

void

)

Get the current layout file name.

Returns:

The current layout file name including the path. You must call TecUtilStringDealloc() on the returned string.

Precondition:

IMPLICATION(LayoutFName != NULL,VALID_REF(LayoutFName)) Pointer must be a valid address or NULL.

Fortran Syntax:

    SUBROUTINE TecUtilGetCurLayoutFName(
   &           Result,
   &           ResultLength)
    CHARACTER*(*)   Result
    INTEGER*4       ResultLength

Python Syntax:

  Results = TecUtil.GetCurLayoutFName()

  Output:
    Results[0]    ReturnVal            string

Boolean_t TecUtilNewLayout

(

void

)

Delete all frames and data sets (clear the current layout).

A blank default frame will be created for you.

Returns:

Currently, TRUE is always returned.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilNewLayout()

Python Syntax:

  Results = TecUtil.NewLayout()

  Output:
    Results[0]    ReturnVal            boolean

Clear the current layout:

   Boolean_t IsOk = TecUtilNewLayout();

Boolean_t TecUtilOpenLayout	(	const char *	FName,
		StringList_pa	AltInstructions,
		Boolean_t	Append
	)

Open and read in a new layout file.

Parameters:

	FName	The name of the layout file to open. This should be the full path to the layout file. If the full path is not specified, any relative paths in your layout may not be correctly resolved.
	AltInstructions	Alternate instructions for the layout file. In most cases, this will be a string list containing file names which will override the data files listed in the layout file. Use NULL to load the data referenced in the layout file
	Append	TRUE to append the new layout file to the current layout or FALSE to replace the current layout

Returns:

TRUE if successfull, FALSE otherwise.

Precondition:

FName String must have a valid address and non-zero length.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilOpenLayout(
   &                   FName,
   &                   AltInstructionsPtr,
   &                   Append)
    CHARACTER*(*)   FName
    POINTER         (AltInstructionsPtr, AltInstructions)
    INTEGER*4       Append

Python Syntax:

  Results = TecUtil.OpenLayout(FName, AltInstructions, Append)

  Input:
                  FName                string
                  AltInstructions      sequence of strings
                  Append               boolean
  Output:
    Results[0]    ReturnVal            boolean

Open a layout file called "experiment.lay." Then, append a layout called "calculate.lay," overriding the first data file referenced in that layout with a file called "newdata.plt":

   StringList_pa AltInst = TecUtilStringListAlloc();
   TecUtilStringListAppendString(AltInst, "newdata.plt");
   TecUtilOpenLayout("C:\\experiment.lay", (StringList_pa)NULL, FALSE);
   TecUtilOpenLayout("C:\\calculate.lay", AltInst, TRUE);
   TecUtilStringListDealloc(&AltInst);

Boolean_t TecUtilOpenLayoutX

(

ArgList_pa

ArgList

)

Open and read in a new layout file.

Since:

11.3.29.396

Parameters:

ArgList

Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions. Arglist Values SV_FNAME Type: char * Arg Function: TecUtilArgListAppendString() Required: Yes Notes: The name of the layout file to open. This should be the full path to the layout file. If the full path is not specified, any relative paths in your layout may not be correctly resolved. The file name reference need not be allocated however the string must not be deallocated until it is no longer referenced by the argument list. SV_ALTINSTRUCTIONS Type: StringList_pa Arg Function: TecUtilArgListAppendStringList() Default: NULL Required: No Notes: Alternate instructions for the layout file. In most cases, this will be a string list containing file names which will override the data files listed in the layout file. Use NULL to load the data referenced in the layout file. SV_APPEND Type: Boolean_t Arg Function: TecUtilArgListAppendInt() Default: FALSE Required: No Notes: TRUE to append the new layout file to the current layout or FALSE to replace the current layout. SV_APPENDTOCURPAGE Type: Boolean_t Arg Function: TecUtilArgListAppendInt() Default: TRUE Required: No Notes: When appending a value of TRUE tells Tecplot to append the layout to the contents of the current page while a value of FALSE instructs Tecplot to append the layout to a new page.

Returns:

TRUE if successful, FALSE otherwise.

Precondition:

ArgList Argument list must be valid.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilSaveLayoutX(ArgListPtr)
    POINTER (ArgListPtr, ArgList)

Python Syntax:

  Results = TecUtil.OpenLayoutX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            boolean

Open a layout file called "experiment.lay." Then, append a layout called "calculate.lay," overriding the first data file referenced in that layout with a file called "newdata.plt":

   TecUtilArgListClear(ArgList);
   TecUtilArgListAppendString(ArgList, SV_FNAME, "C:\\experiment.lay");
   TecUtilOpenLayoutX(ArgList);

   StringList_pa AltInst = TecUtilStringListAlloc();
   TecUtilStringListAppendString(AltInst, "newdata.plt");

   TecUtilArgListClear(ArgList);
   TecUtilArgListAppendString(ArgList,     SV_FNAME,           "C:\\calculate.lay");
   TecUtilArgListAppendStringList(ArgList, SV_ALTINSTRUCTIONS, AltInst);
   TecUtilArgListAppendInt(ArgList,        SV_APPEND,          TRUE);
   TecUtilOpenLayoutX(ArgList);

   TecUtilStringListDealloc(&AltInst);
   ...

Boolean_t TecUtilSaveLayout	(	const char *	FName,
		Boolean_t	UseRelativePaths
	)

Save the current layout to a file.

You must supply the file name.

Parameters:

	FName	The name of the layout file to save
	UseRelativePaths	Set to TRUE to make all of the files referenced by the layout file use paths relative to the current directory. Set to FALSE to make all of the files referenced by absolute paths

Returns:

TRUE if the current layout was saved, FALSE otherwise.

Precondition:

Must have one or more pages.

FName String must have a valid address and non-zero length.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilSaveLayout(
   &                   FName,
   &                   UseRelativePaths)
    CHARACTER*(*)   FName
    INTEGER*4       UseRelativePaths

Python Syntax:

  Results = TecUtil.SaveLayout(FName, UseRelativePaths)

  Input:
                  FName                string
                  UseRelativePaths     boolean
  Output:
    Results[0]    ReturnVal            boolean

Save a layout file called temp.lay, using absolute paths:

   Boolean_t IsOk = TecUtilSaveLayout("temp.lay", FALSE);

Boolean_t TecUtilSaveLayoutX

(

ArgList_pa

ArgList

)

Save the current layout to a file.

Parameters:

ArgList

Set of Arglist entries. This is built using calls to TecUtilArgListAppendXXXX functions. Arglist Values SV_FNAME Type: char * Arg Function: TecUtilArgListAppendString() Required: Yes Notes: Associated value is the file name of the file in which to save the layout. The file name must be a reference to a non-NULL string who's length is greater than zero. The file name reference need not be allocated however the string must not be deallocated until it is no longer referenced by the argument list. SV_INCLUDEDATA Type: Boolean_t Arg Function: TecUtilArgListAppendInt() Default: FALSE Required: No Notes: Associated value indicates if the layout should be saved as a layout package where the data is included with the style information or if it should reference linked data SV_INCLUDEPREVIEW Type: Boolean_t Arg Function: TecUtilArgListAppendInt() Default: TRUE Required: No Notes: Associated value indicates if the layout package should also include a preview image. This argument only applies if the include data option is TRUE SV_USERELATIVEPATHS Type: Boolean_t Arg Function: TecUtilArgListAppendInt() Default: FALSE Required: No Notes: Associated value indicates if the layout should be saved using relative paths. This argument only applies if the include data option is FALSE. SV_POSTLAYOUTCOMMANDS Type: char * Arg Function: TecUtilArgListAppendString() Default: NULL Required: No Notes: A character string containing a set of Tecplot macro commands that are appended to the layout or layout package file. These can be almost anything and are generally used to store add-on specific state information (using $!EXTENDEDCOMMAND commands). SV_PAGELIST Type: Set_pa Arg Function: TecUtilArgListAppendSet() Default: NULL Required: No Notes: If NULL all pages are written to the layout otherwise the specified subset of pages are written. The set contains the 1 based page positions relative to the current page where the current page has a position value of 1, the next page 2, the page after that 3, and so on. See example below.

Returns:

TRUE if successful, FALSE otherwise.

Precondition:

Must have one or more pages.

ArgList Argument list must be valid.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilSaveLayoutX(ArgListPtr)
    POINTER (ArgListPtr, ArgList)

Python Syntax:

  Results = TecUtil.SaveLayoutX(ArgList)

  Input:
                  ArgList              dictionary
  Output:
    Results[0]    ReturnVal            boolean

Save a layout package named temp.lpk, without a preview image:

   TecUtilArgListClear(ArgList);
   TecUtilArgListAppendString(ArgList, SV_FNAME,   "temp.lpk");
   TecUtilArgListAppendInt(ArgList,    SV_INCLUDEDATA,    TRUE);
   TecUtilArgListAppendInt(ArgList,    SV_INCLUDEPREVIEW, FALSE);
   IsOk = TecUtilSaveLayoutX(ArgList);

Save a layout named temp.lay using relative path names:

   TecUtilArgListClear(ArgList);
   TecUtilArgListAppendString(ArgList, SV_FNAME,  "temp.lay");
   TecUtilArgListAppendInt(ArgList,    SV_USERELATIVEPATHS, TRUE);
   IsOk = TecUtilSaveLayoutX(ArgList);

Assume that we have a layout consisting of half a dozen pages all identified by their unique page IDs. Save a partial layout containing only a sub-set of the layout's pages. In this example we assume My2DPlotPageID and My3DPlotPageID where acquired by earlier calls to TecUtilPageGetUniqueID().

   Set_pa PageList = TecUtilSetAlloc(FALSE);
   TecUtilSetAddMember(PageList, TecUtilPageGetPosByUniqueID(My2DPlotPageID)), FALSE);
   TecUtilSetAddMember(PageList, TecUtilPageGetPosByUniqueID(My3DPlotPageID)), FALSE);

   ArgList_pa ArgList = TecUtilArgListAlloc();
   TecUtilArgListAppendString(ArgList, SV_FNAME,  "partial.lay");
   TecUtilArgListAppendInt(ArgList,    SV_USERELATIVEPATHS, TRUE);
   TecUtilArgListAppendSet(ArgList,    SV_PAGELIST, PageList);
   IsOk = TecUtilSaveLayoutX(ArgList);

   TecUtilArgListDealloc(&ArgList);
   TecUtilSetDealloc(&PageList);

Boolean_t TecUtilStateIsProcessingJournal

(

void

)

Query Tecplot to find out if Tecplot is in the middle of processing the data journal.

This function is Thread Safe.

Returns:

Returns TRUE if Tecplot is processing the data journal, otherwise FALSE.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilStateIsProcessingJournal()

Python Syntax:

  Results = TecUtil.StateIsProcessingJournal()

  Output:
    Results[0]    ReturnVal            boolean

Boolean_t TecUtilStateIsProcessingLayout

(

void

)

Query Tecplot to find out if Tecplot is in the middle of processing a layout.

This function is Thread Safe.

Returns:

Returns TRUE if Tecplot is processing a layout, otherwise FALSE.

Fortran Syntax:

    INTEGER*4 FUNCTION TecUtilStateIsProcessingLayout()

Python Syntax:

  Results = TecUtil.StateIsProcessingLayout()

  Output:
    Results[0]    ReturnVal            boolean