UserGuide

File Type Group 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 Groups with the File Type Group editor.

This File Type Group 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 Group 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 Group is used to tell the OS how your apps deals with files.

Adding File Types

To create a File Type Group, select Insert ↠ File Type Group from the command bar or main menu.

Use the buttons in the File Type Group 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 X button to remove it.

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 Group 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 Group section. Common file types should always have their UTI type set to "Imported".

Custom 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 Groups section.

File Type Editor.png

General 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 Group:

  • Name. Required. The name of the file type. You will use this when referencing the specific file type in your code.
  • Display Name. Optional. This is displayed in file dialogs.
  • Description. Optional. A description for the file type to help you remember its purpose.
  • 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. 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.

macOS-Only File Type Properties

  • Icon. (Mac-only)
    File Type Group - 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. 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.
  • File type is unique to this app CheckBox. Indicates that this file type is uniquely created by and/or read by this application. If this is checked, your application is assumed to both read and write this file type. If it's unchecked, this file type is one 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. This checkbox should be left unchecked for the Common File Types (see above).
fa-exclamation-circle-32.png
Do not declare a standard file type (such as PDF or PNG) as an exported type as this may alter standard system behavior.
  • Identifier. 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.myAppName-DisplayName is a simple way to ensure uniqueness. An example of a UTI might be: com.example.appname-contactdata. All characters in an identifier must be lowercase. The following characters are allowed: a-z, 0-9, - and .
  • Conforms To. 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 "public.data". 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:
    • public.data: 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.
  • macOS Types. Optional. The four-character Mac ostype used by the file type. An example would be "JPEG". This is retained for backwards compatibility. This is used to indicate that your application reads this type of file but not that it writes it.
  • Role. The role indicates if your application is used only for viewing, editing and viewing or executing the file.
  • Rank. Enabled only if the Role is set to Edit, View or Execute. MacOS uses rank to determine which app to use to open a file. The order of precedence is Owner, Default, Alternate. Default means this app is an opener of files of this type; this value is also used if no rank is specified. This would be appropriate for files uniquely created by your application. Owner means this app is the primary creator of files of this type. Alternate means this app is a secondary viewer of files of this type.

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.

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

  • File selection dialogs can limit the selection of files
  • Opening a file or dropping a file onto the app's Dock icon will automatically launch the app and pass the file to the App.OpenDocument event.
  • The File Type icon will appear in the Finder for files created by the app

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.

See Also

UserGuide:File Type Groups topic