Main Index : Reference :

Filename

Description

Definition

class Filename
{
public:
  Filename();

  [bool] FileSelect([string] title, [bool] save);
  [bool] PathSelect([string] title);

  [bool] AddLast([string] name);
  [bool] RemoveLast();

  [bool] SetSuffix([string] suffix);
  [bool] DelSuffix();
  [bool] CheckSuffix([string] suffix);
  
  [string] GetFullString();
  [string] GetLastString();
  [bool] SetFullString([string] path);
  [bool] SetLastString([string] name);

  [bool] IsEmpty();
  [bool] IsEQ([Filename] f);
  [bool] IsNE([Filename] f);

  [bool] CopyTo([Filename] dest);
  [Filename] GetClone();
}

Explanation

Normally one would specify a filename by just using a string. However, in C4D this is not a good idea since the program, and also the plugins, should be platform independent. For example on the PC there is something like "C:\temp\test.txt" and on the mac "-12367:2313:test.txt".

For this reason there is a special filename class handling these problems. When using the filename class one doesn't have to deal with different system seperators like "\" or ":" and can also be sure that one's plugins will work on future platforms.

Members

FileSelect( title, save )

Opens the standard file navigation dialog of the OS. The message to the user is specified by the string title. Whether it is an open dialog or a save dialog depends on the save parameter. The difference, besides what the button in the dialog says, is that a save dialog will warn the user if he selects an existing file. If the user has selected a file and everything is OK the function returns TRUE. Otherwise, for example if the user chooses Cancel, the function returns FALSE.

The selected file's path is stored in the filename object.

PathSelect( title )

Opens the standard dialog of the OS for selecting directories. The message to the user is specified by the string title. If the user has selected a directory and everything is OK the function returns TRUE. Otherwise, for example if the user chooses Cancel, the function returns FALSE.

The selected directory's path is stored in the filename object.

AddLast( name )

The string name is added to the internal path. This can be either a directory or a file name. Returns TRUE if successful. For example, this code will refer to the file "Earth.tif" in the folder "tex" inside the CINEMA 4D folder:

var filename = GeGetStartupPath();
filename->AddLast("tex");
filename->AddLast("Earth.tif");

RemoveLast()

The last item is removed from the internal path. If the highest level has been reached, the function returns FALSE. Otherwise it returns TRUE. Therefore one can use the following code to get to the root level of the harddrive that C4D is on:

var filename = GeGetStartupPath();
while (filename->RemoveLast()); 

SetSuffix( suffix )

Adds the specified suffix to the last item of the path. Removes any existing suffix. For example, this code gives the file name "Earth.tif":

filename->Add("Earth"); 
filename->SetSuffix("tif");

Returns TRUE if successful.

DelSuffix()

Removes the suffix from the last item of the path. Returns TRUE if successful.

CheckSuffix( suffix )

Returns TRUE if the last item of the path has the specified suffix. Otherwise returns FALSE.

GetFullString()

Returns the current path as an OS specific string. This can be used to, for example, show the user what file he has chosen.

GetLastString()

Returns the last item of the path as a string.

SetFullString( path )

Sets the internal path from the OS specific string path. Returns TRUE if successful.

Remember: Don't use this function to hardcode or store any platform specific paths directly. That will always break the plugin on other platforms. Only use it during runtime to let the user modify strings that you have got from GetFullString(), or possibly to let the user type in a path manually.

SetLastString( name )

Sets the last item of the path to the string name. Returns TRUE if successful.

IsEmpty()

Returns TRUE if the path is empty.

IsEQ( f )

Returns TRUE if the path is equal to the path of the filename f.

IsNE( f )

Returns TRUE if the path is not equal to the path of the filename f.

CopyTo( dest )

Copies the filename to the specified destination. Returns TRUE if successful.

GetClone()

Returns a clone of the filename object.

Example

// Lets the user select a file
var filename = GeGetStartupPath();
filename->FileSelect("Please select a file.", FALSE);

// Selects a file in the current plugin directory
var filename = GetGetRootFilename();
filename->RemoveLast(); // Remove the name of the plugin
filename->Add("foo.txt"); // The name of the file