Introduction

This chapter is intended as a quick reference to some common questions and problems new Sun WorkShop Visual users may have. It is organized loosely by functionality:

Sun WorkShop Visual Interface

Definitions and Instances

Unsupported Locale

Resource Panels

Layout Editor

Links

Code Generation

Sun WorkShop Visual Replay and Sun WorkShop Visual Capture

The subheadings in this chapter, unlike those elsewhere in this manual, do not describe features of Sun WorkShop Visual but symptoms of problems. Scan the bold sub-headings for a brief description of your problem.

Sun WorkShop Visual Interface

This section discusses problems you may encounter if Sun WorkShop Visual cannot find the correct resource file. Sun WorkShop Visual must be installed so that X looks at the Sun WorkShop Visual resource file. These problems refer to the Sun WorkShop Visual interface, not to the dynamic display.

Labels Don't Display Correctly

Symptom: The labels on the Sun WorkShop Visual buttons, prompts, and menu commands do not display correctly.

Cause and Solution: These labels are only available when the correct resource file is read. If the labels are not available, X substitutes variable names. Reconfigure your system so Sun WorkShop Visual reads the Sun WorkShop Visual resource file. There are several ways to do this in X. Consult your system administrator.

Only a Few Labels Are Wrong

Symptom: Most of the Sun WorkShop Visual display is correct, but a few button labels or other resources are wrong.

Cause and Solution: Your configuration may be reading an obsolete version of the Sun WorkShop Visual resource file. Check the software version and make sure Sun WorkShop Visual is reading the resource file that came with that version.

Blank Help Screens

Symptom: Help screens come up blank.

Cause and Solution: Either your X environment is not finding the correct resource file, or the resource file is not accessing the correct search path. Make sure the "helpDir" resource contains the search path for your Sun WorkShop Visual help database.

Definitions and Instances

This section covers issues connected with the creation and use of definitions and instances. These are described in "Definitions" on page 274.

When opening a file in Sun WorkShop Visual, an error message is displayed claiming a "Class object" is "not recognized"

This means that the design file you are trying to open contains an instance of a definition which is not known to your current Sun WorkShop Visual session. When you create a definition, Sun WorkShop Visual puts a special file, called .xddefinitionsrc, into your home directory so that it can find the definition when it is referenced by an instance of it. You will need to find out what the definition is and then do one of the following:

Compiling Code Containing an Instance

The following items list some of the problems you may encounter when compiling code which has been generated by Sun WorkShop Visual from designs containing an instance of a definition.

The compiler complains about an "undefined symbol"

Check that the definition and the instance are not in the same design and therefore the same generated code file. The definition must be kept in a separate design. You should then compile the definition code and make it available to the code containing the instance.

The compiler says that it cannot find an include file and then says the instance is "undefined or not a type"

If you have generated the code for the definition into a separate directory, you will have to change the Makefile so that it can find the header file for the definition. This header file should have the same name as that which appears in the Edit Definitions dialog.

The linker says that it has an un "undefined symbol: create_<defintionname>"

The definition code must be compiled in with the code containing the instance. There are two ways of doing this:

Unsupported Locale

If you have specified a locale using the LANG environment variable which Sun WorkShop Visual does not recognize, a message is printed on startup informing you that the specified locale is not supported and that it is being coerced to "C". For information on the impact this will have, see "Unsupported Locales" on page 630.

Resource Panels

This section discusses problems you may encounter when you use the resource panels. If you encounter problems with resource values at run time of the generated application, see "Code Generation" on page 807.

For advice on setting resources for specific widgets and combinations of widgets, lookup the widget in Chapter 27, "Widget Reference", starting on page 747 and your Motif documentation. Note that many apparent problems with resource settings can be solved by resetting the widget involved or the Shell.

When you set values in Sun WorkShop Visual's resource panels, Sun WorkShop Visual actually resets resources of widget instances in the dynamic display. Sometimes the results are not what you expect:

Resource Settings Are Rejected

Symptoms:

The value you typed into a field of the resource panel is not accepted

The value in the resource panel reverts to the former value

The value in the resource panel changes to some other value

The dynamic display reflects the value on the resource panel, but the value is not what you typed

Cause: Motif cannot set the new value you specified. The most common reason is that the selected widget is being constrained by another widget, usually its parent. This is particularly common with size and position resources such as the width and height resources in the Core resource panel, which are frequently overridden.

