Project file information

A Xojo project is a document that contain all the items that make up your app. You can have several projects open at once and you can have several windows open per project. When you choose to create a new project, you have these types from which to choose: Desktop, Web, Console or iOS.

Type	Description
Desktop	Desktop projects allow you to create apps with a graphical user interface that run on Windows, Mac and Linux desktop operating systems.
Web	Web projects allow you to create apps that run on the web. Users interact with these app using a web browser.
Console	Console projects are used to create text-based apps that run from the command line, terminal or as a background app (service or daemon). Windows, Mac and Linux are supported.
iOS	iOS projects are used to create apps that run on iOS devices such as iPhones and iPads.

If you load a project into a version of Xojo that is different that the version that created it, you will get a dialog. When projects that were last edited in an older version of a Xojo are opened, a warning is displayed. If the project was last edited in a version of Xojo newer than the version of Xojo being used now, then a critical dialog is displayed because you may use properties and values that are specific to the newer version of Xojo.

Project formats

You can save your projects in a several formats, including the binary single-file format (xojo_binary_project), an XML format (xojo_xml_project) and a text format (xojo_project) which uses separate files for project items. A full (non-lite) Xojo license is required to use the XML or Text project formats. In Preferences you can change the format that is used by default.

Note

Xojo can also open and save Real Studio and Realbasic project files.

Binary (xojo_binary_project)

This is a binary file format. Your project is stored in a single file (except for external items such as pictures) that is easy to distribute. This is the only file format that can be used with a Xojo Lite license or when you do not have a license.

XML (xojo_xml_project)

The XML file format is an XML representation of the binary file format. It is also a single file, but it is entirely XML. Being XML, this file format can be larger than the same file saved as Binary, but it is text so you can view it in an external text editor. A Xojo license is required to use the XML project format.

Text (xojo_project)

The Text file format saves your project as separate text files, one for each project item. Because of this, make sure that your save each Text project in its own folder and do not try to save multiple text projects into the same folder.

The Text file format is version control ready and is ideal for use with Git, Subversion or other version control systems because you can see exactly what files have changed and track the history of changes to files.

Note

Previously, the Text project format was also referred to as the Version Control Project (or VCP) format.

A Xojo license is required to use the Text project format.

This format uses the following extensions for your project items:

Extension	Description
xojo_code	Contains source code project items such as modules, classes, web pages, iOS views and anything else not listed below.
xojo_window	Contains windows and container controls from desktop projects.
xojo_menu	Contains menus from desktop projects.
xojo_menu	Contains toolbars from desktop projects.
xojo_toolbar	Contains toolbars from desktop projects.
xojo_report	Contains reports from desktop projects.
xojo_resources	Contains binary information such as icons, encrypted items and other binary data.
xojo_uistate	Contains the IDE and UI layout settings such as: window positions and sizes, warning preferences, iOS debug device, bookmarks and breakpoints.

