advertisement
Using XVT-Design
4
U
SING
XVT-D
ESIGN
This chapter describes the main features of XVT-Design, and tells how to use them to build your application. The chapter covers the following topics:
• Project Files
• Using the Action Code Editor (ACE)
• Creating Windows, Dialogs, and Controls
• Layout Commands
• Object Attributes
• Creation Order
• The Menu Editor
• String Resources
• Userdata Strings
• Help with Help Files
• TestMode
• Generating Source Code
• Code Recovery
4.1. Project Files
For every application you build with XVT-Design, you begin by creating a new project file. Project files are the “documents” you create and modify with XVT-Design. A project file contains all the resources and source code for your application’s user interface.
Projects are stored in binary files. These files are portable across all platforms on which XVT-Design runs. You can create a project file on one platform, then move it to another platform—without
4-1
XVT-Design Manual
modification—to develop and refine your application on both platforms.
4.1.1. Creating New Projects
Tip:
To create a new project:
Choose New Project from the File menu.
XVT-Design creates a new project and opens an Action Code Editor window and a layout window for the project.
4.1.2. Project Attributes
Tip:
There are several attributes which affect your application as a whole.
You set these attributes with the Project Attributes dialog.
To open this dialog:
Choose Project Attributes from the Edit menu.
4-2
Figure 4.1.The Project Attributes dialog (Macintosh Platform)
You can set the following attributes with this dialog:
Task Menubar
The task menubar is the menubar shown in the task window. The
Project Attributes dialog has a list box that contains the names of all
Using XVT-Design
of the menubars in the project. Click the appropriate name to select the task window’s menubar.
All new project files contain a default menubar, named
TASK_MENUBAR
, which includes the standard File, Edit, Font and
Help menus. This menubar appears first in the list box.
Task Window Title
The title of your application’s task window is usually the same as the name of your application. To set the task window’s title, type its name in the edit control.
Document Prefix
The document prefix string is placed at the beginning of the names of new document windows in your application. To set the document window name prefix, type it in the edit control.
See Also:
Internationalization
You can easily generate internationalized applications with XVT-
Design. The program supports efficient localization process and allows flexibility in internationalization schemes
For details on the entire internationalization process, see Chapter 6 of this manual.
See Also:
Code Recovery
With XVT-Design you can edit the generated files using any text editor and later recover code from inside of XVT-Design.
Code fragments are wrapped with special comments during the code generation process. You can edit the files using a standard text editor and recover all the changes you have made to the generated files.
To make the most of this feature, it must be activated by clicking on the Code Recovery radio button (in the Project Attributes dialog box) early in the design process.
For further explanation of code recovery, see Code Recovery on page 4-68.
Own Font
You can set the default control font for the entire application by clicking on this button.
4-3
XVT-Design Manual
See Also:
For further explanation of choosing and setting fonts, see Fonts and
See Also:
Own Color
You can set the default control color for the entire application by clicking on this button.
For further explanation of choosing colors, see Fonts and Colors on page 4-26.
About Box
The About Box is a dialog that is invoked when the user of your application chooses the “About…” menu item. You can either use a default dialog supplied by XVT-Design, or create your own. Any modal dialog in your project can be used.
The Project Attributes dialog has a list box that contains the names of all of the dialogs in the project. Click the appropriate name to select the About box.
4.1.3. Working with Multiple Projects
You can work with more than one project at a time. The names of all open projects are listed at the bottom of the Edit menu.
Only one project is active at a given time. The active project has a check mark next to its name on the Edit menu. The windows for any inactive projects are hidden. To make a project active, choose its name from the Edit menu.
4.2. Using the Action Code Editor (ACE)
In XVT-Design, the Action Code Editor (ACE) is the primary tool for creating and editing your application’s user-interface source code. Using the ACE, you can
• Create and edit user action code
• Create and modify connections for TestMode
• Invoke other XVT-Design editors
This section describes how to use the ACE for each of these functions.
4-4
Using XVT-Design
4.2.1. Invoking the ACE
Tip:
You can invoke the ACE in several ways:
• From the Tools menu, choose Action Code Editor. You can use this method at any time, as long as a project is open.
• From the Edit menu, choose Edit Code. This menu item is available only when the active window is a layout window for a window or dialog.
• In a layout window, hold down the Shift key and double-click on a control, or the layout window itself.
4.2.2. ACE Code Fragment Templates
Note:
In previous version of XVT-Design, the initial ACE code for each tag was hardwired. In this new version of Design, initial ACE code is contained in a text file called design.cft.
• The design.cft file can be customized.
• When XVT-Design starts up, it reads design.cft.
• Each tag whose code fragment has not previously been modified in the ACE gets initialized with the code you have specified.
• You can create multiple versions of design.cft for use with different applications.
It is important to note that ACE code fragments should not be created larger than 32K.
4.2.2.1. Editing the Design.cft file
The design.cft file is located in the same directory as design.cfg.
Figure 4.2.Directory for the design.cft file
4-5
XVT-Design Manual
4.2.2.2. Viewing the design.cft file
You can use any text editor to open the file.
The design.cft file is shown in the diagram below. There are two types of string variables and they are detailed in the file itself.
4-6
Figure 4.3.A portion of the design.cft file
4.2.2.3. Rules for Editing design.cft
• Do not add or remove any templates.
• Do not change the BeginTemplate or EndTemplate statements.
• Do not add or remove %’s – XVT-Design expects a specific
number of %’s for each template.
• If you change the design.cft file after a project has been created, note that only tags which have never been modified are updated from the design.cft file.
4.2.2.4. Resolving %s’s.
%s’s are documented in the design.cft file itself. There are two types of %s’s:
• A string variable that references a variable that XVT-Design
knows about. These variables are like printf
functions in C. Do
not change these types of variables.
• A string variable that references internal values.
This kind of variable can be changed.
Using XVT-Design
4.2.3. ACE Controls
When opened in a new project, the ACE window looks like this:
Figure 4.4.Controls in the Action Code Editor (Macintosh Platform)
The ACE window contains several controls: three list buttons for setting the editing context, a text editing region for examining and modifying source code, and several push buttons for other operations. The following section describes the function of each control.
4.2.3.1. The Editing Context
In the ACE, context refers to a specific tag for a specific object. The context consists of three parts: the module that contains the object, the object itself, and the tag. Three list buttons in the ACE correspond to these parts (see below).
The titles of the list buttons always indicate the current context.
Action code can be associated with each context. The action code is displayed in the text editing pane of the ACE.
Module
The Module list button lists the titles of all the containers and menubars in the current project. An additional item, “Application,”
4-7
XVT-Design Manual
refers to the context for application events. The code for each module in the project is generated into a different C file.
Object
The Object list button lists the titles of all the objects contained by the item specified by the Module list button:
• If the Module item is a window or dialog, the objects are the controls in that window or dialog
• If the Module item is a menubar, the objects are the titles of the menu items
• If the Module item is “Application,” there is only one object, also titled “Application”
Items in the Object list button have a prefix that indicates their type:
Containers
DLG: Dialog WIN: Window
Controls
CB: Check Box
CC: Custom Control
ED: Edit Control
HS: Horizontal Scrollbar
LB: List Button
LE: List Edit
LX: List Box
PB: Push Button
RB: Radio Button
TE: Text Edit
TX: Static Text
VS: Vertical Scrollbar
Tag
The Tag list button lists all the tags available for the item indicated by the Object list button. The items on this list vary depending on the kind of object (control, menu item, etc.) in the context. There are two types of tags:
• Event tags have the prefix “
EVNT
:”
• Special tags have the prefix “
SPCL
:”
4.2.3.2. The Text Editing Pane
The center of the ACE window contains a rectangular pane for editing text. You’ll use this editor to create, modify, and examine all the action code fragments for your application. The code in this pane always corresponds to the current context of the ACE, as shown by the three list buttons.
4-8
Using XVT-Design
See Also:
See Also:
If the code won’t fit in the editing pane, you can use the horizontal and vertical scroll bars to view it. You can change the size of the pane by resizing the ACE’s window.
To edit text in the ACE, you can use three Edit menu commands:
Cut
Removes the selected text from the editor and places it on the system clipboard.
Copy
Places a duplicate of the selected text onto the system clipboard.
Paste
Places the text from the system clipboard in the editor, at the insertion point. If text is selected in the editor, the clipboard text replaces it.
All text created with the editor is stored on disk in your project file when it is saved. When XVT-Design generates the source files for your application, the text is copied into the appropriate files.
You can also recover code after it has been generated.
For further explanation of code recovery, see Code Recovery on page 4-68.
You can change the font and font size used in the ACE text pane by
editing XVT-Design’s configuration file. See Fonts and Colors on page 4-26.
4.2.3.3. Creating and Editing Connections
You create connections in the ACE, using the Connections button.
Connections provide a link between user interface objects in your application. For example, you can make a connections between a push button and a window; once the connection is made, when the button is pushed, the window appears.
Adding a connection usually means that XVT-Design generates code and places it in the ACE editing window.
Connections
Brings up the Connection editing dialog (see following illustration).
This button is enabled only when the context is set to an object and tag that allows a connection. In other words, it is enabled only when the context is a menu item’s
Select event, a push button’s
Control event, or the application’s
Create event.
4-9
XVT-Design Manual
4-10
Figure 4.5.The Connection Dialog (Macintosh Platform)
The Connection dialog displays the object title and tag near the top to indicate the context for the connection. Radio buttons on the left indicate the action that will be executed when the event occurs:
Create User-defined Object
If this box is checked, the connection creates one of your application’s windows or dialogs. A list button, enabled only when this radio button is checked, indicates which one will be created.
From the list, choose the name of the object that the connection will create.
Create XVT Dialog
If this box is checked, the connection invokes one of the pre-defined
XVT dialogs. A list button, enabled only when this radio button is checked, shows the names of the pre-defined XVT dialogs:
Question
A dialog with a question icon, a message, and two or three buttons, used to query the application user.
Error
A dialog with an error icon, a message, and an OK button.
Note
A dialog with a note icon, a message, and an OK button.
Using XVT-Design
Message
A dialog with an information icon and a message, useful in low-memory or error conditions.
Save
A native save-file dialog, which allows the application user to enter a name for a file and to choose its directory.
Open
A native open-file dialog, which allows the application user to open a file.
Font
A dialog which allows the application user to choose a font and type style.
From the list, choose the name of the dialog that the connection will invoke.
Dialog Strings
To enter the message that the dialog displays, click the Dialog
Strings button. A small dialog opens; enter the message in the dialog’s edit control and click the OK button.
If the connection creates the XVT “Question” dialog, you can also enter titles for the three buttons in the dialog.
Tip:
Create External Object
If this button is checked, XVT-Design creates an external connection—that is, a connection to an object outside of the current project. You must supply the symbolic identifier for the object (for example,
WINDOW_101
), and click the appropriate radio button to indicate the type of the object.
To create a connection to an external object:
1. Click the Create External Object radio button.
2. Type the symbolic identifier of the object in the edit field.
3. Click the radio button that corresponds to the type of the external object—Modal Dialog, Modeless Dialog, Modal
Window or Window.
4-11
XVT-Design Manual
Close Object
If this button is checked, the action closes the window or dialog that contains the object. Typically this connection is used to dismiss a dialog or close a window when a button in that container is pushed.
Note:
Do Nothing
If this button is checked, the connection will not have any effect, and no code will be generated for it. This button is checked by default when the connection dialog is first opened for a context. To remove an existing connection, check this button.
Only the internal connection that XVT-Design uses for TestMode is removed. You must remove the connection’s action code from the
ACE by hand.
4.2.3.4. Using Other ACE Controls
The ACE includes four other push buttons for performing various operations:
4-12
Figure 4.6.Action Control Editor
Using XVT-Design
Layout
Brings up the layout window for the context object. If the context is
a menubar, the menubar editor opens. (See section 4.7.2 on page
Attributes
Opens the Attributes dialog for the context object.
Revert
May perform one of the three following actions (depending on what code is in the Text Box):
Revert to Previous
• Discards any changes you have made in the text editing pane.
The pane reverts to the text that was present when the context was last selected.
Revert to Default Code
• Reverts to default code. The pane reverts to the default code
(replaces the current content of ACE with default code).
Append Default Code
• Appends default code. XVT-Design supplies action code for some object/tag combinations. This “generic” code suggests what your application should do by default for the context.
This code appears in the text editing pane; you can edit it just as you would edit code you create yourself. After editing the code, you can restore the original generic code by clicking the
Default Code button. The default code is added at the end of any existing text.
Connections
When you create a connection, XVT records the connection in the project file. The action code is also added to the module’s source code so that the connection will occur when the application is generated.
4.2.3.5. Finding Text in Action Code
The Edit | Find command brings up a dialog box that allows you to set options that control a search through action code for the first match of a string that you specify. The search applies to the active
Action Code Editor (ACE).
4-13
XVT-Design Manual
When you click the Find button in the dialog, the Action Code Editor is positioned to the tag containing the match, and the matching text is selected. You may then edit the text, or perform any other XVT-
Design operations.
Use the Edit | Find Next command to find the next match; if you've moved to another tag, it finds the next match after that tag. In other words, it starts the search from the current position. Or, you can issue the Edit | Find command again, using the same or different options in the dialog box.
With both the Find and Find Next commands, the search doesn't go beyond the scope (see below). If no match is found, the position of the ACE is left undisturbed.
These are the controls in the Find dialog:
Search for
The text to be searched for.
Case Sensitive
If checked, the match is case sensitive; otherwise, it is case insensitive.
Whole Words Only
If checked, the text in the "Search for" field must match complete words. (That is, "break" will not match "breakfast".)
4.2.3.6. Controls in the Origin Groupbox
From Cursor
If selected, the match begins from the current caret position in the current action code.
Entire Scope
If selected, the match begins at the start of the scope, which is set by one of the following four radio buttons.
4.2.3.7. Controls in the Scope Groupbox
Project
If selected, the scope is the entire project. If Entire Scope is selected, the search begins with the first tag for the Application module and the "APP:Application" object; otherwise it begins with the current
4-14
Using XVT-Design
caret position. In both cases it ends with the last tag for the last object for the last module.
Module
If selected, the scope is the entire module. If Entire Scope is selected, the search begins with the first tag for the first object in the module; otherwise it begins with the current caret position. In both cases it ends with the last tag for the last object in the module.
Object
If selected, the scope is the entire object. If Entire Scope is selected, the search begins with the first tag for the object; otherwise it begins with the current caret position. In both cases it ends with the last tag for the object.
Tag
If selected, the scope is the entire action code for the tag. If Entire
Scope is selected, the search begins at the start of the action code; otherwise it begins with the current caret position. In both cases it ends at the end of the action code.
Find
When this button is pressed, the dialog is dismissed and the search begins.
Cancel
This button dismisses the dialog without starting a search.
4.2.3.8. Scanning a Project's Action Code
The Edit | Scan Tags command allows you to quickly review the action code for part or all of a project.
4.3. Creating Windows, Dialogs, and Controls
See Also:
XVT-Design provides tools for creating windows, dialogs, and controls graphically and interactively. You create and adjust these resources directly on your screen, and XVT-Design generates the appropriate resource description files.
For more information on the differences between windows and
dialogs, see Project Files on page 4-1.
4-15
XVT-Design Manual
4.3.1. Creating Windows and Dialogs
Tip:
Tip:
Note:
To create a new window:
1. Choose New Window from the Window menu. XVT-Design opens a new layout window.
2. Move and resize the window to suit your needs. The size and location of the layout window represent the size and location of the window resource you have created.
To create a new dialog:
1. Choose New Dialog from the Window menu. XVT-Design opens a new layout window.
2. Move and resize the dialog to suit your needs. The size and location of the layout window represent the size and location of the dialog resource you have created.
XVT-Design uses document-style layout windows to represent windows and dialogs of all types. This lets you easily adjust the position and size of these resources. In TestMode, and in your compiled application, the windows and dialogs are rendered appropriately for their type.
4.3.1.1. Modal Windows
XVT-Design supports the layout and generation of modal windows.
There is a Window Attributes radio button for Modal Window type.
And you can preview these windows in Test Mode.
The purpose of a modal window is to block the users’ interaction with any other application window except the modal window itself.
Modal windows have a different look-and-feel on each platform, because they conform with the required style of that platform’s window manager.
A modal window prevents user interaction with any other window of an application (including the parent window which may be modal itself) until some user-initiated action causes the modal window to be dismissed. When a user initiates a request for dismissal, the application must destroy the modal window by calling xvt_vobj_destroy
. After a modal window is destroyed, focus returns to the window which previously had focus.
Notes About Using Modal Windows
• Modal windows do not support menu bars.
4-16
Using XVT-Design
• When laying out a modal window, you must have a button inside the window with a connection to close the object.
Tip:
Why use Modal Windows?
Modal windows use several types of objects that are not available in dialogs. Specifically, modal windows can contain custom controls, text edits and child windows.
In addition, modal windows allow drawing operations (while dialogs do not).
To create a modal window
1. Create a window.
2. Click on its Attributes button in the ACE or, in the Layout
Editor, double-click in the background of the window.
Figure 4.7.Window Attributes dialog box
3. Click on the Modal radio button.
Modal Window Look-and-Feel
Modal windows are implemented using the native object best suited to providing modality on each platform. A
W_MODAL
window may have characteristics of a top-level window, a child window, or a dialog. Moreover, the look-and-feel of this object is platformspecific—it will have the physical appearance most appropriate for modality on a particular platform. Modal windows follow native look-and-feel guidelines for decorations (borders, system menus, etc.) and stacking order.
4-17
XVT-Design Manual
See Also:
For further information about Modal Windows, see the XVT
Portability Toolkit Guide, chapter 6.
4.3.2. Creating Controls
Tip:
Tip:
Tip:
To create one or more controls:
1. From the Controls menu, choose the control type.
(The custom control menu item has a hierarchical menu that lists all of the installed custom controls.)
2. Position the cursor in the upper left corner of the desired location.
3. Either click or drag the control into the desired size.
If you click to create the control, it will be of the standard size for this type of control.
4. Click and/or drag to create additional controls of this type.
5. To exit from this mode, choose Pointer (or another control) from the Controls menu.
To move a control:
Click and drag it with the pointer.
To change the size of a control:
1. Click the control once to select it.
2. Drag the small black rectangle near the lower-right corner of the control.
4.3.3. The Object Palette
Layout windows contain a palette of graphical toggle buttons which represent the various controls you can put in a window or dialog.
4-18
Using XVT-Design
Pointer
Check Box
Horizontal
Scroll Bar
Static Text
Text Edit
List Button
Group Box
Push Button
Radio Button
Vertical
Scroll Bar
Edit Control
List Box
List Edit
Custom
Control
Figure 4.8.The Object Palette
Tip:
Tip:
You can use these toggle buttons to create controls, instead of using the commands on the Controls menu. Clicking once on a toggle button in the palette is the same as choosing the corresponding control from the Controls menu. Once you click the toggle button, it remains active until you click a different button. This allows you to create a number of controls of the same type after clicking the toggle button once.
To create a control using the object palette:
1. Click the button of the desired control in the object palette.
2. Position the cursor in the upper left corner of the desired location.
3. Either click or drag the control into the desired size.
If you click to create the control, it will be of the standard size for this type of control.
The custom control toggle button behaves slightly differently than the other buttons.
To create a custom control using the object palette:
1. Click the custom control button in the object palette.
When you click the custom control button, a menu containing
4-19
XVT-Design Manual
4-20
the names of all of the currently installed custom controls drops down next to the button.
2. Click the appropriate name on the menu to choose a custom control.
Once you have chosen the control from the drop-down menu, you can create one or more of these controls just as you would create standard controls.
4.3.3.1. Hiding the Object Palette
Tip:
Tip:
Note:
By default, all layout windows contain an object palette when first opened. You can hide the object palette if you desire. For example, you may want to hide the palette after you have created all of the controls in the container, since you no longer need the palette.
To hide the object palette:
Choose Hide Object Palette from the Layout menu.
To show a hidden palette:
Choose Show Object Palette from the Layout menu.
The object palette is hidden on a per-window basis; i.e. you can show the palette in one window and hide it in another.
The presence or absence of the object palette does not affect your container’s appearance at runtime—it is part of the layout window, not of your container itself.
4.4. Layout Windows
A layout window in XVT-Design represents the actual window or dialog in your generated application.
The Layout menu includes various alignment and spacing commands to help you position controls in dialog boxes and windows. When you first create controls, you can position and/or size them manually by using the mouse or entering position and/or size values. Then you can fine-tune them using the layout commands.
4.4.1. Alignment
All alignment operations use the position of the first selected control as a reference point for lining up the other controls. For example, if you select push buttons 3, 2, and 1 (in that order), and then select
Align Left from the Layout menu, push buttons 2 and 1 line up along
Using XVT-Design
the left border of push button 3, because it was the first control selected.
Align Left
Aligns the selected controls along their left border. The position of the first control selected is the reference point for lining up the other controls.
Align Center
Aligns the selected controls along their horizontal center by moving them left or right.
Align Right
Aligns the selected controls along their right border.
Align Top
Aligns the selected controls along their top border.
Align Middle
Aligns the selected controls along their vertical middle by moving them up or down.
Align Bottom
Aligns the selected controls along their bottom border.
4.4.2. Spacing
Even Horizontal Spacing
Equalizes the horizontal spacing between the right-most and leftmost boundaries of the selected controls. If the controls would overlap, XVT-Design places them adjacent to each other horizontally, which increases the total distance between the rightmost and left-most boundaries of the selected controls.
Even Vertical Spacing
Equalizes the vertical spacing between the top-most and bottommost boundaries of the selected controls. If the controls would overlap, XVT-Design places them adjacent to each other vertically,
4-21
XVT-Design Manual
which increases the total distance between the top-most and bottommost boundaries of the selected controls.
Make Same Size
Makes all selected controls the same size as the first control selected.
Controls with the Standard Size attribute set may not be affected by this command, or may be affected in only one dimension.
4.4.3. Grid
The Grid command lets you superimpose a grid on a selected window or dialog box, to help you position controls. You can determine the spacing of the grid, and choose whether controls snap to it.
Grid Spacing
Sets the horizontal and vertical spacing of the grid in pixels (default setting: 8 x 8) or in characters. You can use any size pixel-based grid, depending on how you like to lay out your controls. Or, for greater portability, you can use a character-based grid. (See “Tip,” later in this section.)
Note:
Snap To Grid
Determines whether controls you create, move, or resize are automatically aligned to the layout grid. As you move a control, its position will jump to the nearest grid line intersection. As you change the size of a control, its right and bottom edges will jump to the nearest grid lines. This option is independent of the Display Grid option; controls can snap to a grid even if it is not displayed.
Controls that you have already placed in the layout window are not affected when you select this command, until you move or resize them.
Tip:
Display Grid
Determines whether the grid is displayed in the selected window or dialog box. This option is independent of the Snap To Grid option; you can display the grid without forcing controls to snap to the grid.
To ensure that your resources look good when you move your application to other platforms, we recommend that you use the character-based grid. When you move your project from one platform to another, this grid changes size, but the grid spacing is
4-22
Using XVT-Design
always the size of a character of average width and height in the system font (the default font used to draw labels in native controls).
If you use a character-based grid, your controls will map cleanly to coordinate systems on other platforms, and thus be properly aligned and spaced.
4.4.4. The Toolbar
Layout windows have a toolbar, with picture buttons corresponding to the most frequently used commands for creating and editing controls. Clicking a button on the toolbar has exactly the same effect as choosing the corresponding command from the menu.
4.4.4.1. Hiding the Toolbar
By default, all layout windows contain a toolbar when first opened.
You can hide the toolbar if you desire.
Tip:
Tip:
Note:
To hide the toolbar:
1. Choose Hide Toolbar from the Layout menu.
To show a hidden toolbar:
1. Choose Show Toolbar from the Layout menu.
The toolbar is hidden on a per-window basis; i.e. you can show the toolbar in one window and hide it in another.
The presence or absence of the toolbar does not affect your container’s appearance at runtime—it is part of the layout window, not of your container itself.
4.5. Setting Object Attributes
Tip:
In XVT-Design, the attributes for your application’s windows, dialog boxes, and controls are set with dialog boxes.
To invoke the attributes dialog box for an object:
1. Select the object (dialog box, window, or control).
2. From the Edit menu, choose Attributes.
-OR-
Double-click the object.
4-23
XVT-Design Manual
4.5.1. Common Attributes
The specific attributes that can be set vary depending on the type of object. The attributes that are common to all objects are described in this section. Object-specific attributes are described in the following sections, according to the type of object.
Title
Allows you to specify a particular title or name for an object. Each object’s title field is automatically filled in with a system-defined default name.
Caution:
Symbolic Identifier
Specifies a symbolic name for the resource ID of an object. These names for resource IDs are placed in a header file that is created when you invoke the Generate Application command. This header file is then included in the .url resource files and the .c source code files that need access to the resources.
A symbolic identifier lets you symbolically refer to a particular resource within your application code. This field is automatically filled in with a system-defined default name.
The default symbolic identifiers that XVT-Design creates are unique within a project. If you edit the symbolic identifier field, you must be sure that all symbolic identifiers are unique. You cannot have two objects with identical symbolic identifiers within a project.
X and Y coordinate locations
Specifies the position of an object. The X and Y (horizontal and vertical) coordinate values are specified in pixel units and refer to the position of the upper left-hand corner of the object. For controls, these values are set when you move the object in a layout window.
For windows and dialogs, these values are set when you move the layout window itself. You can also type them in edit fields in an attributes dialog.
Height and Width fields
Defines height and width values, in pixels, for a particular object.
For controls, these values are set when you changes the size of the object in a layout window. For windows and dialogs, these values are set when you change the size of the layout window itself. You can also type them in edit fields in an attributes dialog.
4-24
Using XVT-Design
Note:
Tip:
See Also:
Help Topic
Associates a help topic with the object. A list button shows all of the help topics in the current help text source file. To associate a topic with the object, select its name on the list button.
Once you have written a help text source file for your application, you must load it into XVT-Design before you can associate topics with objects.
To load a help text source file into XVT-Design:
1. Open the attributes dialog for any window, dialog, control, or menu item.
2. Choose the “<Load Help File>” item from the Help Topic list button in the attributes dialog. This invokes a standard open file dialog.
3. Open your help text source file in the open file dialog.
After you open the help text source file, XVT-Design scans the file, extracts all of the help topic titles in the file, and places them in the
Help Topic list button shown in the attributes dialogs.
For more information on XVT’s hypertext on-line help system, see the “Hypertext On-line Help” chapter of the XVT Portability Toolkit
Guide.
4-25
XVT-Design Manual
4.5.1.1. Fonts and Colors
You can set the control font and the control colors for the entire application, a individual container, or a particular control.
Set Color
Set Font
Figure 4.9.Window Attributes Dialog (Macintosh platform)
Tip:
Set Fonts
To set a font for a particular control,
1. Open the Attributes window.
2. Click on the Own Font box.
3. The Set Font button will be activated.
4. Click on the Set Font button.
The dialog box shown below will appear.
4-26
Using XVT-Design
Figure 4.10.Set Fonts Dialog (Win32 platform)
5. To select a portable font, click on any (or all) of the family, size or style options.
4-27
XVT-Design Manual
To select a platform-specific native font, click on the Use Native
Attributes button.
Figure 4.11.Native Fonts Dialog (Win32 platform)
4.5.1.2. Set Colors
Tip:
To set a color for a particular control,
1. Open the Attributes window.
2. Click on the Own Color box.
4-28
3. Click on the Set Color button.
Using XVT-Design
Figure 4.12.Set Colors Dialog (Macintosh platform)
Note:
Note:
In the diagram above, the Highlight, Border, Trough and Select components do not have a color swatch visible to the right of the option. No swatch signifies that the component inherits its color from its parent.
4. Click on the component whose color you want to change.
5. Then click on the Own Color radio button.
6. Then click on the Predefined list box and choose the color you want.
To create your own color,
7. Once you have chosen the predefined color, move the scroll bars or enter numbers for the values that comprise the color.
Most systems cannot display all possible colors. XVT recommends the use of predefined colors whenever possible for greatest portability.
4-29
XVT-Design Manual
4.5.2. Control Attributes
4-30
Figure 4.13.Attributes Dialog for Controls (Motif Platform)
Standard Size
Sets a control to be the standard height, which is predefined for this type of control on this platform. On each platform, standard size is the native or “natural” size for a control of a certain type.
If the standard size attribute is set, you can change only the width of a control, since the height is predefined. The exception to this is the vertical scrollbar control, where the width is predefined and you can change only the height.
To change the size in both dimensions, turn off standard size.
Standard size for a control is set if you simply click to create the new control. If you drag off the Tool Palette to create the control, the standard size attribute is not set. The standard size attribute applies to all controls except list boxes, group boxes, and custom controls.
Default
Sets a push button control to respond to the default choice. The default button is automatically activated when the user presses
Return; it is typically titled “OK”.
Only one push button can be the default. If you have set the default attribute for one push button, then attempt to set the default attribute for a second push button, the first push button’s default attribute will be set to Normal. Setting the default attribute also affects the creation order for controls, as explained later in this chapter. The default attribute applies to push button controls in dialog boxes only.
Using XVT-Design
Cancel
Sets a push button control to respond to the cancel choice. This is the control that is automatically activated (on many platforms) when the user presses Esc; it is typically titled “Cancel”.
If you have set the cancel attribute for one push button, and then attempt to set the cancel attribute for a second push button, the first push button’s cancel attribute will be set to Normal. The cancel attribute applies to push button controls in dialog boxes and modal windows.
See Also:
Initial State
These checkboxes determine the state of the control when it is created at application runtime.
Invisible
Sets a control to be initially invisible.
Selected
Sets a check box or radio button to be initially selected, or checked. This attribute applies to check box and radio button controls only.
Disabled
Sets a control to be initially disabled. The control is grayed out so that it is unselectable.
The xvt_vobj_set_*
functions, described in the XVT Portability Toolkit
Guide, are useful for changing the state of controls at application runtime.
Selection
These radio buttons determine whether the application user can make single or multiple selections in a list box, or whether the list box is read-only (i.e. no selections can be made). This attribute applies to list box controls only.
Justification
Sets whether a control’s text label will be left-, center-, or rightjustified (when possible for a particular toolkit). This attribute defaults to native justification, which tells XVT to use whatever justification is used by default by the native platform. The justification attribute applies to all controls except scrollbars, list boxes, and custom controls.
4-31
XVT-Design Manual
Note:
The conventions and capabilities for control label justification vary from platform to platform. Individual platforms may or may not adhere to this attribute’s setting.
4.5.3. Custom Controls
Custom controls do not have a fixed set of attributes. To distinguish them from the standard XVT controls, the attributes of a custom control are referred to as properties. Each type of custom control has its own set of properties, although some properties are common to most types of custom controls (such as size and location).
Properties are displayed and changed in the custom controls dialog:
4-32
Figure 4.14.Custom Controls Dialog
Tip:
To set a property’s value:
1. Select the name of the property in the list box.
The current value of the property is displayed in the list edit above the list box.
2. Type the new value for the property in the list edit
OR
Choose a new value from the list edit’s pull-down list.
Not all properties of all custom controls have values in the pulldown list. For instance, a size attribute would be unlikely to have a pull-down list of values, since all integers from one to the maximum size of the control would have to be listed.
Using XVT-Design
Tip:
Tip:
To restore the previous value of the property:
1. Click Undo.
To dismiss the dialog:
1. Click OK to save your changes and dismiss the dialog
OR
Click Cancel to dismiss the dialog and discard all of your changes.
At startup time, XVT-Design loads the properties for each custom control from Control Description Files.
4.5.3.1. Control Description Files (CDF)
A CDF file describes the properties that may be set in XVT-Design
for a custom control that is created in a window. See Creating
Controls on page 4-18 for information on how a custom control is
created.
File Names
For a custom control named ccname, the CDF file must be named ccname.cdf. The ccname part of the name becomes the class name.
When referring to the custom control name internally, XVT-Design converts it to lower-case. We recommend that you use an entirely lower-case file name on case-sensitive systems like UNIX.
The custom control can also have an image (bitmap) that is used by
XVT-Design to render it, at design-time only (not runtime); it must have the name ccname.bmp and be in the same directory as the CDF.
Again, the file name should be all lower-case on case-sensitive systems.
File Location
When it starts up, XVT-Design builds a list of all available custom controls by scanning for file names with a .cdf extension. The following directories are scanned:
1. The current directory.
2. The directory containing the configuration (design.cfg) file.
3. The directory defined by the XVTCDF attribute, if the configuration file, design.cfg, contains such a definition.
4. The directory defined by the XVTCDF environment variable, if the environment contains such a definition.
4-33
XVT-Design Manual
If duplicate file names are found (using a case-insensitive comparison), the first occurrence is taken.
Custom Controls Without CDF Files
To create a custom control in a window, you are not required to have a CDF file. (This maintains compatibility with earlier versions of
XVT-Design.) If you do not have a CDF file, choose "Other..." from
the custom control menu. (See Creating Controls on page 4-18.)
You will be prompted to enter the class name before you can drag out the custom control in the window. Once a class name is entered in this way, and you place a custom control of that class in a window, it will appear on the custom control menu, although it still won't have a CDF file. You will be able to set values for standard properties (e.g., TITLE and HEIGHT) via the Custom Control
Attributes dialog.
To set control-specific attributes for the control, type into the ACE for the tag "SPCL:Instance Data," following the rules for that particular control. If you subsequently provide a CDF file for the control, XVT-Design automatically moves properties defined for the control from the action code for the "SPCL:Instance Data" tag to the Custom Control Attributes dialog when you bring up the Custom
Control Attributes dialog. Any properties not defined in the CDF file are left in the action code.
Forming the Attributes for the Custom Control
At runtime, XVT-Design automatically generates appropriate data and code to pass properties and values to the custom control when it is created. From the custom control's perspective, properties and their values are stored in attributes.
The application developer may specify properties in the Custom
Control Attributes dialog (those defined in a CDF), as action code for the "SPCL:Instance Data" tag, or in both places. One reason that both places might be used is that some properties may have values
(e.g., running text) that do not fit the property/value model used by
CDF files.
XVT-Design always places properties and values from the Custom
Control Attributes dialog first in attributes, followed by text supplied as action code.
Text entered as action code is not reformatted, and appears exactly as entered, one line of instance data per line of action code
(following any CDF properties).
4-34
Using XVT-Design
The following standard properties that always appear in the Custom
Control Attributes dialog are not also set as instance data, although they are available to the custom control via other means (see XVT
Technical Note #148):
Title
Control_ID
X
Y
Width
Height
Format of a CDF File
A CDF file consists of property descriptions, one per property. One property description is separated from the next by one or more blank lines. Comment lines start with a # (in column one) and can appear anywhere.
A property description consists of up to four fields. The first three
(Name, Type, and Default) are one per line. The fourth (Description) can be on multiple lines. The fields must be in the order Name, Type,
Default, and Description. All but the Name are optional.
Here are details on the fields:
Name
The name of the property, limited to letters (case insensitive), digits, and the underscore.
Type
One of the following: boolean, color, enum, int, or string.
Default
The default value, used when initially populating the Custom
Control Attribute dialog.
Description
One or more lines of descriptive text, up to 500 characters in length, that could be displayed when the property is selected in the Custom
Control Attributes dialog. (This feature is not currently implemented, so no Description text is displayed and the field may be entirely omitted.)
4-35
XVT-Design Manual
The type (e.g., string) can be optionally followed by a colon and a comma-separated list of values used to populate a drop-down list; from this list you can select a value. Or, you can enter the value in the edit control. With the exception of the enum type, an entered value need not match a value in the drop-down list, as long as the value is legal for the type (see next section).
Spaces are ignored within a CDF line, except within a Default value or Description text.
Property Types
The type of a property determines the values that you can enter in the edit field within the Custom Control Attributes dialog. Validation of the value occurs when the value is accepted in the dialog, not while the value is typed, (i.e., when another property is selected or the dialog's OK button is clicked). These types and their allowed values are:
boolean
A Boolean value, which must be TRUE, FALSE, T, or F (case insensitive).
color
A color value, either three decimal numbers (0 through 255) separated by commas that give values for the red, green, and blue components, or one of the following symbols (case insensitive):
RED, GREEN, BLUE, CYAN, MAGENTA, YELLOW, BLACK,
DKGRAY, GRAY, LTGRAY, or WHITE.
enum
An enumerated value, which behaves like a string value, except that the value must match one of those listed after the type in the property description (e.g., "enum: TOP, LEFT, BOTTOM, RIGHT")
int
An integer value, which consists of a string of digits (0 - 9) optionally preceded by a sign (+ or -).
string
A string value, which consists of up to 255 arbitrary characters.
4-36
Using XVT-Design
4.5.3.2. Example CDF
# CDF for Calendar custom control.
#
VIEW enum: DAILY, WEEKLY, MONTHLY
MONTHLY
BACK_COLOR color
GRAY
TEXT_COLOR color
BLACK
RULE_COLOR color
BLUE
START_YEAR int
1980
END_YEAR int
2010
HEADING string
LANG enum: English, French, Spanish, German
English
MSG string: Choose date, Pick date, Select date, Click on choice
Choose date
4.5.4. Text Edit Attributes
The following attributes apply to text edit objects only. For more information regarding text edit objects, see the XVT Portability
Toolkit Guide.
4-37
XVT-Design Manual
4-38
Figure 4.15.Attributes Dialog for Text Edit Objects (Win32 Platform)
Initial Text
The text shown in the text edit object when it is first displayed at application runtime. (This attribute is the same as the Title attribute for other objects.)
Autohscroll
Enables automatic horizontal scrolling of the text edit object when the user drags the mouse outside of the view rectangle.
Autovscroll
Enables automatic vertical scrolling of the text edit object when the user drags the mouse outside of the view rectangle.
One Paragraph
Limits the entered text to one paragraph. A paragraph is terminated with a carriage return. When this attribute is set, the paragraph is limited to the number of characters entered in the Char Limit field.
Word Wrap
Keeps words together and wraps them to the next line when there is not enough room on the first line (as determined by the number of pixels specified in the Margin field).
Using XVT-Design
Overtype
Determines whether the text edit object is initially in overtype mode.
In this mode, typed characters overwrite existing text. If this attribute is not set, the text edit object defaults to insert mode.
Border
Places a border around the text edit object.
Cut
Allows users to cut text from the text edit object.
Copy
Allows users to copy text from the text edit object.
Paste
Allows users to paste text into the text edit object.
Enable Menu
Determines whether the text edit system will enable and disable the commands on the Edit menu of the window that contains the text edit object. Do not check this attribute if the window’s menubar does not have an Edit menu.
Enable Clear
Causes the Clear menu item to be always enabled when the text edit object is active.
Read-only
Sets the text in the text edit object to be read-only (unselectable).
Margin
Sets the maximum number of pixels allowed per line when Word
Wrap is enabled, thereby determining the right margin.
Char Limit
Sets the limit for the number of characters that can be entered in the text edit object, if the One Paragraph attribute has been set.
4-39
XVT-Design Manual
4.5.5. Dialog Box Attributes
Type: Modal/Modeless
This control sets the type of the dialog box being created as either modal or modeless.
Invisible
Sets the dialog to be initially invisible. It can be made visible in the application by calling the XVT function xvt_vobj_set_visible
.
Disabled
Sets the dialog to be initially disabled. It can be enabled in the application by calling the XVT function xvt_vobj_set_enabled
.
Callback Class
Specifies the class name for a dialog. If you enter a name in a dialog’s callback class edit field, or select a name from the callback class list, XVT-Design generates function calls for all of the dialog’s tags, with names based on the class name. This lets you easily use classes of functions defined in external files.
The function calls are inserted in each tag’s action code, unless you have already entered code for that tag. XVT-Design will not overwrite code that you have entered before you set the callback class of a dialog.
Own Color
Allows you to change the colors of the dialog.
Example:
Own Font
Allows you to change the fonts of the text in the dialog.
Suppose you set the callback class attribute of a dialog to be
“MyCl”. In the action code for the dialog’s Create event tag,
XVT-Design puts the following function call: xd_dlg_MyCl_Create(xdWindow, xdEvent, 0L);
4-40
4.5.6. Window Attributes
Using XVT-Design
Figure 4.16.Attributes Dialog for Windows (Win32 Platform)
Example:
Callback Class
Specifies the callback class name for a window. If you enter a name in a window’s callback class edit field, or select a name from the callback class list, XVT-Design generates function calls for all of the window’s tags, with names based on the class name. This lets you easily use classes of functions defined in external files.
The function calls are inserted in each tag’s action code, unless you have already entered code for that tag. XVT-Design will not overwrite code that you have entered before you set the callback class of a window.
Suppose you set the callback class attribute of a window to be
“MyCl”. In the action code for the window’s Update event tag,
XVT-Design puts the following function call: xd_win_MyCl_Update(xdWindow, xdEvent, 0L);
Initial State:
Invisible
Sets a window to be initially invisible. It can be made visible in the application by calling the XVT function xvt_vobj_set_visible
.
4-41
XVT-Design Manual
Disabled
Sets a window to be initially disabled. It can be enabled by the application by calling the XVT function xvt_vobj_set_enabled
.
Maximized
Sets a window to be initially maximized.
Type
Sets the window’s type. There are three types of borders available:
Document, Double Border, and Plain border.
Modal
Modal windows are windows that force the user to address an issue raised in the window before continuing.
Place Exact
If the Modal radio button is clicked, the Place Exact box becomes available. The Place Exact button sets the
WSF_PLACE_EXACT
flag in the attribute flag of a window creation call. This function allows you to overwrite default window behavior that a particular platform might enforce.
See Also:
Colors/Fonts
Control colors and fonts can be specified at the window level.
For details on how to specify a color or font, see Fonts and Colors on page 4-26.
4.5.6.1. Attributes that Affect Only Document-Type Windows
The following attributes affect only windows with their type attribute set to Document.
Close Box
Determines whether a window’s decoration includes a close box.
Iconized
Sets a window to be initially iconized (minimized). This affects only applications that run on the Win, PM, and Motif platforms.
4-42
Using XVT-Design
Note:
Maximized
Sets a window to be initially maximized. Motif platforms ignore this setting.
The Iconized and Maximized attributes are mutually exclusive— setting one clears the other.
Capabilities
These checkboxes affect the border controls on the window.
Checking the attribute’s box indicates that the control is present.
Iconizable
Determines whether a window can be iconized. This affects only the Win, PM, and Motif platforms.
Sizeable
Determines whether a window’s decoration includes size controls.
Vertical Scrollbar
Determines whether a window includes a vertical scrollbar. XVT-
Design knows that scrollbars are included in windows; activating this button allows you to attach
HScroll
attribute to the window.
Horizontal Scrollbar
Determines whether a window includes a horizontal scrollbar. XVT-
Design knows that scrollbars are included in windows; activating this button allows you to attach
VScroll
attribute to the window
4.6. Specifying Creation Order
Tip:
On the Edit menu, the Creation Order command lets you specify the creation order for controls within the currently active dialog box or window. When a user navigates an application by pressing keys, the creation order for controls determines the order in which the controls are traversed. Also, the creation order determines which of one or more overlapping controls will be drawn “in front” of the others.
To view or edit the creation order for controls:
1. Select a window or dialog box.
4-43
XVT-Design Manual
2. From the Edit menu, choose Creation Order.
A dialog box shows the control names and their current traversal order.
4-44
Figure 4.17.The Creation Order Dialog (Windows Platform)
Tip:
Note:
Tip:
The current traversal order reflects the order in which you created the controls, except for two cases:
• Any push button control with the Default attribute automatically appears in the first position
• Any push button with the Cancel attribute automatically appears in the second position.
To rearrange the current order:
1. Select the name of the control to be moved.
2. Click the Up, Down, Top, or Bottom button to move the control to a new position.
Up, Down
Moves the selected control name one position up or down.
Top, Bottom
Moves the selected control name to the top or bottom of the list.
If any push buttons have the Default or Cancel attribute set, another control cannot move to the top of the list.
Selecting a control in the Creation Order dialog also selects the control in the layout window. This is useful for finding controls that have been obscured by other controls. Also, double-clicking on a control’s name in the Creation Order dialog opens the control’s attributes dialog.
Using XVT-Design
4.6.1. Keyboard Navigation in Windows
See Also:
Keyboard navigation is the use of keyboard input instead of mouse pointing and clicking to interact with GUI objects. Generally, native look-and-feel for keyboard navigation includes using the Tab key and Shift-Tab key (back-tab) to traverse through controls in a window or dialog. Alternatively, the user may type character keys
(associated with mnemonic characters) to select an object directly.
A mnemonic character is preceded by a tilde (
~
) in the title text and displayed with an underline to users. (“Title text” refers to the title field of the control attribute dialog.) Groups of controls (such as radio buttons) may be traversed with Arrow keys.
Unlike XVT dialogs which automatically provide keyboard navigation to users, XVT windows require special handling to implement keyboard navigation. The
XVT_NAV
navigation object encapsulates the navigation list of controls, child windows, and custom controls for a particular window. The navigation object allows you to specify the navigation order for your application’s windows. Any control mnemonic character set in the control’s title will be processed automatically on the XVT/Win32 platform where control mnemonics are supported in native look-and-feel.
Navigation is provided by checking the “Navigation” checkbox in the window attribute editor. You do not need to create the
XVT_NAV navigation object.
For detailed information about the xvt_nav_*
functions, refer to their descriptions in the XVT Portability Toolkit Guide.
4.6.1.1. Add Keyboard Navigation to a Window
To add keyboard navigation to a window,
1. Open the window’s Attributes dialog.
2. Click on the Keyboard Navigation button.
4-45
XVT-Design Manual
Keyboard
Navigation
4-46
Figure 4.18.Keyboard Navigation box
4.6.2. Radio Button Groups
Radio buttons, by definition, are combined into groups. Only one radio button in a group can be checked at a time, allowing the application user to choose one of several alternatives. XVT-Design automatically generates code to handle radio button groups.
A group of radio buttons consists of two or more radio buttons with consecutive creation order within a container (window or dialog). If one container has two or more groups, the groups must be separated in the creation order list by at least one control of any type other than a radio button.
The position of the radio buttons within a container has no effect on their grouping. The position of other controls in the container, including group boxes, does not affect radio button groups either.
Only the creation order of the controls dictates the grouping of radio buttons. This allows you to lay out the controls without restriction.
4.6.2.1. Creating and Using Radio Button Groups
Since radio button groups are determined only by creation order, you can lay out your controls with XVT-Design first, then determine their grouping later. Of course, you should group radio buttons visually as well as functionally, so that your application user understands how to operate the controls.
Group boxes and static text controls are useful for separating radio button groups because either the group box title, or the static text, can describe the radio button group to the user. At the same time,
Using XVT-Design
Example:
you can use the group box or static text to programmatically separate the group from other groups, by placing it after the radio group in the creation order of the controls. Use the Creation Order command on the Edit menu to adjust the creation order of the controls.
The following figure shows a dialog box, with two radio button groups, as it would appear in an executing application:
Figure 4.19.Dialog with Radio Button Groups (Macintosh Platform)
The first group contains two radio buttons, while the second contains three. The user can choose one of two kinds of containers, and one of three flavors. Unlike the radio buttons, the Toppings check boxes do not operate as a group—one, both, or neither can be checked.
The next illustration shows the creation order for the controls in this dialog:
Figure 4.20.Creation Order for Radio Buttons (Macintosh Platform)
4-47
XVT-Design Manual
Notice that the group boxes (Container and Flavor), which visually surround and delimit the radio button groups, follow the radio buttons in the creation order list. Because of their position in the creation order of the dialog’s controls, they functionally separate the two radio button groups.
4.6.2.2. Responding to Radio Button Events
XVT-Design creates code for radio button groups when you generate source files for your application. When the application user clicks a radio button in a group, this code checks that button and unchecks the previously checked button. You do not have to write any code to implement this behavior.
Although XVT-Design generates code that implements the visual behavior appropriate for radio button groups, you must write the code that responds to the
E_CONTROL
events generated by the application when the user manipulates the radio buttons.
4.7. Using the Menu Editor
With XVT-Design, you can design multiple menubars for your application. Each menubar can have hierarchical menus that descend from it. To help you understand menus in XVT, here are some basic definitions:
Menubar
A menubar is the “root” of the menu hierarchy tree. To design menus, you must start with a menubar. A menubar, which consists of a list of menus, is visually represented by a row of names across the top of a screen or window.
Menu (also called a pull-down menu)
Menus appear horizontally across a menubar. When you click on a menu (or select it via a keyboard mnemonic), it “pulls down” a vertical list of items for you to choose from. A menu can contain submenus.
Menu item
Menu items appear on a menu or submenu. A menu item can be a “leaf” of the menu tree, in which case it causes an
E_COMMAND
event to be delivered to the application. Or, it can be another submenu whose contents are displayed when the user drags the mouse to this item.
Hierarchical menu
A hierarchical menu has one or more submenus. Such a menu/
4-48
Using XVT-Design
submenu arrangement is hierarchical because it can contain several nested levels of menus.
Submenu
A submenu is just like a menu, except that it can appear anywhere in your menu hierarchy. When a submenu appears as an item on a menu (or submenu), some graphical indication— such as an arrow—is used to show that the menu hierarchy extends below this item. When the user pulls down a menu and moves the mouse to a submenu, the list of menu items for that submenu appears.
Figure 4.21.Hierarchical Menu with Submenu (Macintosh Platform)
In the illustration above, the menubar consists of the File, Edit,
Choices, Font, and Style menus. The Choices menu is a hierarchical menu; its submenu is titled “From Menu”. The From Menu submenu has two menu items, titled “Hello” and Goodbye”.
4.7.1. Menubar Editor
Tip:
You can create new menubars and edit their menu hierarchies by using the Menubar Editor.
To invoke the Menubar Editor:
From the Tools menu, select Menubar Editor.
The Menubar Editor dialog appears.
Figure 4.22.The Menubar Editor (Macintosh Platform)
4-49
XVT-Design Manual
The Menubar Editor consists of a dialog containing a list box, an edit control, and several push buttons. The list box shows the names of all menubars in your project. To select a menubar, click on its name.
The push buttons apply different actions to the selected menubar.
The Menubar Editor dialog contains the following controls:
Rename
Changes a menubar’s symbolic identifier. To do this, select the menubar in the list box and type the new name in the edit control.
Then click the Rename button.
New
Creates a new menubar. The name of the new menubar is added to the list.
Clear
Deletes the selected menubar. The menubar is permanently removed from the project, and it is not copied to the clipboard.
Edit
Invokes the Menu Editor for this menubar (see “Menu Editor” below).
Done
Dismisses the Menubar Editor.
4.7.2. Menu Editor
When you invoke the Menu Editor for a new menubar, a list box appears containing the four standard menus: File, Edit, Font, and
Help. The menus are listed in left-to-right order.
4-50
Using XVT-Design
Figure 4.23.The Menubar Editor (Macintosh Platform)
Cut
Deletes the selected menu or menu item and puts it on the clipboard.
Copy
Copies the selected menu or menu item to the clipboard.
Paste
Inserts the contents of the clipboard after the selected menu or menu item.
Clear
Deletes the selected menu item without putting it on the clipboard, thereby permanently deleting it.
Attributes
Invokes the Menu Attributes dialog, where you can set various attributes for a menu, menu item, or submenu (see “Menu
Attributes”).
Userdata
Invokes the Userdata Editor, where you can associate up to six strings of arbitrary text with a menu, menu item, or submenu.
4-51
XVT-Design Manual
Add Menu/Edit Menu
Invokes the Menu Editor again, so you can descend to the next level below the selected menu item. This button reads “Edit Menu” if the object selected in the list box has a submenu, and reads “Add Menu” otherwise.
Up/Down
Moves the selected menu or menu item either one position up, or one position down in the current menu. (If you are editing a menubar, moving a menu up corresponds to moving it left on the menubar.)
Note that you cannot position any items in front of the Standard File or Standard Edit menus, and you cannot position any items after the
Standard Font or Standard Help menus.
New
Creates a new menu or menu item, inserting it after the currently selected menu item.
4-52
Figure 4.24.Menu Editor Showing a New Menu (Macintosh Platform)
Separator
Inserts a separator bar after the currently selected menu item. You can insert separators only into menus and submenus; you cannot insert them on the menubar.
Using XVT-Design
Std (Standard) Menus
Brings up a dialog from where you can select which standard menus you want. The standard menus (File, Edit, Font, Help) can be selected only for a menubar, not its submenus.
Figure 4.25.Dialog for Selecting Standard menus (Macintosh
Platform)
Done
Dismisses the Menu Editor dialog. You can also dismiss the dialog by clicking its close box.
4.7.3. Menu Attributes
When you click Attributes for a menu or menu item, the Menu
Attributes dialog is displayed.
4-53
XVT-Design Manual
4-54
Figure 4.26.The Menu Attributes Dialog (Macintosh Platform)
The controls in the Menu Attributes dialog are described below.
When you invoke the dialog for a menu (rather than a menu item), all of the controls except Title, Menu ID, Mnemonic, and Help
Topic are disabled.
Title
The text for this menu or menu item.
Menu ID
The symbolic identifier for this menu or menu item.
Mnemonic
Specifies the one-character mnemonic you wish to associate with this menu or menu item. At run-time, the mnemonic can be used on those platforms that support keyboard navigation of menus. The mnemonic character must be one of the characters in the title of the menu or menu item.
Accelerator
Specifies the one-character accelerator key that you wish to associate with this menu item. At run-time, the accelerator can be used as a substitute for selecting the menu item with the mouse.
Using XVT-Design
Keys
Brings up the Accelerator Keys dialog, where you can specify a function key as the accelerator for this menu item. When you choose one of the keys, its full name is inserted in the Accelerator edit field.
Alt/Control/Shift
If you have selected an accelerator for this menu item, you can specify the modifier keys (Alt, Control, or Shift) to be used with the accelerator key.
Checkable
Specifies that this menu item can be checked.
Checked
Specifies that this menu item should initially be checked.
Disabled
Specifies that this menu or menu item should initially be disabled.
The item can be enabled by the application with the XVT API function xvt_menu_set_item_enabled
.
4.8. String Resources
4.8.1. Strings
Tip:
In XVT-Design, you can create and manipulate strings and string lists, to be used as resources from within an XVT program. The advantage of string resources is that you can maintain strings outside your executable program. As a result, you can modify them without having to recompile the program.
Strings and string lists are useful for adding text to your application that would not otherwise be in its resources. For instance, you could use a string list to initialize a list box or list button. String resources are also useful for holding text that may change when the application runs. As an example, you could have a button with the title “Find”, that changes to “Find Again” at some point during execution. The second string, “Find Again”, could be stored as a string resource.
To create a string:
4-55
XVT-Design Manual
1. From the Tools menu, choose Strings Editor.
The Strings dialog box appears.
Figure 4.27.The Strings Dialog (Windows Platform)
2. Click New String.
A new string is created, whose contents are initially “New
String”. The String Edit dialog box appears, in which you can change both the string and the symbolic identifier.
3. Change the string and/or its symbolic identifier, and click OK.
4-56
Figure 4.28.The String Edit Dialog (Windows Platform)
In your application, add a call to xvt_res_get_str
to retrieve the string at run time. The function prototype for xvt_res_get_str
is: char *xvt_res_get_str(int rid, char *s, int sz_s)
For the first argument, simply use the symbolic identifier for the string you want (in the above example, you would use
STR_ALIGNRT
). You must allocate a buffer large enough to hold the string and pass the address of the buffer, as well as the buffer’s size, as the second and third arguments.
4.8.2. String Lists
String lists are useful if you have a list of names or labels that you would like to enumerate outside of your application. Let’s say you
Using XVT-Design
Tip:
Example:
had a list containing the names of all the states in the United States.
In your application, you could then retrieve the list as a whole, and populate a list box with the resulting list.
To create a string list:
1. From the Tools menu, choose Strings Editor.
2. In the Strings dialog, click the New List button.
A new string list is created, and the String List dialog appears.
In the String List dialog box, the symbolic identifier, which you can change, appears at the top. For example, you might change this to be
“
SL_USA
”).
When you click the New String button, a new entry with the contents
“New String” is created, and the String List Edit dialog appears.
Change the contents of the string (perhaps to something like
“Arizona”), and click OK.
Click New String again (which creates another “New String”), and change it to “Alabama”. Clicking New one more time creates another string that you could change to “Georgia”.
To arrange your strings in ascending alphabetical order, you can reorder your string list. To reorder an item, select the one you would like to reorder (in our example, “Alabama”), and click Up. Alabama is now in the first position, and Arizona in the second. You could have selected any item and used the Up and Down buttons to change its position in the string list.
The result is a string list whose symbolic identifier is “
SL_USA
”, and whose contents are the three strings “Alabama”, “Arizona”, and
“Georgia”. To retrieve the entire string list into your application program, call xvt_res_get_str_list,
whose function prototype is the following:
SLIST xvt_res_get_str_list(int rid_first, int rid_last)
The two arguments to xvt_res_get_str_list are the symbolic identifiers for the list (“
SL_USA
”); “
_FIRST
” and “
_LAST
” are appended respectively. Your call to xvt_res_get_str_list
would therefore look something like this:
SLIST x; x = xvt_res_get_str_list(SL_USA_FIRST, SL_USA_LAST);
Following the call to xvt_res_get_str_list
, the contents of the SLIST x will be the strings you created using XVT-Design.
4-57
XVT-Design Manual
4-58
4.9. Userdata Strings
Example:
See Also:
XVT-Design’s Userdata feature lets you associate arbitrary data (up to six text strings) with any control, dialog box, window, or menu you create. For instance, you could associate textual data with a dialog box control.
Imagine an application in which a user could perform various queries on a separate database program by pressing buttons in a dialog box. With XVT-Design’s Userdata feature, you could associate the query commands needed for the database with a particular control in the dialog box. Then you could write C code that would send the associated userdata strings (the query commands) to the database, whenever the control was selected.
Userdata is stored in the application’s URL file. As a result, you can change the userdata for an application without recompiling the application.
XVT-Design lets you create and edit userdata to be associated with an object. You can also change the labels that are associated with the userdata items themselves.
The XVT API provides three functions for accessing the userdata you have created with XVT-Design:
• xvt_res_get_dlg_data
• xvt_res_get_win_data
• xvt_res_get_menu_data
See the XVT Portability Toolkit Guide for more details.
4.9.1. Creating Userdata
Note:
There are two ways to invoke the Userdata window for creating and editing userdata strings:
• Select an object (window, dialog, or control) in a layout window, and choose Userdata from the Edit menu
• Select a menu or menu item in the Menu Editor, and click the
Userdata button
In the Userdata window, you can create or modify six different userdata strings. These are the userdata strings that will be associated with the object you have selected.
Before using the Userdata command on a window or dialog box, make sure that no controls are currently selected within the window or dialog box.
Using XVT-Design
Figure 4.29.The Edit Userdata Window (Macintosh Platform)
4.9.2. Editing Userdata
The Userdata window contains a list button and a scrollable text edit pane. The list button contains the labels of the six userdata strings
(see below). To choose one of the six userdata strings for editing, select the appropriate label from the list button.
The text edit pane contains the text of the userdata string indicated by the list button. You can enter an unlimited number of lines of userdata for each userdata string. Userdata can include newlines, which show up as “\n\” in the URL file.
4.9.3. Userdata Labels
Tip:
In the Edit Userdata window, userdata labels are associated with userdata strings. Userdata labels are simply titles or descriptions of each of the six userdata strings that can be associated with objects.
The default userdata labels are “Userdata 0”, “Userdata 1”, ...
“Userdata 5”.
Userdata labels only appear in XVT-Design’s Edit Userdata window. They are not placed in the generated source code or URL files. The labels are just to remind you what a particular userdata string means.
You can create labels before you have created a window, dialog box, menu, or control. You can also change the userdata labels even if you have not created any of these objects. You can edit userdata labels without having to edit the userdata itself.
To edit userdata labels:
1. From the Edit menu, choose Userdata Labels.
The Edit Userdata Labels dialog box appears.
4-59
XVT-Design Manual
4-60
Figure 4.30.Edit Userdata Labels Dialog (Macintosh Platform)
2. In the Edit Userdata Labels dialog, select a label in the list box.
3. Click Edit (or double-click the label).
The label appears in the edit field.
4. Edit the label, then click Replace to change the label.
Edit
Puts the selected label into the edit field.
Replace
Replaces the existing label with your new label.
OK
Accepts the changes that you have made to the labels and removes the dialog box. After you click OK, any future Edit Userdata window that you bring up displays the new userdata labels above each of the six userdata strings.
Cancel
Removes the dialog box without applying the changes you have made to the userdata labels.
4.9.4. Generating Code with Userdata
When you generate an application, the userdata is written to the project URL file as a userdata
statement in a dialog
, window
, or menu
definition. If the userdata is associated with a control, the
Using XVT-Design
userdata
URL statement follows the control definition in the
URL file.
4.10. TestMode
Note:
XVT-Design’s TestMode lets you verify the appearance of your application’s user interface without compiling or linking. TestMode emulates your application’s appearance at runtime, as if you had compiled, linked, and executed it.
During TestMode, XVT-Design’s user interface is replaced with your application’s. Instead of seeing XVT-Design’s windows and dialogs, you’ll see those of your project.
In TestMode, your project’s menus, windows, dialogs, and controls behave as if your application were actually running. If you induce any events for which you have defined connections (for example, choosing menu items or manipulating controls), the actions for those connections are executed. You can open windows by choosing menu items, create or destroy dialogs by clicking push button controls, and so forth.
If you use XVT-Design on more than one platform, you can use
TestMode to check your application’s appearance on each platform.
XVT-Design’s project files are portable across all supported platforms.
Keep in mind that XVT-Design only keeps track of connections in
TestMode. It does not interpret or execute your program’s code.
TestMode ignores any code you have entered with the ACE. You do not need to generate any source files before using TestMode. The presence or absence of generated files has no effect.
4.10.1. Entering TestMode
Tip:
To test your project:
1. From the Tools menu, choose Enter TestMode.XVT-Design hides its menubar and any open windows and dialogs. The task window and its menubar are replaced with your project’s task window and menubar. A special “TestMode” menu is appended to the right of your application’s menubar.
2. Test any menus, windows, dialogs, and controls in your project for which you have defined connections.
When you enter TestMode, your application receives a
Create
event.
If you want a window or dialog to appear as soon as your application
4-61
XVT-Design Manual
Note:
starts, create a connection for the application’s
Create
event tag to create the window or dialog.
The special TestMode menu appears on all of your application’s menubars while you use TestMode, to provide a way for you to exit
TestMode. It does not appear in your compiled, stand-alone application.
If you haven’t created any connections in your project, TestMode is not very interesting. You will see only your application’s task window (on platforms that have a task window) and its menubar.
Choosing menu items won’t have any effect, except choosing Quit from the File menu, which will cause XVT-Design to leave
TestMode.
4.10.2. Leaving TestMode
Tip:
Note:
To leave TestMode:
1. From the TestMode menu in your application’s task window, choose End TestMode.
-OR-
From your application’s File menu, choose Quit or Exit.
-OR-
Close your application’s task window, if the native window system provides a way to do this.
If you have defined a connection for the Quit item on a File menu, choosing this item will not terminate TestMode.
When you leave TestMode, XVT-Design redraws its menubar and reopens any windows that were open before you entered TestMode.
4.10.3. Special Considerations for TestMode
Although XVT-Design emulates your application’s runtime appearance and behavior as accurately as possible, there are a few limitations.
4.10.3.1. About Box
In TestMode, you will not see your application’s About dialog box.
A dummy dialog box is displayed in its place.
4.10.3.2. External Connections
If you have any connections to objects outside of the current project,
XVT-Design will not be able to invoke these objects during
4-62
Using XVT-Design
TestMode operation. If your application attempts to execute such a connection during TestMode, you will see a dialog like the following one:
Figure 4.31.External Connections in TestMode (Macintosh Platform)
See Also:
To resolve connections to objects external to your current project, you must merge your project file with the project file that contains the external objects.
Refer to the “Project File Management” chapter of this manual for more information on external objects and merging project files.
4.11. Generating Source Code
Once you’ve created the windows, dialog boxes, menus, and other resources for your project with XVT-Design, the next step is to generate the source code for your application. XVT-Design automatically generates Universal Resource Language (URL) files for your resources, and C source code files to handle these resources in your final application.
4.11.1. Setting the Destination Directory
Tip:
By default, XVT-Design puts the files it generates in the directory where the project file was opened from or the current directory.
To change the destination directory:
1. From the File menu, choose Generate Application.
The Generate Application dialog appears.
4-63
XVT-Design Manual
4-64
Figure 4.32.The Generate Application Dialog
(Macintosh Platform)
Note:
The current destination directory is displayed at the top of the dialog.
2. Click the Change button. A standard save-file dialog appears.
3. Navigate to the directory in which you want XVT-Design to place your application’s source code files.
4. Click the OK button.
This procedure does not actually create any files; it simply sets the destination directory for when the files are generated.
4.11.1.1. The Application Name
The name of your application is distinct from the name of its project file. For instance, the name of your project file might be
“MDB30.DPR”, but the application it generates could be named
“MegaDB_3.0”.
You set the name of your application when you set the destination directory, as described in the previous section. Before clicking the
Save button in the save-file dialog, type the name of your application in the filename edit control in that dialog.
4.11.2. Filenames
XVT-Design creates names for the files it generates, based on several pieces of information:
• the name of the application (which you supply)
• the type of the file
Using XVT-Design
• the resource associated with the file
In most cases, the first three characters of each file’s name will be the same as those of the application’s name.
In the filenames given in the following sections, we indicate these first three characters as “<xxx>”, and the complete application name as “<appname>“. For example, if your application is named
“hello”, the filename described as “<xxx>appl.c” would actually be
“helappl.c”.
You can change these names as you desire. See “Choosing Files,” later in this chapter.
4.11.3. Types of Generated Files
XVT-Design generates several different kinds of files for your application: C source code files, a header file, a resource file, a help text file, and a makefile. The following sections describe these files and their naming conventions.
4.11.3.1. C Source Code Files
XVT-Design creates a separate .c file for each module in your project (including the application itself). These files contain event handlers for the module, and any code fragments that you created with the Action Code Editor.
The names for these files have the following format:
<xxx><r><nnn>.c
where “<xxx>” is the first three characters of the application’s name. “<r>” is a character indicating the type of the associated resource, which is interpreted as follows: d - dialog box m - menu w - window
“<nnn>” is the ID number of the resource (three digits). Resources are numbered consecutively, in order of their creation.
The main function and the Task window’s event handler are placed in a file called <appname>.c, where <appname> is the name of your application.
4-65
XVT-Design Manual
Example:
Suppose your application’s name is “hello”, and it has one window and one dialog. The source code file for the window will be named
helw101.c, the file for the dialog will be named held102.c, and the main file for the application will be named hello.c.
4.11.3.2. Header File
XVT-Design creates one header file, named <appname>.h.
It contains function prototypes and resource ID definitions.
4.11.3.3. Resource File
XVT-Design generates one XVT Universal Resource Language
(URL) file, named <appname>.url. It contains resource descriptions for all of the user-interface objects in your application.
4.11.3.4. Help Text File
Tip:
XVT-Design puts all text you enter in the
SPCL:Help
tag in a file named <appname>.csh.
This feature is provided primarily for compatibility with
XVT-Design Release 2. For convenience, XVT recommends that you do not use this feature to enter and edit help source text. Instead, use an external text editor or authoring tool.
4.11.3.5. Makefile
XVT-Design creates a complete makefile for compiling and linking your application’s source files. It is named makefile.<xxx>.
4.11.4. Choosing Files to Generate
Tip:
The first time you generate source files for a given project, you will probably want to generate all of these files. Later, when you modify the project (for instance, to change the items in a menu, or add a new dialog box) you may not need to regenerate all the files.
To choose which files to generate:
1. From the File menu, choose Generate Application.
The list box in the dialog lists all the files that are part of your application, and whether or not they are to be generated. If an asterisk (“*”) precedes the filename, XVT-Design will generate a new copy of that file. If no asterisk precedes the filename,
XVT-Design will not generate a new copy of that file.
2. To turn a file’s asterisk off or on, double-click the filename.
4-66
Using XVT-Design
Tip:
3. To enable generation of all of the files, choose Select All. To disable generation of all of the files, choose Select None.
To change the name of a generated file:
1. In the list box, click on the file’s name.
The name appears in the edit control at the bottom.
2. In the edit control, change the file’s name.
3. Click the Rename button.
4.11.5. Makefiles
Note:
Tip:
XVT-Design creates makefiles by using pre-defined template files for each compiler and operating system configuration supported by
XVT, adding information about the particular files for your project when it generates the makefile.
If there are no pre-defined templates that suit your system configuration, you can modify the templates using any text editor.
To change the template ID, you can modify an existing template file.
To create a new template file, modify an existing one.
To choose a makefile template for your project:
1. From the File menu, choose Generate Application.
The Makefile Template list button lists all of the available templates.
2. Choose the appropriate template from the list button.
You can generate a makefile using any available template, regardless of the platform on which you run XVT-Design.
If none of the templates supplied with XVT-Design suit your development environment, create your own templates by editing copies of the most-suitable supplied templates. Make sure you modify the name of the template in the TPL file so that you can identify your template in the XVT_Design list of makefiles.
4.11.5.1. How XVT-Design Finds Makefile Templates
XVT-Design locates makefile templates by searching for files with the filename extension .tpl. It searches for makefile templates in the following directories, in the order they are listed here:
• The current directory
• The directory that contains the design.cfg configuration file
4-67
XVT-Design Manual
• The value of
XVTTPL
, if
XVTTPL
is a macro defined in
design.cfg, and is defined as a valid directory.
• The value of
XVTTPL
, if
XVTTPL
is a variable defined in your environment, and is defined as a valid directory.
4.11.5.2. External Files
Source-code files that are part of your application’s code, but not generated by XVT-Design, are called external files. External files are usually used for portions of your program other than the userinterface code.
Tip:
You can add external file references to your XVT-Design project.
When XVT-Design generates the makefile for your application, it inserts dependency information for your external files.
To add external file references:
Example:
1. From the File menu, choose External Files. The External Files dialog appears.
2. Type the names of your external files in the dialog. Place each filename on a separate line. Each file can depend on one or more other files. Dependencies are described as follows:
<dependent_filename>: <filename1> <filename2> ...
In the following illustration, mycode.c and dsp.c are external files:
mycode.c depends on mycode.h, and dsp.c depends on dsp.h.
4-68
Figure 4.33.Dependent External Files (Windows Platform)
4.12. Code Recovery
With XVT-Design you can edit the generated files using a text editor and later recover code from inside of XVT-Design.
Using XVT-Design
Note:
If you enabled Code Recover, then code fragments were wrapped with special comments during the code generation process. You can edit the files using a standard text editor; then click on a “Recover
Code” button to recover all the changes you have made to the generated files.
Code Recovery is an optional feature. You must click on the Code
Recovery button in the Project Attributes dialog (which activates the feature for the entire application) before the files are generated in order to recover code afterwards.
The code recovery dialog is similar to the code generation dialog; it allows you to select which files you want to recover.
4.12.1. Edit and Recover Code
The following example illustrates how a simple code fragment can be recovered.
Example:
1. Assume the following ACE code fragment:
Figure 4.34.ACE window with sample code
2. The ACE code is framed with special comments during the code generation process:
...
task_eh(WINDOW xdWindow, EVENT *xdEvent)
...
case E_CREATE:
...
/*RECOVERABLE CODE BEGIN Create */
if (!xvt_win_create_res(WIN_101,
TASK_WIN,EM_ALL, WIN_101_eh, 0L) xvt_dm_post_error("Can't open window");
/*RECOVERABLE CODE END Create */
break;
...
4-69
XVT-Design Manual
3. Edit the generated files using a text editor. (In this example, we have added an additional piece of code called myutils_init()
. You can modify as well as add code.)
...
task_eh(WINDOW xdWindow, EVENT *xdEvent)
...
case E_CREATE:
...
/*RECOVERABLE CODE BEGIN Create */ if (!xvt_win_create_res(WIN_101,
TASK_WIN,EM_ALL, WIN_101_eh, 0L) xvt_dm_post_error("Can't open window");
myutils_init();
/*RECOVERABLE CODE END Create */ break;
...
4. When you select the Recover Code option from the File menu in the ACE, XVT-Design will recover all of the changes you have made to all the generated files:
4-70
Figure 4.35.ACE window with modified code
4.12.2. Important Notes About Recovering Code
• Only code between the Begin and End comments is recovered.
• Do not modify the Begin or End comments in the generated files.
• Remember: this is an optional feature. You must click on the
Recover Code checkbox in the Project Attributes dialog box
before you generate the application in order to recover code later.
Using XVT-Design
• Unlike ACE code, you can edit the generated files with a text editor and you see exactly where your code is in the generated files, which helps fix regular errors detected when you compile.
4.12.3. Special Caution When Using the Code Recovery
Feature
Caution:
If you have previously generated code with Code Recovery enabled, you must recover code before you modify your project with XVT-
Design. The reason for this requirement is that the code recovery algorithm depends on the current state of the project. For example, if a control is added to a window, then an additional tag will be expected during code recovery.
XVT-Design will not recover any code if the project and
generated files get out of sync.
If you inadvertently modify your project prior to recovering code, you must get your project in sync with the generated files.
• The best way to get your project in sync is to undo whatever changes you made to the project.
• A second method is to duplicate any edits you made to the generated files in the ACE.
• A third way is to manually modify the tags in the generated files to reflect the current state of your project.
In general, follow these steps:
1. Modify your project using XVT-Design
2. Generate code
3. Edit tags in generated files
4. Recover code
5. Repeat the process
4-71
XVT-Design Manual
4-72
advertisement
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project