For example, if a RadioBox contains a group of ToggleButtons, the width of the individual ToggleButtons is determined by their text and margin resources; the width of the RadioBox is calculated from the width of its widest child; and all the ToggleButtons are forced to be the same width as the widest one. A width setting on the Core resource panel is overridden by the calculated value. If the RadioBox is in turn the child of a Form, attachments set in the Layout Editor can override the RadioBox rules.

Solution: Check your design for constraints that may be overriding the setting. Use the constraints imposed by other widgets to achieve the desired effect.

FIGURE  28-1 Resource Relationships

Resource Settings Don't Take Effect

Symptom: A new value is accepted on the resource panel, but the dynamic display does not immediately reflect the change as you expect.

Solutions: Reset the widget. If that doesn't work, reset the Shell. If resetting the Shell doesn't work, consult the Widget Reference chapter. You may need to set two or more resources to achieve a single effect. For example, to display a pixmap on a label or button, you must set the "Pixmap" resource to specify the pixmap you want, and set the "Type" resource to "Pixmap."

A few resources are never reflected in the dynamic display, as discussed below.

Geometry Resources Are Overridden

Symptom: The width and height resources on a widget's Core resource panel are overridden.

Cause and Solution: The width and height Core resources of any widget can be overridden, either by resources specific to that widget class or by geometry rules of the widget's parent. Consult Chapter 27, "Widget Reference", starting on page 747, or Motif documentation for information about resources of the widget and its parent that may be controlling its size.

Cause and Solution: The width and height Core resources of a Shell can be overridden by the corresponding resources of the Shell's child. One way to control the size of a dialog is to set the width and height resources of the Shell's child. Another way is to set the minimum width and height resources of the Shell, which are not overridden by the child.

Cause and Solution: The x,y position resources of a Shell can be overridden by the position resources of the Shell's child if the Shell's child is a BulletinBoard, or a derivative of the BulletinBoard such as a Form, DialogTemplate, or MessageBox. To use the Shell's x,y position resources to control the dialog's position, set the BulletinBoard's "Default position" resource to "No."

Resources Are Not Reflected After Resetting

Symptom: The resource panel accepts your resource settings, but they are not reflected in the dynamic display even when you reset the widget.

Cause: Certain resources can only be set when a widget is first created. These resources cannot be changed once the widget is added to the dynamic display. They include various resources related to scrollbars such as "Scrolling policy." Sun WorkShop Visual still lets you change the value on the resource panel, and even though the value is not reflected in the dynamic display, the new setting takes effect at run time of the generated application. For details about individual resources, consult the Motif Programmer's Manual.

Cause: The "Dialog Style" resource of BulletinBoards and widget classes that derive from the BulletinBoard can be set to "Modeless," "System Modal," or "Application Modal." Modal dialogs disable all other dialogs until they receive an answer from the user, so if a setting of "System Modal" or "Application Modal" were effective in the dynamic display, you would not be able to do anything else until the dynamic display was closed. You can still select one of these settings; Sun WorkShop Visual disables the setting while you are building the hierarchy and generates it correctly in the code.

Solution: If you have resources of this kind in your design, you can only see the final results after the design is finished and you generate the code. You can see the results at intermediate stages by generating code and running a prototype using the following steps:

Expected Fonts Do Not Display In Sun WorkShop Visual

Symptom: A widget with a default font setting does not display the font you expect in the dynamic display.

Cause: When a widget does not have an explicit font setting, Motif searches back through the design hierarchy to find the widget's nearest BulletinBoard, BulletinBoard derivative, or Shell ancestor, and uses the font setting of that ancestor for the current widget. Therefore, if several buttons all have default font settings but are children of different BulletinBoards, some may show different fonts from others.

Solution: Setting a font on the BulletinBoard or Shell instead of on individual widgets is a convenient way of setting all the fonts at once. To get uniformity you must use the same font on all parent widgets with explicit font settings. A font object is a convenient way to do this.

Font Change on Parent Doesn't Affect Children

Symptom: Changing the font on a BulletinBoard, BulletinBoard derivative, or Shell has no effect on its children.

Cause and Solution: The new font setting on a parent widget does not affect the children until you reset the parent widget. Reset the parent widget.

Cause and Solution: Font settings on parent widgets do not affect their children if the children have explicit font settings of their own. Make sure the children have default font settings.

CascadeButtons in DialogTemplate Don't Display

Symptom: The DialogTemplate does not resize to accommodate CascadeButtons in the MenuBar.

Cause: This is a bug in some versions of Motif. The DialogTemplate resizes properly to accommodate the button box and work area, but if the MenuBar exceeds the width of the button box and work area, it is cut off.

