UsersGuide:Chapter 3:Working with Windows
From Real Software Documentation
Working with Windows
Typically, most of a Desktop application’s user interface will be in the application’s windows. This, of course, is highly application-specific. Real Studio makes it easy to create new windows of just about any type. You create your user interface by creating its windows and adding interface controls such as PushButtons and CheckBoxes. By default, a Real Studio Desktop Application project has one window that is displayed automatically when the application runs. Typically, you will begin designing your application’s interface by adding controls to this window and enabling the controls by writing code.
To add additional windows to an application, you follow the following procedure:
- Add a new window to the project by clicking the Add Window button in the Project Editor toolbar or by choosing the Project ↠ Add ↠ Window command,
- Set the window’s Frame type and other properties using its Properties pane,
- Add controls to the window,
- Add code as needed,
- Add code to display the window in the finished application (see Opening Windows in Chapter 5).
The following sections review the types of windows supported by Real Studio Desktop Edition. In addition to these window types, you can design message dialog boxes without formally creating a window for the message. You do so using the MessageDialog class, which is described in the section The MessageDialog Class in Chapter 3.
The Web Edition is oriented around the web page rather than the document window. Its layout editor uses a parallel structure for options relevant to the creation of Web applications and its own set of user interface controls. This section is relevant to the creation of Desktop applications.
Window Types
Real Studio supports twelve types of windows for Desktop applications. The window type is set by its Frame property. Some types, however, are rarely used in modern applications and are retained only for historical reasons. A few specialized windows are supported on Mac OS X only. The types of windows are:
- Document
- Movable Modal dialog
- Modal dialog
- Floating
- Plain box
- Shadowed box
- Rounded (functionality was available only on Mac OS 9; it appears as a Document window on all currently supported platforms)
- Global Floating
- Sheet window (functionality available only on Mac OS X)
- Metal window (functionality available only on Mac OS X 10.4 and above)
- Drawer window (functionality available only on Mac OS X 10.4 Carbon and above)
- Modeless Dialog
The type you choose for a particular window depends mostly on how the window will be used.
The Web Edition handles types a little differently. You can either create a WebPage or a WebDialog. If you create a dialog, you can specify the type of dialog. The Frame property does not play the same role in Web applications as it does in Desktop applications.
Document
The Document window is the most common type of window. When you add a new window to a project, this is the default window type. It is also the window type for the default window, Window1. Document windows are most often used when the window should stay open until the user dismisses it by clicking its close box (if it has one) or clicking a button programmed to close the window. The user can click on other windows to bring them to the foreground, moving the document window behind the others. This illustration shows an example of a small, blank document window. When you first launch Real Studio, the default Desktop Application project includes one blank Document window.
Document windows can have a close box, a maximize box, and a grow handle (making them user-resizable). Mac OS X Document windows have the standard set of red, yellow, and green buttons in the Title bar.
On Windows and Linux, the default menubar, Menubar1, appears in the window by default. You can choose to display the window with no menubar by setting the MenuBar property of the window to None, or, if you have created additional menubars, choose a different menubar.
When you add a new window to your project, it defaults to the Document Window type. You can modify its type by setting the Frame property (see Using a Window’s Properties Pane in Chapter 3).
Movable Modal
This type of window stays in front of the application’s other open windows until it is closed. Use a Movable Modal window when you need to briefly communicate with the user without the userrsquo;s having access to the rest of the application. Because the window is movable, the user will be able to drag the window to another location in case they need to see information in other windows in order to finish what they are doing in the Movable Modal window. This illustration shows examples of a blank Movable Modal window on each operating system.
On Windows, a Movable Modal window has minimize, maximize, and close buttons in the Title bar. In Windows MDI interfaces, the window opens in the center area of the screen rather than in the center area of the MDI window. Therefore, the Movable Modal window may open outside the MDI window.
On Linux, the window has minimize and close buttons in its Title bar.
On Macintosh, Movable Modal windows do not have a close box, so you need to include a button that the user can click to dismiss the window unless the window will dismiss itself after the application finishes a particular task. Also, Macintosh Movable Modal windows are not resizable by the user and cannot have a maximize box. This means you will have to consider the amount of available screen space the user will have in determining the size you will make a Movable Modal window.
 |
