UsersGuide:Chapter 2:Working With Projects
From Real Software Documentation
Working with Projects
All of the windows, menus, modules, pictures, sounds, movies, plug-ins, databases, and programming code that make up an application are stored in a Project document. Projects give you a convenient way to organize the objects that make up your application. You can have several projects open at once and you can have several windows open per project.
Projects can contain any of the following items:
- Windows
- Menu bars
- Classes
- Class interfaces
- Modules
- File Type sets
- Container Controls
- Pictures
- Sounds
- Movies
- Databases
- AppleScripts (Mac OS only)
- Resource files (Mac OS only)
- Cursor resources
- Folders
- Build Automation (Enterprise version only)
- Documents of other types, which are treated as text strings
Each item is denoted by an icon that denotes its type and, in some cases, its subtype. For example, different window types have their own icon. If some of these items are not familiar to you, don’t worry. You will learn more about them in later chapters.
Double-clicking on an item in the Project Editor will either display the item in its editor or a viewer for the item, if Real Studio has no editor for that type of item.
 |
NOTE: There is one exception to this rule. You can encrypt an item in the Project Editor to prevent others from accessing the item and any code associated with it. An encrypted item functions normally in the built application, but it cannot be viewed or edited within the Real Studio IDE. Encrypted items have a small key in the lower-right corner of its icon. When you doubleclick an encrypted item, Real Studio displays an alert that tells you that the item is encrypted. For more information, see Encrypting Your Source Code in Chapter 5. |
Creating a New Project
When you open Real Studio by double-clicking on the Real Studio icon, either a new project is created for you automatically or the most recent project is opened. Optionally, Real Studio will display a QuickStart screen that leads to an introduction to Real Studio. These options are controlled by the Startup options screen in Real Studio options. To set your options, choose Edit ↠ Options (or Real Studio ↠ Preferences on Macintosh). Scroll the left panel down and click the Startup icon. The following screen appears.
On Mac OS X Lion, the operating system has taken over the job of opening the recently opened documents, so this option does not appear.
If you select the Show Quickstart at Launch option, then the following screen is presented in front of the Real Studio IDE. It appears after you select the application type in the New Project dialog box.
By default, the Quickstart screen is shown the first time you launch Real Studio. After you have viewed the demo and finished the Quickstart, you can deselect it in the Startup options screen.
If you turn off the Quickstart screen, Real Studio will either open a new untitled project or your most recently opened project. It will do the latter if you select the Open Most Recent Project in the Startup screen in the Options dialog (shown in the prior illustration) or you are using Mac OS X Lion or greater and are using the operating system to open the recent document. By default, the new project is a Desktop Application project but you can change the type of project. For more information, see the section Creating Project Templates in Chapter 2.
If you immediately resize the IDE window after creating a new project, Real Studio will remember this size and use it as the default IDE window size for subsequent new projects.
If you have a project open and wish to begin a new one, simply choose File ↠ New Project. Real Studio presents the New Project dialog box.
For more information on creating new projects from a template, see Creating Project Templates in Chapter 2.
When you create a new project from a template, the Project Editor will contain all the additional objects that were saved with the project when the template project was created.
Configuring the Project Editor Toolbar
The Project Editor Toolbar (just below the row of Tabs) has buttons for adding items to the project. By default, it has buttons for adding classes, class interfaces, modules, folders, menubars, and windows. If you like, you can modify the Project Editor toolbar with the View ↠ Editor Toolbar ↠ Customize submenu. Note that the Project pane must be selected to customize the Project Editor toolbar rather than another editor’s toolbar.
The following dialog appears:
The Customize Project Toolbar dialog box uses a “mover” interface to configure the toolbar. Listed in the right panel are the current items in the toolbar. Listed on the left are optional items that can be added to the toolbar.
The following operations are available:
- To add an item, highlight it in the left panel and click the Add button.
- To remove an item, highlight it in the right panel and click the Remove button. This moves the item to the list on the left.
- To reorder an item, highlight it in the right panel and click either Move Up or Move Down or select the item to be moved, drag it to the desired location, and drop it between two items. The order in which the items are listed is the left-to-right order in the toolbar.
- To change the appearance of the items in the toolbar, choose an item from the Display As drop-down menu. Your choices are:
- Big icons with labels.
- Small icons with labels,
- Big icons (no labels),
- Small icons (no labels),
- Labels only.
- Big icons with labels.
- To reset the toolbar to the default toolbar, click the Reset button (Windows and Linux) or the Reset Defaults button (Macintosh).
Adding Items to Your Project
The method you use to add items to a project depends on the type of item you wish to add. You add Real Studio project items such as windows, classes, class interfaces, menubars, and modules by clicking on a button in the Project Editor toolbar (just below the row of tabs) or with the Project ↠ Add submenu.
If you have a picture, sound, movie, or Real database you wish to use in your project, you can add with the File ↠ Import menu item. It displays an import-file dialog box that enables you to navigate to the item to be imported. Choose the item and click the Import button.
You can also import items by dragging a file from the desktop and dropping it into the Project Editor. If Real Studio stores a shortcut (alias on Macintosh) to an external item, it is displayed in italics within the Project Editor. You will learn in later chapters how to add each type of item that can appear in the Project Editor.
Dragging to the Tabs Bar
If the Project Editor is not displayed, you can still import an item into the Project Editor by dragging. Do this by dragging the item to the Tabs bar. Any item that can be dragged to the Project Editor can also be dragged to the Tabs bar. When you complete the drag on Macintosh, the Tabs bar gets a marquee that indicates that it can accept the dragged item. On Windows and Linux, the pointer changes to show a marquee.
Organizing Project Items
If your application has many items in its Project Editor, you may want to organize them rather than leaving them in the order in which they were created. First, you can reorder an item by holding the mouse button down on the item and dragging it up or down. As you drag, you can drop it to a new position. The new position is indicated by a horizontal line between existing items as you move the dragged item over it. Release the mouse button to drop the item into its new position.
You can also group items by adding a folder to the Project Editor and storing some items in the folder. For example, you might want to create a folder to hold all the movies and another folder for all the sounds. First, create the folder by clicking the Add Folder button in the Project Editor toolbar or choose Project ↠ Add ↠ Folder.
A folder has one property, its name. Use the Properties pane to give the new folder a meaningful name. Then drag items that you wish to group together into the folder. To drag into a closed folder, drag in a diagonal direction to the right to indicate that the item should be placed in the folder instead of above or below. If you want to add new items to a folder, open the folder and then click the Add button in the toolbar for the desired type of item.
Note that your use of these two features does not affect the functionality of the project. They are available as a convenience to you, making it easier to work with projects with a lot of items.
External Project Items
It is also possible to include windows, classes, or modules in a project that are actually stored in external files. This feature allows more than one project to use the externally stored item. When you modify an external project item in Real Studio 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 external file, that project will reflect your changes. However, Real Studio does not allow you to open more than one copy of Real Studio accessing the same external project item simultaneously.
To convert a project item to an external item, select it in the Project Editor and right+click (Control-click on Macintosh) to display the contextual menu for the item and choose Make External. Real Studio will display a Save-file dialog box. Navigate to the directory in which you want to save the item, name the item, and click Save. When you have successfully saved the item, it will be shown in the Project Editor with a shortcut badge and its name will be in italics. This is shown below.
To add an item to a project as an external item, hold down Alt key (⌘ and Option keys on Macintosh). The File ↠ Import menu command changes to Import as External. Choose that command and select the item to be imported. You’ll know you’ve done it correctly because the icon in the Project Editor will have a small shortcut (alias on Macintosh) badge and the name will be in italics, just like shortcuts on the desktop. IIn the illustration below, an externally stored module has been added to the project.
You can add an item to another project as either an external item or a regular item. To add it as an external item, hold down the Ctrl and Shift keys (⌘ and Option keys on Macintosh) when dragging to the Project Editor.
When you save a project that contains external items, Real Studio will display a Save As dialog box for each external item, followed by the one for the project itself. This gives you an opportunity to save your modified external project items to a new location, leaving the original ones intact. External project items that you haven’t modified are not presented in this way.
If an external project item is set to Read Only in Windows or Linux or locked in the Finder (on Macintosh), you can’t modify that item within the Real Studio IDE, 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. It also provides a way to use Real Studio with some version control systems, as long as these systems can use locking at the OS level to reflect the checked in/out state of each file. (Note that if an external file is changed on disk by something other than Real Studio — such as a version control system — you’ll need to re-open the project to reload that item.)
In addition to Real Studio items that can be stored either internally or externally, several other types of items are stored as external items by default. These include movies, sounds, and pictures.
Removing Items from Your Project
You can remove items from a Project by clicking once on the item in the Project Editor to select it and then pressing the Delete key. You can also select the item and choose Edit ↠ Cut or Edit ↠ Delete. You can also use the Delete command in the Project Editor’s contextual menu, described in the following section.
The Project Editor Contextual Menu
The Project Editor has its own contextual menu that makes it easy to perform actions directly from the Project Editor. Right+click on a project item (Control-click on Macintosh) or on the blank space in the Project Editor to display a contextual menu. The items on the menu vary depending on object type and may include some or all of the following items:
- Add to Project: Has a submenu that offers to add any type of item that can be added to the Project Editor. Items that can be added include windows, classes, class interfaces, container controls, modules, toolbars, folders, menu bars, file type sets, Real SQL Databases, report, build automation script, and ActiveX controls (Windows only). For Web applications, you can add a WebPage, a WebDialog, or a Style object. This menu item duplicates the functionality of the Project ↠ Add menu item.
- Add to ModuleName: Available only when the selected item is a module. Has a submenu that offers to add any type of item that can be added to a module namespace. Items that can be added are classes, class interfaces, and other modules. If the contextual menu is displayed while a module’s Code Editor is displayed, the submenu also offers to create a method, property, computed property, constant, note, structure, or enum. For information about adding items to modules, see Chapter 6.
- Edit Source Code: Opens the Code Editor for editing the item within Real Studio. For example, if the item is a module, it opens the Code Editor for the module. If the item is a movie, it opens the movie using the default media player for the movie type, if available. You can also open files by simply double-clicking the item in the Project Editor. (If the object is encrypted, the Edit command is unavailable).
- Edit Window: Opens the window for editing in a Window Layout Editor. This item is available only if the item is a window or a container control. Windows are not a part of Web applications, so this item is not available for Web applications.
- Find Item: Finds all instances of the selected item in the project. When you choose Find Item, Real Studio opens Search Results panel that lists the results of the search. For more information on the Search Results panel, see the section Searching your Project in Chapter 5.
- Delete: Removes the item from the project. You can undo this action with the Edit ↠ Undo Delete menu command.
- Duplicate: Duplicates the selected project item.
- Play: Appears only if the item is a sound file. Plays the sound.
- Open File: Opens the file as if double-clicked from the desktop. For example, if the item is a picture, it opens the item in the application indicated by its file extension or Type and Creator codes.
- Show on Disk: Opens the file’s folder and highlights the file. For external items only.
- File Path: Displays a hierarchical menu to the external item, allowing you to open any folder enclosing the file.
- Relocate: Opens an open-file dialog box, enabling you to reopen the item if it has been moved from its original location. For external items only.
- Encrypt: Displays the Encrypt… dialog box, allowing you to enter an encryption password and encrypt the object. Encryption is supported only in Real Studio Professional and Enterprise editions. Decryption is supported in all editions. This feature is most typically used to hide code in windows, classes, or modules that you distribute or sell to other developers. For an example, see the section in Encrypting Modules in Chapter 6. Available only if the item is not encrypted.
- Decrypt: Displays the Decrypt… dialog box, allowing you to enter the encryption password to decrypt the object. An encrypted object in the Project Editor has a small key in the bottom-right corner of its icon. Available only if the item is encrypted.
- Add to Class: Appears for classes, allowing you to add structures, enums, and delegates to classes.
- New Subclass: Appears only when the selected item in the Project Editor is a class or subclass. Creates a new subclass, adds it to the Project Editor, and automatically sets its super class to the selected class. That is, it creates a subclass of the selected class. The new subclass is automatically named CustomClassName, where ClassName is the name of the super class. After creating the subclass, you can use the Properties pane to make any necessary modifications to the new subclass, including changing its Super class. See Chapter 10, Creating Reusable Objects with Classes for information on classes and subclasses.
- Extract Superclass: Opens the Extract Superclass dialog box. Available only for classes that do not have a superclass. This enables you to create a new superclass from the current class. You can give the new superclass a name and select some or all of the methods and properties of the current class to be methods and properties of the superclass instead. When you accept this dialog, the new superclass is added to the project and any methods or properties that you selected become methods of the superclass and are removed from the current class. For information on classes and superclasses, see Chapter10, Creating a Superclass from an Existing Class.
- Implement Interface: Opens the Implement Interface dialog box. This enables you to implement a class interface for the selected item. It is available only for windows and classes. It contains a drop-down list of all the built-in and custom interfaces in the project. Choose among the types of interfaces presented in the drop-down list. When you specify a class interface via this dialog box, Real Studio will automatically add all the method declarations specified by the class interface to the item’s Method Editor and will open the Method Editor to the first such method. A window or class can have more than one class interface. Repeat this process to specify additional class interfaces for the item. For more information on interfaces, see the section in Chapter 10, Class Interfaces.
- Property List Behavior: Available only for classes. Displays the ClassName Property List dialog box. It enables you to customize several aspects of the Properties pane when an instance of the class has been added to a window. For information on the Properties List Behavior dialog, see the section, Customizing the Properties List in Chapter 10.
- Make External: Saves the item to disk as an external project item. The difference between Make External and Export is that Make External also converts the item from a “regular” item to an external item for the present project. Like exported items, the copy on the desktop can be imported into other projects. For information on external project items, see the section in Chapter 2, External Project Items.
- Make Internal: Appears only when the selected item in the Project Editor is an external item. Make Internal converts the item to an internal project item.
- Export: Used to export the item to disk. When you choose Export, a Save-file dialog appears, enabling you to save the item to disk. You can import the item into another project by dragging it from the desktop to the Project Editor or importing it as an external item (in which the item remains on disk and can be shared among projects) by holding down the Ctrl and Shift keys (⌘ and Option keys on Macintosh) while you drag the item from the desktop to the Project Editor.
- New Implementor: Available only for class interfaces. Creates a new class that implements the selected class interface. The new class is named CustomInterfaceName. It has no Super class but implements the methods of the selected interface. For more information on interfaces, see the section in Chapter 10, Class Interfaces.
- Find Implementors: Available only for class interfaces. Searches the project and finds all classes that implement the current class interface. When it is finished, it creates a new Search Results tab that lists the results of the search. For more information on interfaces, see the section in Chapter 10, Class Interfaces.
- Extract Interface: Opens the Extract Interface dialog box. Available only for windows and classes. This enables you to create a new class interface that uses some of the methods of the current item in the new class interface and makes the current class or window an implementor of the new class interface. For more information on interfaces, see the section in Chapter 10, Class Interfaces.
- Attributes: Available for project items and methods and properties in the Code Editor. Opens the Attributes Editor for the item. Attributes are compile-time properties. An attribute is added to an item via the Attributes Editor in the Project Editor. They can be accessed by the AttributeInfo class in the language. For more information on Attributes, see the section in Chapter 4, Attributes.
- Web Page: Available only if the project is for a Web application. Adds a new WebPage to the project.
- Web Dialog: Available only if the project is for a Web application. Adds a new WebDialog to the project.
- Style: Available only if the project is for a Web application. Adds a new Style Editor to the project.
Saving Your Project
When you want to save the changes you have made to your project, choose File ↠ Save. If you aren’t sure whether you want to keep the changes you have made, you can choose not to save your project or choose Save As from the File menu and save the project under another name. This will keep your original project intact.
By default, Real Studio saves the project in its own binary format. This is the preferred format for normal project development with Real Studio. In addition, you can also save in either the XML or Version Control Project (VCP) formats. These options are offered in the “Save as Type” or Format (on Macintosh) pop-up menus in the Save As dialog box.
If you need to save in either alternate format, you can set the default preference in the General Options screen (Preferences on Macintosh). You can set the default to the binary format (RBP), XML, or VCP format.
As noted above, you can save external project items independently of the project via the items’ contextual menus.
Saving as XML
Projects can be saved in XML format using the File ↠ Save or File ↠ SaveAs commands and then choosing XML from the Save as Type (Windows and Linux) or Format (Macintosh) pop-up menu in the Save-file dialog box. When you save in XML format, you are really doing an export, not a save; the project stays associated with its original file location and format.
Opening XML
Projects can be imported from XML using the File ↠ Open command. Also, all text files will appear in the Open dialog, but only those that contain proper XML data can actually be read. If the open is successful, an IDE for the project appears, just as if it had been saved in the Real Studio format.
Saving as a Version Control Project
The Version Control format saves the project in a human-readable text format. This format is intended only for use with a Version Control System to handle version control and project sharing among multiple programmers. In the Version Control system, programmers can easily reconcile different versions of the same project by working with the text files.
Although the Version Control Project format produces editable text files, you should not attempt to write your code or continue development of the project in a text editor. Project development is supported only within the Real Studio IDE.
When you save a project in the VCP format, you actually get several files that collectively represent the information in the project. Here are general descriptions of the types of files that you get:
- The Project file is store as an.rbvcp file that contains the properties of the application as a whole. The.rbvcp file can be opened from the Real Studio IDE via the File ↠ Open command.
- Source code project items (interfaces, modules, classes, file type sets) are stored in .rbbas files.
- Each window and container control is stored in a.rbfrm file that contains the window’s or container control’s contents as well as the source code.
- The menus are stored in an.rbmnu file.
- External items (pictures, sounds, movies, and so forth) don’t generate any extra files since they’re already external.
- Binary items are saved in a single binary.rbres file. Items such as the application’s icon, file type icons, encrypted items, and so forth are stored here. This file is not meant to be human readable.
In a text file, each item begins with a #tag statement that indicates the type of the item, such as “#Tag=Window”. This is followed by a text representation of the item. For example, properties are represented as key-value pairs (such as “Width=350”), methods and menu handlers are stored in a Version Control project, and so forth. The details of the format are not officially documented, but you will be able to recognize what each item is.
On the Macintosh a, VCP uses Unix line endings.
To use a version control system, save simply save the project in VCP format. Then you can check the items in. For detailed information about the VCS “Subversion,” see http://subversion.tigris.org.
When you delete files or folders from a project in VCP format, they are left on disk. This is actually useful for Subversion and similar VCS users as it gives you a chance to manually delete the file from Subversion.
Renaming a project item produces a “.obsolete” file. For example, if you have Foo.rbbas and rename it to Bar.rbbas, you are left with Foo.rbbas.obsolete. To fix this in SVN you have to manually (outside of Real Studio) do the following:
- Rename Bar.rbbas to a temporary name such as Bar.rbbas.hide
- Rename Foo.rbbas.obsolete to Foo.rbbas
- Use Svn to rename Foo.rbbas to Bar.rbbas (no need to commit, just need the rename operation pending)
- Manually delete Bar.rbbas
- Rename your Bar.rbbas.hide back to Bar.rbbas
- Commit
 |
