VCOM:Working with File Identifiers

From Vectorworks Developer
Jump to navigation Jump to search

.SDK|SDK ..SDK:Types|SDK Types ..VCOM:VCOM (Vectorworks Component Object Model)|VCOM Basics ..VCOM:Class Reference|VCOM Class Reference

What is this?

File identifier interfaces are: VCOM:VectorWorks:Filing:IFolderIdentifier and VCOM:VectorWorks:Filing:IFileIdentifier

They are used to identify a folder location (or folder path) or file location (or file path) on the OS disk.

The location stored in those identifier interfaces may not actually exist on the disk.

The interfaces are OS independent and should work the same on all platforms.

Creating Interface Instance

The file identifier interfaces are part of VCOM:VCOM (VectorWorks Component Object Model).

Good style is always to use VCOM:VCOMPtr that will manage the interface reference correctly.

// create new instance of the folder identifier interface
IFolderIdentifierPtr pFolderID( IID_FolderIdentifier );

// create new instance of the file identifier instance
IFileIdentifierPtr   pFileID( IID_FileIdentifier );

Setting the Identifier

To set new file or folder path (location) the functions IFileIdentifier::Set and IFolderIdentifier::Set are used.

Those set of functions can set full paths (OS depended) or to work with relative paths according to VectorWorks installed locations.

For path delimiter you should use '/' or '\' on Windows. '/' is recognized on Windows too and it is preferably to use '/' for relative paths.

Building relative paths you can use '..' also to denote one folder up.

':' is not recognized as path delimiter!

On Windows invalid characters are:

Invalid Character Substituted with
/ %5C
\ %2F
: %3A
* %2A
? %3F
" %22
< %3C
> %3E
| %7C

On Macintosh OS the only folder name invalid character is ':'. However if you put that character in the folder path, it will result the folder name to have '/' at that place.

On Macintosh OS if you have CFStringRef string representation in order to use it as path you must convert it into UTF8 encoded SDK:TXString like this:

TXString GetTXStringPath(const CFStringRef& strRef)
{
  TXString    result;
  const char* tempString = CFStringGetCStringPtr( strRef, kCFStringEncodingUTF8 );
  if (tempString) {
    result            = tempString;		
  }
  else {
    CFIndex  length    = CFStringGetLength( strRef );
    size_t   maxChars  = UnicodeToStringMaxChars( length );
    char*    buffer    = new char[ maxChars ];
    CFStringGetCString( strRef, buffer, maxChars, kCFStringEncodingUTF8 );
    result             = buffer;
    delete [] buffer;		
  }
  return result;
}

The enumeration EFolderSpecifier describes default locations for Vectorworks. Here is a list of constants defined in that enumeration:

