Filename Manual

Table of Contents

• About
• Access
• Combine
• Copy
• Properties
  • String
  • File and Directory
  • Suffix
  • Memory Mode
• Functionality
  • Select Files and Folders
  • Preset Browser
• Compare
• Disc I/O
• Further Reading

About

Filename is a special class to handle filenames and paths. It is used to easily construct and edit paths, filenames and suffixes. It also allows to open dialogs to select files and directories.

Warning

To handle files with the MAXON API see also Url Manual.

Note

To convert a Filname to a maxon::Url use MaxonConvert().

Access

Filename objects can be created on demand or can be obtained from other entities.

To retrieve and modify Filename objects stored in a BaseContainer respectively use:

• BaseContainer::GetFilename(): Returns the Filename stored at the given ID.
• BaseContainer::SetFilename(): Sets the Filename stored at the given ID.

See also BaseContainer Manual.

To retrieve and modify Filename objects stored in a GeData object (GeData type is DA_FILENAME) respectively use:

• GeData::GetFilename(): Returns the Filename object.
• GeData::SetFilename(): Stores the Filename object.

See also GeData Manual.

Important paths are obtained from:

• GeGetStartupApplication(): Returns the complete path of the host application.
• GeGetStartupWritePath(): Returns the writeable startup directory.
• GeGetPluginPath(): Returns the path for a plugin's main folder.
• GeGetPluginResourcePath(): Returns the resource path for a plugin's main folder.
• GeGetC4DPath(): Returns one of the Cinema 4D paths.

  // This example reads the filename parameter of an alembic generator.
 
  // check if the active object is an "Alembic Generator"
  BaseObject* const object = doc->GetActiveObject();
  if (object == nullptr && object->GetType() != Oalembicgenerator)
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  GeData data;
 
  // read the "Path to Alembic file" parameter
  if (!object->GetParameter(ConstDescID(DescLevel(ALEMBIC_PATH)), data, DESCFLAGS_GET::NONE))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  ApplicationOutput("Alembic File: " + data.GetFilename().GetString());

Combine

A Filename can be constructed with basic operators:

• Filename::operator+(): Concatenates the two filenames.
• Filename::operator+=(): Concatenates the filenames and set the left-hand operand to the result.

Note

