File Type Set Editor

From Xojo Documentation

Your desktop apps may need to prompt users to select files. Apps may also want to create their own files, with specific icons for files used by the app. You do all these things by creating File Type Sets with the File Type Set editor.

This File Type Set Editor is available starting with 2015r3.

There are many different file types. The type of a file defines a unique type of data stored in that file. For example, a text file stores text while a PNG file stores PNG images. Files have a file extension (or suffix) that defines the file type. For example, a Text file has the extension "txt". A file named "MyNotes.txt" is recognized as a Text file.

Rather than writing code that deals directly with all of this, you create File Types Sets to abstract you from the details. A File Type Set contains one or more file types that represents a specific file type and contains information on how to identify the file. Each file type has a name that is used in your code when opening and creating files. This allows you to work with names you can choose and easily remember instead of cryptic codes. It also abstracts your code from the operating system, making it easier for you to create versions of your app for other operating systems.

What you specify in your File Type Set is used to tell the OS how your apps deals with files.

For additional information, refer to Using File Type Sets.

Adding File Types

To create a File Type Set, select Insert ↠ File Type Set from the command bar or main menu. This adds a File Type Set to your project, which is empty by default.

Use the buttons in the File Type Set editor command bar to add a custom File Type or add a Common File Type (file types for standard file formats).

Removing File Types

With the cursor in any field of the File Type, click the Remove button on the command bar to remove the file type from the set.

Collapse/Expand All Rows

Use the Collapse/Expand All Rows button on the command bar to collapse the rows to only show the name or to expand them so that all the fields are displayed.

Common File Types

These are file types for standard file formats, such as mp3, text, png, etc. When you choose a common file type, it is added to the File Type Set with the correct properties filled in for you. This is what "text/plain" looks like:

Generally you should not change any of the settings for a common file type. For an example on how to use common file types in your apps, refer to the Using File Type Sets section. Common file types should always have their UTI type set to "Imported".

Custom File Types

File Type Set Editor - Common File Types

Custom file types are used for files that are owned (or created) by your app. These are files that your app creates and knows how to handle. For an example on how to use custom file types in your apps, refer to the Using File Type Sets section.

File Type Properties

When you create a custom file type, you'll have to specify the property values so that your file type is recognized by the OS.

These are the properties that are used with a File Type Set:

  • Name
Required. The name of the file type. You will use this when referencing the specific file type in your code.
  • Red/Green Circle Indicator
The indicator is red by default and changes to green when your File Type icons are set up properly, which includes adding icon and mask sizes to the Image Set. Not all icons are required, but all icons must have both the image and mask. If any icons are partially complete, this indicator displays as orange with a number indicating how many images need to be fixed. Hover over the indicator to get a more specific description of what needs to be fixed.
  • Image Set (Mac-only)
File Type Set - Image Set
Optional. The Image Set contains all the icon sizes (and masks) required for a file type. Drag the image you want to use as the icon for the file type on to the image area of the file type and it will be scaled to fit all the sizes. This image will be used as the file's icon in the Finder on macOS. When you have an all the images and masks specified for the type, the "Circle Indicator" changes from red to green. After dragging an image to the file type, you can click on it to display the Edit Icon window which shows you all the different sizes along with the images and masks. You can drag alternate images into this editor, copy/paste between areas and delete individual images using the contexual menu or standard keyboard commands. Not all images are required, but any images that are added must also have a mask. The Image Set is only used for macOS apps.
  • Display Name
Optional. This is displayed in Windows file dialogs.
  • Description
Optional. A description for the file type to help you remember its purpose.
  • UTI Identifier (macOS-only)
Required for Mac apps that want to use a file type. The Uniform Type Identifier is a unique identifier used by macOS to identify a file. Following the reverse-DNS format beginning with com.companyName.myTypeName is a simple way to ensure uniqueness. An example of a UTI might be: com.example.contactdata.
  • Conforms To (macOS-only)
Required for Mac apps that want to use a file type. The UTIs to which the above UTI Identifier conforms. UTIs are hierarchical, so you need to provide a "parent" or "base type" for your file type's UTI. Apple maintains a complete list of System-Declared Uniform Type Identifiers that you can use. If you don't want to identify your file content to other apps, you can use the base type of "". If you'd like other apps to be able to recognize your file content, you can use a more specific type. For example, if your data file contains any type of text you can use "public.text" to allow other apps that work with text to be able to open your file. You can list multiple UTIs by separating them with commas. Some useful UTIs include:
    • Base physical type for byte streams (flat files, pasteboard data, and so on).
    • public.database: Base functional type for databases.
    • public.text: Base type for all text, including text with markup information (HTML, RTF, and so on).
    • public.html: HTML text.
    • public.xml: XML text.
  • Extensions
Required. The file extensions for the file type (the "." prefix is optional). When you have multiple extensions, list them all separated by semi-colons.
  • Mime Types (macOS-only)
Optional and only used for Mac apps. Mime types are standard media and file format types. The IANA has a list of all Mime types. For example, JPEG has this Mime type: image/jpeg. Your own custom file types are not likely to have a Mime Type since they are not a standard file format. A Mime type can be provided to help provide additional information to other apps that may use the file.
  • OS Types (macOS-only)
Optional. The four-character Mac ostype used by the file type. An example would be "JPEG". This is retained for backwards compatibility, but is not needed on recent versions of macOS.
  • UTI Type (macOS-only)
This can be Imported or Exported.
An imported UTI Type (the default) creates a file type that your app does not own, but would like to use. An example would be if you want your app to be able to open PNG image files. The Common File Types you can add to your project should be defined as Imported.
An exported UTI Type creates a file type that your app owns (the type is also available for use by all other apps on the system). For example, an app that uses (defines or creates) a proprietary document format should declare it as an exported UTI Type. Do not declare a standard file type (such as PDF or PNG) as an exported type as this may alter standard system behavior.

When you change this setting, the icon next to the name at the top of the file type changes to indicate Imported or Exported.

Mac Information

For Mac apps, the File Type information specified above is used to create a UTI that is included in the Info.plist for the app. In addition, Mac apps also require an additional step where you set the roles for each of the file types. To set the roles, select macOS in the Build Settings and then click the File Types button to display a window of all the file types defined in your project. Here you can select the types that your app recognizes and you can choose the role for each type. This is the list of types the app understands along with whether it can edit, just view or possibly only write out files of certain types (behind the scenes it sets CFBundleTypeRole in Info.plist). Roles are:

  • None: The file type is not used by your app.
  • Editor: Your app can read, edit and write files of a particular type, and will give you the usual document behavior. Use this for files your app owns or creates.
  • Viewer: Your app can open and read a particular file format, but can not save in this file format. Use this for files your app can open, but does not own or create.
  • Shell: Not documented by Apple.

A properly set up file type and role enables these OS features:

  • File selection dialogs can limit the selection of files
  • Opening a file will automatically launch the app and pass the file to it
  • The File Type icon will appear in the Finder for files created by the app
  • Dragging a file onto the app's Dock icon will launch the app if it is not running and pass the file to it

Refer to the Using File Type Sets section for specific examples.

To learn more about how macOS uses UTIs, refer to these Apple documentation topics:

Windows Information

On Windows, only the extensions need to be specified in order for file dialogs to limit the selection of files.

Your Windows app installer needs to create Registry entries to set an associated file icon and allow opening of documents to automatically launch the app. For more information on this refer to the sample Inno Setup Scripts for 32-bit and 64-bit apps.