Solution: Add the button box and work area children to the DialogTemplate before you add the CascadeButtons to the MenuBar. In many cases the width of your work area or button box will create enough width to accommodate the MenuBar.

Solution: If your MenuBar is still too wide to display, use a Form as the work area, or put the work area inside a Form, then use the Layout Editor to add extra space around the work area.

Solution: You can force the DialogTemplate to be wider by setting its "Width" resource on the Core resource panel.

Layout Editor

This section discusses problems you may encounter when you use the Layout Editor. Note that many apparent problems in the Layout Editor can be solved by resetting the Form.

Widget Becomes Very Small or Very Large

Symptom: The widget becomes very small or very large.

Cause and Solution: In some versions of Motif there is a bug in the Form that appears when the Form is a child of a DialogTemplate. When you reset the Form, any container widgets inside the Form become very small. If you have this problem, resetting the DialogTemplate instead of the Form corrects it. To do this, you must go from the Layout Editor screen to the main Sun WorkShop Visual screen, select the DialogTemplate in the construction area, and give the "Reset" command. To resume working in the Layout Editor, first select the Form again in the construction area.

Cause and Solution: Attachments can change the size of a widget. For example, attaching the edges of a widget to the corresponding edges of the Form forces the widget to span the full width or height of the Form. Reset the Form. If resetting the Form doesn't work, remove some of the attachments from the widget and reset again.

Methods of breaking attachments are listed below. For a more complete discussion, see Chapter 4, "The Layout Editor", starting on page 99.

Use "Undo" to remove the most recent attachment

Move the widget

In the "Attach" mode, click just inside the edge of the widget or drag from just inside the edge of the widget toward the widget's center

Replace the old attachment with a new attachment

Select the widget in the design hierarchy, bring up its Constraints panel, and reset the attachment "Type" for that edge to "None".

"Circular Dependency" Error Message

Symptom: A "circular dependency" message appears after you make an attachment.

Cause and Solutions: If you add an attachment that results in a circularity involving two or more widgets, Motif detects the circularity and returns the error message. Click on "Undo." If you still get the error message, carefully inspect your layout for an attachment loop and remove one of the attachments.

"Bailed Out..." Error Message

Symptom: A "bailed out" message appears after you make an attachment.

Cause and Solutions: This Motif message indicates that your layout contains attachments that contradict one another without being circular. It usually occurs with "Self" or "Position" attachments. Use "Undo" or move the widgets to remove the contradictory attachments, then reset the Form.

Widgets Overlap the Boundary of the Form

Symptom: Widgets at the edge of a Form cause breaks in the Form's boundary line.

Causes: Widgets whose edges coincide with the sides of the Form can overlap the line drawn around the Form, causing undesirable breaks in the line. This only occurs if the Form is the immediate child of a Shell. Three conditions in the Form can cause the overlap:

A widget is attached to the edge of the Form with an offset of 0 or 1 pixel

A widget is attached to the edge of the Form with a default offset and a vertical or horizontal spacing value of 0

There are no attachments between the bottom or right edge of the Form and the widgets closest to those edges

Solution: Attach widgets to the top or left edge of the Form with an offset of 2 or more pixels. You can use an explicit offset, or you can set the Form's vertical and horizontal spacing resources to the offset value and use the default offsets. Make sure the widgets at the bottom and right side of the layout are attached to the edge of the Form with an offset or spacing of 2 or more pixels.

Solution: Put the Form inside another manager widget, such as another Form or a DialogTemplate. This is the simplest and most flexible solution.

Links

This section discusses problems you may encounter when you use the "Edit links" command in the Widget Menu. For additional information about links, see the Code Generation section that follows.

"Add" Is Disabled

Symptom: The "Add" option is grayed out.

Cause and Solution: The Link facility requires the target widget to have an explicit variable name. If the target widget is a Shell, its immediate child must also have an explicit name. Sun WorkShop Visual grays out the "Add" option if it does not find explicit names. Name the appropriate widgets.

A Link Stops Working

Symptom: A link that used to work stops working. The link appears in the "Edit links..." dialog with a blank space instead of an icon.

Cause and Solution: If you change the name of a widget, Sun WorkShop Visual does not automatically update links that refer to that widget and they cease to be functional. Remove the obsolete links and replace them with new ones.

Links Don't Update When You Select Another Button

Symptom: The "Links" panel doesn't behave like the resource panels. If you edit links on one button then select another button, the "Links" panel still shows the links from the previously selected button.