Only the last part (typically the file) of the given Filename is added.

  // This example lets the user select a folder.
  // A full file path is constructed and the example checks if that file exists.
 
  Filename selectFolder;
 
  // open a folder selector dialog
  if (!selectFolder.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Select Folder"_s))
    return maxon::OK;
 
  const Filename fullFilePath = selectFolder + "cube.c4d";
 
  // check if given file exists
  if (GeFExist(fullFilePath))
    ApplicationOutput("The folder contains \"cube.c4d\"");
  else
    ApplicationOutput("The folder does not container \"cube.c4d\"");

  // This example constructs the Filename for an image file
  // in the plugin's "res" folder and loads this image.
 
  // construct full file name
  const Filename imageFile = GeGetPluginPath() + Filename("res") + Filename("arbitrary_icon.tif");
 
  // check if the file exists
  if (!GeFExist(imageFile))
    return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
 
  AutoAlloc<BaseBitmap> bitmap;
  if (bitmap == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // load image file into the given BaseBitmap
  if (bitmap->Init(imageFile) != IMAGERESULT::OK)
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  // show BaseBitmap in the Picture Viewer
  ShowBitmap(bitmap);

Copy

A Filename object can easily be copied:

• Filename::operator=(): Assigns the right-operand filename to the left-operand filename.
• Filename::CopyTo(): Copies the filename into the given Filename object.

Properties

String

The content of a Filename object can be represented by a String:

• Filename::IsPopulated(): Returns true if the filename has been set.
• Filename::GetString(): Returns the full filename as a String.
• Filename::SetString(): Sets the filename with the given String.

See also String Manual (Classic).

  // This example prints the full path to the console.
 
  const String filenameString = selectedFile.GetString();
  ApplicationOutput("File selected: " + filenameString);

File and Directory

A filename may be composed of a directory part and a file part. Each part can be edited independently:

• Filename::GetDirectory(): Returns the directory of the filename.
• Filename::SetDirectory(): Sets the directory of the filename.
• Filename::GetFile(): Returns the file part of the filename.
• Filename::SetFile(): Sets the file part of the filename.
• Filename::GetFileString(): Returns the file part of the filename as a String.

  // This example prints the file and the directory to the console.
 
  const String file = selectedFile.GetFileString();
  const String directory = selectedFile.GetDirectory().GetString();
 
  ApplicationOutput(directory + " - " + file);

Suffix

Part of the filename may also be the file suffix. This suffix can be edited separately:

• Filename::GetSuffix(): Returns the suffix as a String.
• Filename::SetSuffix(): Sets the suffix to the given string.
• Filename::ClearSuffix(): Clears the suffix.
• Filename::ClearSuffixComplete(): Clears also suffixes longer than seven characters.
• Filename::CheckSuffix(): Checks if the suffix is equal to the given string.

  // This example checks the suffix of the given filename.
 
  // check if the given Filename references a Cinema 4D scene file
  if (selectedFile.CheckSuffix("c4d"_s))
    ApplicationOutput("C4D File");
  else
    ApplicationOutput("Some other file");

It is possible to get the suffix for a given image file type:

• GeFilterSetSuffix(): Sets the standard suffix of a given bitmap saver plugin.

  // This example adds the correct suffix to the given Filename object
  // based on the image file type.
 
  imageFileName = GeFilterSetSuffix(imageFileName, FILTER_JPG);
  bitmap->Save(imageFileName, FILTER_JPG, nullptr, SAVEBIT::NONE);

Memory Mode

The memory mode allows to perform read and write operations on a memory block instead of a file on the hard drive. This is typically used to encrypt or compress the resulting data.

• Filename::SetMemoryReadMode(): Sets the filename to read from a memory block.
• Filename::SetMemoryWriteMode(): Sets the filename to write to a memory block.

  // This example writes some data into memory and accesses the raw memory afterwards.
 
  AutoAlloc<MemoryFileStruct> mfs;
  if (mfs == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  Filename fn;
  fn.SetMemoryWriteMode(mfs);
 
  void* data = nullptr;
  Int   size = 0;
 
  // open HyperFile to write
  if (!hyperFile->Open(0, fn, FILEOPEN::WRITE, FILEDIALOG::NONE))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  hyperFile->WriteInt32(123);
  hyperFile->WriteString("foo"_s);
  hyperFile->WriteString("bar"_s);
  hyperFile->WriteInt32(456);
  hyperFile->Close();
 
  // get raw data
  mfs->GetData(data, size, false);
 

Note

The data stored in memory may be written to a file using HyperFile::WriteMemory().

Functionality

Select Files and Folders

A Filename object is also useful to open dialogs to select files and folders:

• Filename::FileSelect(): Opens a dialog to select a file or a folder.
• Filename::FileSelectMultiple(): Opens a dialog to select multiple files or folders.

The files that can be selected in a dialog can be filtered with these flags:

• FILESELECTTYPE::ANYTHING : Allow any file.
• FILESELECTTYPE::IMAGES : Allow only image files.
• FILESELECTTYPE::SCENES : Allow only 3D scene files.
• FILESELECTTYPE::BODYPAINT : Allow only BodyPaint 3D files.

The type of dialog is defined with this flag:

• FILESELECT::LOAD : Opens a "Load" dialog.
• FILESELECT::SAVE : Opens a "Save" dialog.
• FILESELECT::DIRECTORY : Opens a folder selections dialog.

  // This example shows how to select a file for loading, saving and a folder.
 
  Filename loadFile;
 
  // open a file selector dialog to open a file
  if (loadFile.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::LOAD, "Load File"_s))
    ApplicationOutput("File to load: " + loadFile.GetString());
 
  Filename saveFile;
 
  // open a file selector dialog to save a file
  if (saveFile.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::SAVE, "Save File"_s))
    ApplicationOutput("File to save: " + saveFile.GetString());
 
  Filename folder;
 
  // open a folder selector dialog
  if (folder.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Select Folder"_s))
    ApplicationOutput("Folder: " + folder.GetString());

  // Demonstrates the selection of multiple files with Filename::FileSelectMultiple().
 
  iferr_scope;
 
  // The dialog title and the starting url.
  const maxon::String dialogTitle("Select multiple files");
  const maxon::Url startUrl;
 
  // A maxon::Id can be passed to identify the window instance for storing its properties (size, 
  // position, etc.). When this is not required, the empty id, maxon::Id(), can be passed instead.
  maxon::Id callerId("net.mycompany.myplugin.fileselectdialog");
 
  // A set of file type filter strings for the file types which should be selectable for the user.
  maxon::BaseArray<maxon::Tuple<maxon::String, maxon::String>> typeFilter;
  typeFilter.Append(maxon::Tuple<maxon::String, maxon::String>("All files"_s, "*.*"_s)) iferr_return;
  typeFilter.Append(maxon::Tuple<maxon::String, maxon::String>("3D-Formats"_s, "*.c4d;*.dxf;*.lwo;*.lws;*.3ds;*.obj;"_s)) iferr_return;
 
  // This stores output of the method, the selected files. The the last argument of 
    // FileSelectMultiple() is of type ValueReceiver, which is an alias for Delegate<Result<Bool>(T...)>. 
  // Passing a BaseArray<Url> is only one form of populating such ValueReceiver, other forms could 
  // be using a lambda or a delegate function.
  maxon::BaseArray<maxon::Url> selectedFiles;
 
  // Invoke the file selection dialog for selecting multiple files.
  Bool res = Filename::FileSelectMultiple(
    FILESELECT::LOAD, dialogTitle, startUrl, callerId, typeFilter, selectedFiles) iferr_return;
 
  // Iterate over the selected files when the user did not abort the dialog.
  if (res)
  {
    for (maxon::Url& fileUrl : selectedFiles)
    {
      ApplicationOutput("@", fileUrl);
    }
  }
 

Preset Browser

A Filename object may also be used to reference a file located in Cinema 4D's content browser.

• Filename::IsBrowserUrl(): Returns true if the Filename contains a content browser url.

          // This example checks if the file referenced in a filename parameter is a preset file or not.
 
          GeData geData;
 
          // access a filename parameter
          if (node->GetParameter(ConstDescID(DescLevel(ID_FILENAME)), geData, DESCFLAGS_GET::NONE))
          {
            const Filename filename = geData.GetFilename();
 
            // check if the given Filename
            // is a preset URL
            if (filename.IsBrowserUrl())
              ApplicationOutput("File is stored in presets"_s);
          }

Compare

Two Filename objects can be compared easily:

• Filename::operator==(): Returns true if the filenames are the same.
• Filename::operator!=(): Returns true if the filenames are not the same.

  // This example checks if the selected folder is the desktop.
 
  const Filename desktop = GeGetC4DPath(C4D_PATH_DESKTOP);
 
  Filename folder;
 
  // open folder selector dialog
  if (folder.FileSelect(FILESELECTTYPE::ANYTHING, FILESELECT::DIRECTORY, "Select Folder"_s))
  {
    if (folder == desktop)
      ApplicationOutput("You selected the desktop.");
    else
      ApplicationOutput("You selected " + folder.GetString());
  }

Disc I/O

A Filename object can be stored in a BaseFile or a HyperFile using:

• BaseFile::ReadFilename(): Reads the Filename from the BaseFile.
• BaseFile::WriteFilename(): Writes the Filename to the BaseFile.

  // This example writes the Filename into a new BaseFile.
 
  AutoAlloc<BaseFile> bf;
  if (bf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open BaseFile to write
  if (!bf->Open(filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  bf->WriteFilename(filenameData);
  bf->Close();

    // This example reads a String form the given BaseFile.
 
    AutoAlloc<BaseFile> bf;
    if (bf == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // open BaseFile to read
    if (!bf->Open(filename, FILEOPEN::READ, FILEDIALOG::ANY))
      return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
    Filename filenameData;
    bf->ReadFilename(&filenameData);
 
    ApplicationOutput("Filename from BaseFile: " + filenameData.GetString());
 
    bf->Close();

• HyperFile::ReadFilename(): Reads the Filename from the HyperFile.
• HyperFile::WriteFilename(): Writes the Filename to the HyperFile.

  // This example writes the Filename into a new HyperFile.
 
  AutoAlloc<HyperFile> hf;
  if (hf == nullptr)
    return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
  // open HyperFile to write
  if (!hf->Open(753, filename, FILEOPEN::WRITE, FILEDIALOG::ANY))
    return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
  hf->WriteFilename(filenameData);
  hf->Close();

    // This example reads a String from the given HyperFile.
 
    AutoAlloc<HyperFile> hf;
    if (hf == nullptr)
      return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
 
    // open HyperFile to read
    if (!hf->Open(753, filename, FILEOPEN::READ, FILEDIALOG::ANY))
      return maxon::UnknownError(MAXON_SOURCE_LOCATION);
 
    Filename filenameData;
    hf->ReadFilename(&filenameData);
 
    ApplicationOutput("Filename from HyperFile: " + filenameData.GetString());

Further Reading

• GeData Manual
• BaseContainer Manual
• String Manual (Classic)
• Filename Manual