Filename Manual

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:

See also BaseContainer Manual.

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

See also GeData Manual.

Important paths are obtained from:

// 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
return maxon::UnexpectedError(MAXON_SOURCE_LOCATION);
ApplicationOutput("Alembic File: " + data.GetFilename().GetString());
@ ALEMBIC_PATH
Definition: Oalembicgenerator.h:6
Definition: c4d_baseobject.h:248
String GetString() const
Definition: c4d_gedata.h:83
const Filename & GetFilename() const
Definition: c4d_gedata.h:510
#define Oalembicgenerator
Alembic generator.
Definition: ge_prepass.h:1157
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:67
#define ApplicationOutput(formatString,...)
Definition: debugdiagnostics.h:210
#define ConstDescID(...)
Definition: lib_description.h:594
const char * doc
Definition: pyerrors.h:226
Definition: object.h:105
Represents a level within a DescID.
Definition: lib_description.h:298

Combine

A Filename can be constructed with basic operators:

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\"");
Manages file and path names.
Definition: c4d_file.h:94
Bool FileSelect(FILESELECTTYPE type, FILESELECT flags, const maxon::String &title, const maxon::String &force_suffix=maxon::String())
return OK
Definition: apibase.h:2747
@ DIRECTORY
Folder selection dialog.
@ ANYTHING
Any file.
Bool GeFExist(const Filename &name, Bool isdir=false)
// 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);
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);
Bool ShowBitmap(const Filename &fn)
Definition: ge_autoptr.h:37
@ OK
Image loaded/created.
const Filename GeGetPluginPath()

Copy

A Filename object can easily be copied:

Properties

String

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

See also String Manual (Classic).

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

File and Directory

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

// 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);
const char const char const char * file
Definition: object.h:439

Suffix

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

// 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:

// 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);
Filename GeFilterSetSuffix(const Filename &name, Int32 id)
#define FILTER_JPG
JPEG.
Definition: ge_prepass.h:190
@ NONE
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.

// This example writes some data into memory and accesses the raw memory afterwards.
if (mfs == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
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);
void SetMemoryWriteMode(MemoryFileStruct *mfs)
Py_ssize_t size
Definition: bytesobject.h:86
maxon::Int Int
Definition: ge_sys_math.h:64
@ NONE
Never show an error dialog.
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:

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

The type of dialog is defined with this flag:

// 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
ApplicationOutput("Folder: " + folder.GetString());
@ LOAD
Load dialog.
@ SAVE
Save dialog.
// Demonstrates the selection of multiple files with Filename::FileSelectMultiple().
// 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.
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.
// Invoke the file selection dialog for selecting multiple files.
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);
}
}
static maxon::Result< Bool > FileSelectMultiple(FILESELECT flags, const maxon::String &title, const maxon::Url &startUrl, const maxon::Id &settingsIdentifier, const maxon::Block< maxon::Tuple< maxon::String, maxon::String >> &filterStrings, const maxon::ValueReceiver< const maxon::Url & > &selectedUrls)
Definition: basearray.h:415
MAXON_ATTRIBUTE_FORCE_INLINE ResultRef< T > Append(ARG &&x)
Appends a new element at the end of the array and constructs it using the forwarded value.
Definition: basearray.h:619
Definition: apibaseid.h:237
Definition: string.h:1235
Definition: url.h:942
Py_UCS4 * res
Definition: unicodeobject.h:1113
maxon::Bool Bool
Definition: ge_sys_math.h:55
#define iferr_scope
Definition: resultbase.h:1386
#define iferr_return
Definition: resultbase.h:1521

Preset Browser

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

// 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);
}
PyCompilerFlags const char * filename
Definition: ast.h:15
Definition: node.h:10

Compare

Two Filename objects can be compared easily:

// This example checks if the selected folder is the desktop.
Filename folder;
// open folder selector dialog
{
if (folder == desktop)
ApplicationOutput("You selected the desktop.");
else
ApplicationOutput("You selected " + folder.GetString());
}
#define C4D_PATH_DESKTOP
OS desktop directory.
Definition: c4d_file.h:1923
const Filename GeGetC4DPath(Int32 whichpath)

Disc I/O

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

// This example writes the Filename into a new BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to write
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
bf->WriteFilename(filenameData);
bf->Close();
@ ANY
Show an error dialog for any error.
// This example reads a String form the given BaseFile.
if (bf == nullptr)
return maxon::OutOfMemoryError(MAXON_SOURCE_LOCATION);
// open BaseFile to read
return maxon::UnknownError(MAXON_SOURCE_LOCATION);
Filename filenameData;
bf->ReadFilename(&filenameData);
ApplicationOutput("Filename from BaseFile: " + filenameData.GetString());
bf->Close();
@ READ
Open the file for reading.
// This example writes the Filename into a new HyperFile.
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.
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