NOTE: There is one exception to the rule regarding Movable Modal windows being in front of all other windows. If a Movable Modal window or one of its controls executes code that opens a Floating window, the Floating window will be in front of the Movable Modal window. However, it is poor interface design for a Movable Modal window to open another window because Movable Modal windows are mostly used in situations where the interaction with the user will be brief. |
Modal Dialog
These windows are very similar to Movable Modal windows. The only difference is that Modal Dialog windows have no Title bar, so they cannot be moved. On Windows, a Modal dialog box has no minimize, maximize, or close buttons. In Windows MDI applications, a Modal Dialog window opens in the center area of the screen rather than the center area of the MDI window. Therefore, a Modal Dialog box may open outside of the application’s MDI window. On Linux, Modal Dialogs are modal but have a Title bar and close and minimize buttons.
The Page Setup dialog box is an example of a Modal Dialog window.
|
NOTE: Because Modal Dialog windows and Movable Modal windows are both modal, the same exception applies regarding floating windows opening in front of Modal windows. See Movable Modal in Chapter 3 |
.
Floating
Like Movable Modal and Modal Dialog windows, a Floating window (also known as a Windoid) stays in front of all other windows. The difference is that the user can still click on other windows to access them. If you have more than one Floating window open, clicking on another Floating window will bring that window to the front, but all open Floating windows will be in front of all non-floating windows.
Because they are always in front of other types of windows, their size should be kept to a minimum or they will quickly get in the user’s way. This type of window is most commonly used to provide tools the user will frequently access.
A Global Floating Window is a Floating window that can float in front of a particular application’s window or all applications’ windows. They are described in the subsequent section, “Global Floating.”
Like Document windows, Floating windows can have a close box and can be user-resizable. On Linux, Floating windows have minimize and maximize widgets.
In Windows MDI applications, a Floating window can float outside the application’s own window. By default, a Windows MDI Floating window opens in the top-left area of the screen, regardless of the location of the MDI window.
Plain Box
These windows function as Modal Dialog windows. The only real difference is their appearance, as you can see in the following illustration. Plain Box windows are commonly used for About Box windows and for applications that need to hide the desktop.
On Windows MDI applications, a Plain Box window opens in the center area of the screen rather than the center area of the MDI window. Therefore, a Plain Box window may open outside the MDI window.
Shadowed Box
Like Plain Box windows, Shadowed Box windows function as Modal Dialog windows. The only difference is their appearance, as you can see in the following illustration. Shadowed Box windows are commonly used for About Box windows.
On Windows MDI applications, a Shadowed Box window opens in the center area of the screen rather than the center area of the MDI window. Therefore, a Shadowed Box window may open outside the MDI window.
On Mac OS X, a Shadowed Box window works like a Modal Dialog box with a minimize button.
Rounded
Rounded windows act like Document windows, as the true “rounded” window is obsolete. It existed as a distinct window type on Mac OS 9 and earlier. Currently, the only differences are appearance (as you can see in the following illustration) and the fact that, on Macintosh, Rounded windows cannot have a zoom box or be resizable. On Windows, a “Rounded” window has the standard minimize, maximize, and close buttons in the Title bar and the corners are not actually rounded.
Rounded windows are not used any more and there is really no reason to choose this option instead of Document windows. Rounded windows appear as Document windows in Real Studio Mac OS X applications.
Global Floating
A Global Floating window looks like a Floating window, except that it is able to float in front of other applications’ windows, even when you bring another application window to the front. This doesn’t work for a Floating window. A “regular” Floating window floats only in front of its own application’s windows.
On Windows MDI applications, a Global Floating window can float outside of the MDI window. By default, it opens in the top-left area of the screen.
Sheet Window
A “Sheet window” is the official name for drop-down dialog boxes that were introduced with Mac OS X. Mac OS X uses them in place of modal dialog boxes. This illustrates an appropriate usage of a Sheet window.
A Sheet window behaves like a Modal dialog window, except that the animation makes it appear to drop down from the parent window’s Title bar. It can’t be moved from that position and it puts the user interface in a modal state. The user must respond to the choices presented in the Sheet window.
Sheet windows behave as sheets only under Mac OS X. On Windows and Linux, Sheet windows behave like Movable Modal dialog windows.
Metal Window
A Metal window uses the metallic background that Apple introduced with Mac OS X and certain Mac OS X software products such as QuickTime, iTunes, and Safari. A Metal window has a Grow handle and the standard Title bar with close, minimize, and maximize buttons of a Document window. The Metal window type requires Mac OS X version 10.2 or above.
In Mac OS X 10.5 Leopard, Apple replaced the metallic look with a gray. Version 10.5 and above use the gray instead of the metal. This is reflected in Real Studio’s Metal window type when it is used under Mac OS X 10.5 and above.
On Windows and Linux, a Metal window looks like a regular Document window.
Drawer Window
A Drawer window was introduced in Mac OS X. It is available only on Mac OS X Carbon and will not be supported under Cocoa. A Drawer slides out of a side or the top or bottom of a main window to provide supplemental information. For example, the Mac OS X Mail application uses a Drawer window to display the user’s list of mailboxes. On Windows and Linux, a window of this type appears as a separate floating window.
Display a Drawer window using the Show, ShowWithin, or ShowModalWithin methods of the Window class. When the Drawer window is displayed, it is in a modeless state even if it is called by ShowModalWithin. You can also control the border from which the window slides (either side, top, bottom, or system default, in which the system figures out where there’s room for the Drawer window).
Modeless Dialog
The Modeless Dialog window is similar to the Modal Dialog, except that it is paired with a parent window (usually a Document window). Unlike a Modal Dialog, it allows you to access the parent window while it is displayed. If you hide the parent window, the Modeless dialog hides as well. If you show the parent window, the dialog reappears.
The Modeless Dialog is supported on Windows and Linux. On Macintosh, it behaves as a Document window.
Custom Window Types
The Window class has a property, MacProcID, that allows you to create custom window types. This property gives you more options than described in this section.
However, these custom types are supported only on Macintosh. All of the window types described in this section are cross-platform, with the limitations noted in each section.
For more information, see the discussion of the MacProcID property of the Window class in the Language Reference.
Using a Window’s Properties Pane
When you click on a window’s name in the Project Editor, the Properties pane changes to show the window’s properties that can be set in the development environment — as opposed to properties that can be set via code. A selected item in the project and its properties is shown below.
You change a window’s properties by entering values into the enterable areas in the Properties pane, by making menu selections, and by selecting or deselecting Checkboxes.
When you enter a value into an entry area, press the Return key to commit the entry. For example, this window’s Title property was changed from the default text, “Untitled”, to “Find and Replace”. The text of the Title property appears in the window’s title bar when the window appears. This illustration shows the window in the finished application.
In the Properties pane, drop-down menus are denoted by the downward pointing arrow on the right side of line. For example, this window’s Frame property was changed from Document to Movable Modal using the drop-down menu.
The icon with the ellipsis indicates that you can enter text by clicking the icon to display a text entry dialog. For example, the HelpTag property of the selected PushButton accepts text entry.
You can enter the text directly into the entry area or click the icon to display a much larger text entry area. An example is shown below.
Creating Windows
When you create a new Desktop Application project, Real Studio adds a window named “Window1” to your project automatically. This is the default project window. Unless you specify otherwise, it will appear when you launch your compiled application. For information on changing the default window, see the section in Chapter 3, Setting the Default Window.
There are several ways to add an additional window to your project. You can click the Add Window button in the Project Editor toolbar, use a menu command, or a contextual menu.
To add a window using the menu command, choose Project ↠ Add ↠ Window. To use the contextual menu, right+click (on Windows and Linux) or Control-click (on Macintosh) and choose Add to Project ↠ Window.
The windows in your project act as templates for windows in your application. When your application opens one of these windows, it’s really opening a copy of the window. This means that your application can have several copies of the same window open at the same time. It’s important to understand this when creating your user interface because there is no need to go to the extra trouble of duplicating a window in the IDE if your application needs to open two of them at the same time. For example, a text processing application uses one window template as the document window. The File ↠ New command in the finished application allows the end-user to create as many document windows as needed from the same template.
Removing Windows
To remove a window from your project, simply click on it once in the Project Editor to select it and press the Delete key or choose Edit ↠ Delete. You can also Right+click the window (Control-click on Macintosh) to display the contextual menu and remove it using the Delete contextual menu item.
You can undo many actions in Real Studio. For example, if you delete a window by mistake, choose Edit ↠ Undo (Ctrl+Z or ⌘-Z on Macintosh).
Setting the Default Window
By default, the window that is included in a Desktop Application project automatically opens when your application is launched. It is called the default window. If you have created more than one window, you can make a different window the default window. Or, you can specify that no windows will open automatically when the application starts.
You set the default window using the DefaultWindow property of the App class object. The App class is added to the project automatically when you create a new Desktop Application project.
To set the default window, do this:
 |