Cause: Sun WorkShop Visual interprets the selection of any new widget as a target widget for a potential new link on the previously selected button.

Solution: Pull down the Widget Menu and select "Edit links" again to display and edit links on the second button. You do not have to close the Links panel first.

Code Generation

This section discusses problems you may encounter when you generate code. Some of these problems result because Sun WorkShop Visual offers you so much flexibility in arranging your files. For example, you should make sure to generate Link functions in only one file, and to generate Includes in the files where they will be needed. Read "Arranging Your Files" on page 244 for more details.

"No Application Shell" Warning

Symptom: Sun WorkShop Visual displays a "No Application Shell" warning message when you try to generate the primary module with a main() program.

Cause and Solution: Your design does not contain the required Application Shell. Bring up the resource panel for the Shell of the main window in your design, click on the "Application Shell" toggle, then click on "Apply."

Links are Undefined

Symptom: Link functions are undefined at link time.

Cause and Solution: If you generate Links with your primary module, you must generate the actual code for the links - the Link functions - into one of your code files, either the primary module or a stubs file. Be sure to generate the link functions into an appropriate file.

Global Widgets Are Undefined

Symptom: Global widgets are undefined when you compile the stubs file.

Cause and Solution: Declarations of global widgets and objects are generated into the primary module, but not into the stubs file. To generate a header file that declares them, use the "Externs..." option and #include the resulting header file with your callbacks. This is preferable to writing your own extern declarations or copying the ones generated in the primary module, because it is less error-prone and more complete. The Externs file can be regenerated when necessary to reflect changes in the design.

Application Does Not Use Resources from X Resource File

Symptom: The generated application doesn't use the resource values from the generated X resource file. For example, variable names appear on labels and buttons instead of the label strings, colors are wrong, or fonts are wrong. The exact symptoms depend on which resources were generated into the X resource file and which were hard-wired.

Cause and Solution: You did not regenerate the X resource file when you regenerated code. If you have added or removed widgets from your design, default widget names may change and no longer correspond to those in the generated X resource file. Regenerate the X resource file.

Cause and Solution: X cannot find the X resource file when you run your application. You may need to rename the X resource file, usually with the same name as the application class and without a suffix. For more information, see your X documentation.

Cause and Solution: X cannot recognize the widget names in the file because a different application class name was used for the generated code file and the X resource file. Regenerate the application and the X resource file, being sure to use the same application class name for both. Be sure to use a unique application name to avoid confusion with other resource files your system may be accessing.

Default Resources Change At Run Time

Symptom: A color, font, or other resource is different at run time from that in the dynamic display.

Cause: Some resources shown in the dynamic display are inherited from Sun WorkShop Visual. If not explicitly set on the resource panels, these resources may inherit values from other sources at run time, depending on the platform where the program is run.

Solution: To ensure the correct colors and fonts, set explicit values for them on the resource panels. Foreground and background colors can be set on each Shell in the design and are then inherited by all children of the Shell. Fonts can be set on BulletinBoards, derivatives of the BulletinBoard, or Shells, and apply to all their children.

Unexpected Results Occur When Widgets Share a Widget Name

Resource values can be shared among widgets with a common widget name, but only if they are read from the X resource file into the resource data base. The following rules apply:

Sharing of resources occurs only at run time. Resource values are not shared among widgets in the dynamic display

Hard-wired resources are not shared

Object bindings are not shared

Symptom: Resource values are different at run time from values in the dynamic display. When a resource is generated to the X resource file, the result is different from when it is hard-wired.

Cause: These are expected results when widgets share a widget name. The dynamic display and hard-wired resource settings disregard common widget names. Resources generated into the X resource file, however, affect all widgets with a common widget name.

Symptom: A color or font is not shared among widgets with a common widget name, even if that resource was generated to the X resource file.

Cause and Solution: The color or font used an object binding instead of a color or font setting. Use a simple color or font setting, or set the resource on a common parent of the widgets that you want to share the value.

Symptom: An explicitly set resource value is overridden at run time.

Cause: If widgets share a widget name and resources are generated to the X resource file, only one value is used even if more than one was set.

Solution: Generally it is better to avoid common widget names unless widgets are to share all resource values. However, you can force any resource value to be restricted to a single widget by hard-wiring it. Use the masking toggles on the resource panels to do this.

Sun WorkShop Visual Replay and Sun WorkShop Visual Capture