Constant name Value Description
kRootFolderSpecifier 0
kApplicationFolder 1 The folder where VectorWorks.exe is located.
kExternalsFolder 2 The 'Plug-ins' folder located where VectorWorks.exe is located.
kExternalDataFolder 3 The 'Data' folder located inside 'kExternalsFolder' folder.
kWorkspacesFolder 4 The 'Workspace' folder located where VectorWorks.exe is located.
kOverlaysFolder - Same as 'kWorkspacesFolder'
kParametricsFolder 5 The 'Plug-ins' folder located where VectorWorks.exe is located
kDebugtoolsFolder 6
kTemplatesFolder 7
kStandardsFolder 8
kHelpFolder 9 The 'Help' folder located where VectorWorks.exe is located.
kDictionariesFolder 10
kObjectLibrariesFolder 11
kAppDataFolder 12 The "version/year number" folder inside the Vectorworks user folder.
kLibrariesFolder 13 The 'Libraries' folder located where VectorWorks.exe is located.
kDefaultsFolder 14 The 'Defaults' folder located inside 'kLibrariesFolder' folder.
kSettingsFolder 15 The 'Settings' folder located where VectorWorks.exe is located.
kObjectsImperialFolder 16
kObjectsMetricFolder 17
kPDFResourcesFolder 18
kCommonFolder 19
kCommonDataFolder 20
kCommonIncludesFolder 21
kCommonInterfacesFolder 22
kFavoritesFolder 23
kIconsFolder 24 The 'Icons' folder located where VectorWorks.exe is located.
kDefaultTexturesFolder 100 The 'Renderworks - Textures' folder located inside 'kDefaultsFolder' folder.
kDefaultCabinetHandlesFolder 101
kDefaultDoorHardwareFolder 102
kDefaultGradientsFolder 103
kDefaultHardscapeHatchesFolder 104
kDefaultHatchesFolder 105
kDefaultImageFillsFolder 106
kDefaultPlantsFolder 107
kDefaultToiletsFolder 108
kDefaultRWBackgroundsFolder 109 The 'Renderworks - Backgrounds' folder located inside 'kDefaultsFolder' folder.
kDefaultSeatingLayoutFolder 110
kDefaultTileSymbolsFolder 111
kDefaultHumanFigTexturesFolder 112
kDefaultWallStylesFolder 113
kDefaultStairsFolder 114
kDefaultTitleBlocksFolder 115
kDefaultSectionMarkersFolder 116
kDefaultRepetitiveUnitFolder 117
kDefaultDoorCustomLeavesFolder 118
kDefaultLightingGobosFolder 119
kDefaultReportsFolder 120
kDefaultLightingSymbolsFolder 121
kDefaultPlants2DSymbolsFolder 122
kDefaultPlants3DSymbolsFolder 123
kDefaultPlantsHatchesFolder 124
kDefaultRepetitiveFlooringFolder 125
kDefaultRepetitiveFramingFolder 126
kDefaultRepetitiveMasonryFolder 127
kDefaultRepetitiveMiscFolder 128
kDefaultRepetitiveRoofingFolder 129
kDefaultRepetitiveSidingFolder 130
kDefaultWallsHatchesFolder 131
kDefaultWallsTexturesFolder 132
kDefaultWindowCustomShuttersFolder 133
kDefaultSketchStylesFolder 134
kDefaultPlantListFolder 135
kDefaultPlantDatabaseFolder 136
kDefaultColorPalettesFolder 137
kDefaultFramingMemberProfileFolder 138
kDefaultEventLayoutSymbolsFolder 139
kDefaultSpacesOccupantOrgFolder 140
kDefaultSpacesNameListsFolder 14

Sample

// create new instance of the folder identifier interface
IFolderIdentifierPtr pFolderID( IID_FolderIdentifier );
if ( VCOM_SUCCEEDED( pFolderID->Set( kExternalsFolder, false, "MyFolder" ) ) ) {
   // ...
   // if VectorWorks is installed at "C:\Program Files\VectorWorks" (Windows)
   // then the result folder will be "C:\Program Files\VectorWorks\Plug-ins\MyFolder"
}

// create new instance of the file identifier instance
IFileIdentifierPtr   pFileID( IID_FileIdentifier );
if ( VCOM_SUCCEEDED( pFolderID->Set( kExternalsFolder, false, "MyFolder/MyFile.txt" ) ) ) {
   // ...
   // if VectorWorks is installed at "C:\Program Files\VectorWorks" (Windows)
   // then the result file location will be "C:\Program Files\VectorWorks\Plug-ins\MyFolder\MyFile.txt"
}
// set location inside user folder
IFileIdentifierPtr   pFileID( IID_FileIdentifier );
if ( VCOM_SUCCEEDED( pFolderID->Set( kExternalsFolder, true, "MyFolder/MyFile.txt" ) ) ) {
   // ...
   // if the current user of Windows Vista is 'user'
   // then the result file location will be "C:\Users\user\AppData\Roaming\Nemetschek\VectorWorks\2009\Plug-ins\MyFolder\MyFile.txt"
}

Using relative path:

// set location inside user folder
IFileIdentifierPtr   pFileID( IID_FileIdentifier );
if ( VCOM_SUCCEEDED( pFolderID->Set( kExternalsFolder, false, "../../MyFolder/MyFile.txt" ) ) ) {
   // ...
   // if VectorWorks is installed at "C:\Program Files\VectorWorks" (Windows)
   // the result path is "C:\Program Files\VectorWorks\..\..\MyFolder\MyFile.txt"
   // then the result file location will be "C:\Program Files\MyFolder\MyFile.txt"
}

See Also