|
When your application launches, the default window (or no window) will open automatically.
Customizing the Window Editor Toolbar
The Window Editor toolbar has buttons for manipulating the controls in the window. By default, it has buttons for changing the Tab Order (the order in which controls are selected when the user presses Tab) and aligning controls. To modify the Window Editor toolbar, choose View ↠ Editor Toolbar ↠ Customize submenu. (Note that a Window Editor must be selected to customize the Window Editor toolbar rather than another editor’s toolbar.)
The Customize Window Editor Toolbar dialog box appears:
The WebPage Layout Editor has three new tools on its toolbar: Fill Width, Fill Height, and Show Measurements. By default, these three tools are displayed, so they appear on the list on the right. This is shown in the following illustration:
Of course, this version of the dialog is available only for the Web Edition Layout Editor.
The Customize Window Editor toolbar dialog box uses a “mover” interface to configure the toolbar. Listed in the right panel are the current items in the toolbar. The left panel contains any available items.
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 an item, 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.
- To reset the toolbar to the default toolbar, click the Reset button (Windows and Linux) or the Reset Defaults button (Macintosh).
Encrypting Windows and WebPages
You can encrypt (protect) or decrypt (unprotect) a window from the Project Editor. WebPages can be encrypted and decrypted using the parallel set of contextual menu commands from the Web application Project Editor.
A protected window cannot be opened in a Window Editor and no one can access any code associated with the window or any of the controls in the window. It’s a good idea to encrypt any Real Studio items that you want to sell to others. They will be able to use the item in their project but cannot modify your code.
Encryption/Decryption is supported only in the Real Studio Professional and Enterprise editions. All editions can use encrypted items.
To encrypt a window, you supply a password which can be used to decrypt it later.
To encrypt a window, do this:
|
The “FindWindow” window has been encrypted in the illustration below. |
When a user tries to open an encrypted window in a Window Editor, Real Studio displays the Decrypt Window dialog box, shown below.
To edit the window and/or its code, you must decrypt it using its encryption password.
To decrypt an encrypted window, do this:
|
|
If you don’t know the password, there is no way to decrypt the window.