The following section answers frequently asked questions about Sun WorkShop Visual Replay and Sun WorkShop Visual Capture.

Why is it not possible to record and replay certain applications (e.g. Netscape)?

Typical reasons are:

The application may be statically linked with the Xt library rather than dynamically linked with it.

The application may have its own multi-threading scheme that disallows Xt Work Procedures.

The product may have multiple application shells. (See below)

If you experience difficulties in recording and replaying your own software, simply relink it so that it uses libXt.so.

Why is the click position in a text widget not recorded?

All of the "position sensitive" motif widgets are recorded/replayed through special Sun WorkShop Visual Replay routines. You will find the source code for these routines in the src/examples/replay/libcvtXm directory.

The conversion routines for XmText and XmTextField are not built by default because, for most testing purposes, it is reasonable to treat the text field as a simple data entry field whose contents you wish to replace.

It is a lot simpler to do the following:

	doubleclick mytextwidget

	type halloworld

than it is to do this:

	doubleclick mytextwidget(position, 25)

	type halloworld

It would also be difficult to check that doubleclicking at a particular character position did select all the text.

Different test runs may involve replacing the contents of a text field with different values. The name of the text widget is the most important item - not the values which are to be placed in it.

If you wish to test the editing facilities provided in an XmText widget within an application, you should rebuild the libcvtXm directory with -DHANDLE_TEXT added to the cc command line. Then copy the libcvtXm.so shared object to lib/xds so overwriting the standard version.

The Sun WorkShop Visual Replay copyright message appears but then it exits

This commonly occurs when Sun WorkShop Visual Replay has determined that you are attempting to replay a non-Motif application.

The -O flag can be used to force the application to be invoked and allows you to replay any non-Motif application functionality.

NB: This situation can also arise for Motif applications which have multiple application shells (see below).

Sun WorkShop Visual Replay is invoked successfully but appears not to be working

Typical reasons are:

The application has a "splash" or creates one or more temporary ApplicationShell widgets on startup.

By default, Sun WorkShop Visual Replay registers the first ApplicationShell widget and uses it as a point of reference. Usually it "takes" the first applicationShell it sees, but you can change it to take the 4th by adding:

	  -use 4

on the command line, or set the XDSUSESHELL environment variable:

	  setenv XDSUSESHELL 4

NB: To check that you are using the "real" application shell, try recording. You should see:

	in ApplicationShell

		......

If you see:

	in myapp

		.....

then it may not be using the correct application shell. (If your application has an unmapped application shell, and multiple toplevel shells, then this is the correct behavior).

The solution is to keep incrementing the -use count. The worst that can happen is that you tell it to ignore ALL you application shells, so it won't record, replay or capture.

Your application has reworked or subverted Xt event handling.

You know that this is the problem, if:

In these circumstances, all you will be able to do is capture designs.

Your application has not been linked with Motif.

In this situation, the default behavior is for Sun WorkShop Visual Replay to abort. This may be overridden using the -O flag. Note however that you will not be able to record or replay any application functionality which relies upon Motif.

My application has 3rd party widgets in it. How can I capture them properly?

The capture mechanism creates capture files in the Sun WorkShop Visual .xd format and assumes that you are using the standard version of Sun WorkShop Visual, i.e. not one supplemented with non-Motif widgets. By default, all non-Motif widgets are represented in the capture file as Motif DrawingArea widgets.

If you are using a version of Sun WorkShop Visual which supports the 3rd party widgets you wish to capture, you need to set the following resource:

*xdsCaptureUserWidgets:true

Can Sun WorkShop Visual Replay handle japanese (and other) text and input methods?

Yes. It records the composed text that has been inserted in the text field and replays by inserting the text directly. It has been configured for the Motif Text and Textfield widgets. The configuration software is in:

src/examples/replay/motif/motif4.c 

and the mechanism for registering the software is in:

src/examples/replay/motif/register.c

The configuration involves a get/put routine of the data. Some input methods will allow you to access this information. The default fallback is to access the string in the widget itself.

It has hard-wired control-space as an input method compose request, and has an alternative "compose" keysym resource, which is set by default to Henkan_Mode.

If you are using the recording software with an input method that takes, e.g. F3 as the compose key, you should run your software with:

	-xrm *xdsImComposeKeySym:F3

or set this resource from a defaults file, or with xrdb.

Can my customers record/replay my applications?

To permit users to use Sun WorkShop Visual Replay to record and replay your application, you must have the following line in your code:

xdsAllowUserAccess()

and link the application with the libxdsclient.a library.