NOTE: When you update the project, you should have the project closed. Otherwise, the IDE may save over what got just got checked out. It does not notice file changes when the project is open. |
Opening a Version Control Format Project
The files that are generated by Real Studio when you save in the Version Control Project format should be kept in the same directory. To open a project in Version Control Project format, choose File.Open and choose Version Control Project from the Format drop-down list (Not needed on Macintosh). Navigate to the correct directory and then open the.rbvcp file that corresponds to the desired project.
Creating 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, Real Studio 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 Real Studio called “Project Templates”. If you do so, your list of templates will be listed in the New Project dialog box whenever you choose File ↠ New Project.
If you want Real Studio to use a particular custom template automatically, name it “Default New Project” and place this template in your Project Templates folder. This is the kind of project the IDE will create if you open the IDE directly without opening a project. You can create a project in the Project Templates directory and it will be used as the default when the IDE starts.
Here are descriptions of the project templates that are included with Real Studio. The first three templates are built into Real Studio, but they can be overridden by providing templates that use these names and place them in the Project Templates folder.
- Default New Project: This is the kind of project the Real Studio will create if you start Real Studio without opening a project.
The remaining next two templates are bundled with Real Studio but can be replaced by placing projects in the Project Templates folder that use their names.
- Desktop Application: The standard desktop application template. It is intended for a very wide variety of applications that have a graphical user interface. The App class in the Project Editor is based on the Application class, the MenuBar is based on the MenuBar class, and the Window class is based on the Window class with the Frame property set to Document. This type of window is the standard overlapping window with the usual widgets that are appropriate for each platform.
- Console Application: This is the standard template for applications that are intended to work in the background (e.g., servers). Its App class is based on the ConsoleApplication class instead of Application. This class has only two event handlers, Run and UnhandledException. It is expected that the application runs in the Run event and the UnhandledException event manages the exceptions. There is no default window and no default MenuBar since there is no user interface.
- Web Application: This is a standalone application with a user interface that is intended for deployment on the web rather than on any desktop operating system. Web Applications are “cloud-based” applications such as Google Mail and Google Maps. Real Studio Web Applications are built using its own WebPage Layout Editor, Web Application controls, and supporting editors. Although it presents a visual interface, it is technically a Console Application. Support for building Web Applications is an Enterprise feature and is also available separately (i.e., without the Desktop Application user interface). Other licensed users can create demo versions of Web Applications.
- CGIApplication: This is a specialized version of the Console Application template that is intended as a web application that interfaces with the Apache server. Its App class is derived from the CGIApplication class (in the project) that in turn is based on the ConsoleApplication class. CGI (Common Gateway Interface) is how a web application works with Apache.
More detailed notes on the CGIApplication are found in the “Notes” section of the App class. The HTTP module contains a custom class that manages HTTP requests. It contains properties and methods that you will use to build the interface to Apache.
- 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 in the Language Reference.
- 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 in the Language Reference for information on how a console application works.
When you start a new project, you can either choose from the templates listed in this dialog or choose a template that is on another location on your computer. To choose the latter, you can simply drag the template into the list of templates in this dialog.
To use a template to start a new project, do this:
 |
|