When used with a version control system, you should add all the files to your repository except for the xojo_uistate file (which you'll typically want to mark as ignored).

When you delete (or rename) files or folders from a text project format, they are left on disk so that you can manually handle the change using your version control software.

External items

Certain project items are always stored as external items and are not included in the project file. These are: pictures, movies, sounds, text files and other files added to the project.

It is also possible to include windows, classes, or modules in a project that are actually stored as external files. This feature allows more than one project to share the project item. When you modify an external project item and then save your project, your changes are written out to the external file on disk. When you open any other project that refers to the same shared file, that project will reflect your changes.

To convert a project item to an external item, select it in the Navigator and right-click (Control-click on Mac) to display the contextual menu for the item and choose Make External. This displays a Save File dialog box. Navigate to the directory in which you want to save the item, name it, and click Save. When you have successfully saved the item, it is shown in the Navigator with a shortcut badge and its name is in italics.

To add an item to a project as an external item, press and release the Alt key (hold down the Option Command key on Mac) before clicking in the menu, then select the File menu and you'll see the Import menu now says "Import External". Choose that command and select the item to be imported. You can also add an external item by dragging the file from the disk to the Navigator while holding down ⌘ Option (on Mac) or Shift Ctrl (on Windows and Linux).

When an item is imported as external the icon in the Navigator appears in italics with a shortcut badge. If an external project item is set to read only (Windows or Linux) or locked (Mac), you can't modify that item within the project, though you can still view it. This provides a convenient way to protect external items (which may be shared by many projects) from accidental modification. Note that if an external file is changed on disk by something other than Xojo — such as a version control system — you 'll need to close and re-open the project to reload that item.

Refer to Sharing Code among multiple projects for more information.

Encrypting project items

../../_images/project_types_encrypt_window.png

If you want to distribute a copy of project items for others to use but you do not want them to be able to view or edit your code, use the Encrypt command to protect the project item prior to exporting it. An encrypted item displays in the Navigator with an icon containing a small key in its lower-right corner. An encrypted project item cannot be viewed when it is selected in the Navigator.

You can encrypt (protect) or decrypt (unprotect) a project item while it is in your project using the contextual menu “Encrypt ProjectItemName...”. An encrypted item cannot be opened and no one can access any code (or layout) associated with it unless they know the password to decrypt it. When encrypting an item, you supply a password that can be used to decrypt it later.

Warning

Do not forget the password as there is no other way to decrypt the item.

Import project items

To import a file you wish to use in your project, simply drag it from the desktop and drop it in the Navigator. Or, if the file is not conveniently located on the desktop, choose File > Import. An Open File dialog box appears, allowing you to navigate to and import the file.

For code, open the method that you wish to import code into and drag the text clipping into the body of the method. You cannot use the File > Import command to import text files into the body of a method.

To delete a file that has been imported to the project, highlight it in the Navigator and press the Delete key on the keyboard or choose Edit > Delete. You can also delete a file in the Navigator by Control-clicking on the item and choosing Delete from the contextual menu.

Export project items

You can export project items to a file in the XML, binary or text format. Select the project item item and then choose File > Export… from the menu. Exporting project items can be useful for sharing code with others.

You can always copy code to the Clipboard and paste it into a text editor or word processor.

On Mac, the code for methods, events, constants, properties, and so forth can be dragged to the desktop as text clippings or into a text editor.

Collect project items

Choosing File > Collect Project Items will make a copy of the project and the plugins folder.

Some of your project items may be external to the actual project files. These can be things such as graphics or even project items that are shared across multiple projects. For distribution, it can be helpful to collect all project items from their various locations next to a saved project.

External items remain as external items, but they are now grouped (pictures, data, scripts, etc.).

This process does not rename items on disk, so duplicate filenames will be reported as errors.

Collecting a project does not save the project. Typically you will want to do a “Save As” after collecting the project so that everything gets saved into a new location. External items will then be saved into this new location. The original project and its original external items will be unchanged.

Choose File > Collect Project Items to collect the current project.

Templates

If you have several items you commonly use in every project, you can save them in a project file and make the project file a template for new projects. The template can include custom windows, classes, modules and other project items.

When you create a new project based on the template, Xojo creates a new untitled project that is an exact copy of the template. The template project itself remains unchanged. This lets you create a new project using existing project items without worrying about modifying the original items.

The most efficient way to use a template is to place it in a special directory in the same directory as Xojo called “Project Templates”. If you do so, your list of templates will be listed in the Project Chooser whenever you choose File > New Project.

Here are descriptions of the project templates that are included by default. Although these templates are built-in, but they can be overridden by providing templates that use these names and placing them in the Project Templates folder.

EmptyService: This is a service application template. Its App class is based on the ServiceApplication class. It also runs in the background with no user interface. Please see the Notes section for the ServiceApplication class for more information.
Event Driven Console: This is also a template for a Console Application. Its App class is also based on the ConsoleApplication class and it includes a custom class, MyApplication, that contains shell methods and properties for a Console Application. See the Notes section for the Console Application class for information on how a console application works.

Changing default projects

When you create a new desktop, web or console project, a simple project is opened with just the basics to get you started.

You can use your own project files as a substitute for the simple projects used for desktop, web and console projects.

To do so, create projects (in Binary format) and add the project items you want to include by default. Save them with the following names in the Project Templates folder:

Default Desktop Project
Default Web Project
Default Console Project
Default iOS Project

For example, if you create Default Desktop Project that has two windows and some standard modules and classes that you typically use in all your projects, they will be immediately available when you select Desktop from the Project Chooser.

Online and network file systems

Do not edit your Xojo project files directly from networked file systems (SMB, etc.) or online file systems (DropBox, Google Files, Box, etc.). The multi-user access and automated syncing can cause project corruption if things happen at inappropriate times.

For sharing projects between computers, Xojo recommends using a version control system.