When Wave Widgets applications were designed with previous versions of PV-WAVE, use of Wave Widgets (Ww) and Widget Toolbox (Wt) routines could be mixed freely to create the desired interface. However, when writing an application targeted for both Microsoft Windows and Motif, use of Widget Toolbox (Wt) commands is not recommended. In particular, Motif constants as defined in the wtxmconsts.pro and wtxmclasses.pro files have their Microsoft Windows counterparts in the files wtwacconsts.pro and wtwacclasses.pro. These differences as well as others are folded into the Ww layer routines to provide a common Application Programming Interface (API). Hence, to create a portable application, the general rule is to use the Ww layer routines to access Wt layer functionality.

Every effort has been made to encapsulate as much of the common functionality as is practical in the Ww layer routines.

One of the major considerations that affects applications written to run on multiple windowing systems is the differing system commands and file naming conventions imposed by the underlying operating systems. The following PV-WAVE commands are available to help eliminate these differences by constructing pathnames given a filename.

In addition, standard PV-WAVE directories can be referenced by using system variables to avoid having to specify platform-specific filenames. In particular the following system variables can be used to specify files in PV-WAVE directories:

In cases where the above commands cannot be used to construct the filename, it is important to follow the conventions of the operating systems, as described in Table D-1: Operating System Conventions.

It is also important to remember that since the colon character (:) is used as a valid part of filenames on Microsoft Windows, a colon should not be used to separate directories in a path list if one is required. By convention, the semi-colon (;) is used to separate pathnames on Microsoft Windows systems. Since UNIX filenames may not contain the colon character, it is used to separate directories on UNIX platforms.

Due to differences in the underlying implementation of event/message processing, differences exist in the processing of key events between Motif and Microsoft Windows. The WwGetKey routine bridges the majority of these differences. However, when using the Keysym keyword with WwGetKey, differences in values may be seen, especially in the translation of unprintable keys like <Delete> or <Return>.

On Motif-based systems, it is possible to customize Wave Widgets that contain text by changing the font in which the text is displayed. This is often done by specifying the Font keyword in the WAVE Widget (Ww) routine call. It is also possible to change the font through a call to WwSetValue or by specifying the font in a resource file.

The Microsoft Windows version of PV-WAVE 6.0 does not provide support for changing widget fonts. Widgets that display text will do so using the default Microsoft Windows system font. One notable exception is the Preview widget. Because of the column-oriented nature of the widget, it cannot be used effectively with a proportional font and therefore displays in the default fixed width font.

Keep in mind when writing GUI applications for Microsoft Windows that some systems may be running at different resolutions, which can affect how your application appears on their display. This section discusses both high and low resolution displays.

New display and touch screen devices are offering ever higher screen resolutions. Higher resolutions make the screen appear sharper, but also make fix-sized display elements such as icons, program windows, images, text and individual Graphical User Interface (GUI) elements smaller and harder to read and work with. On small, touch screen devices, ultra-high resolutions can make manipulating GUI elements with your fingers very difficult to do accurately.

Your screen resolution represents the number of available pixels on your screen. If your screen is 100 pixels wide and a button in a GUI is 10 pixels wide, the button takes up 1/10th of the width of your screen. If you increase your screen resolution to 1000 pixels wide, the button now takes up only 1/100th of your screen. If you are using a high resolution device and find that screen elements are too small to comfortably read and work with, you could reduce your screen's resolution until everything on it grows to a size you can work with. Changing your resolution changes the relative positions and sizes of all of the GUI elements displayed on your screen by the same proportion, so everything remains in the right place and is correctly sized.

In Windows XP and later, Microsoft provides another method to deal with this issue. A link at the bottom of the dialog used to set your screen resolution allows you to force Windows to scale up certain display elements by fixed percentages to make them easier to read. The effect is that the targeted elements are stretched by the scaling percentage that you choose. However, as anyone who has attempted to stretch a small image to a larger size knows, stretching it too far results in a blurry, pixelated image.

There are additional issues for the PV-WAVE GUI developer. PV-WAVE widgets are bitmapped, meaning that their size, in pixels, is fixed. When a user instructs Windows to stretch everything, only certain elements of a PV-WAVE GUI can be stretched. Compounding this issue is the fact that Windows performs this stretching after PV-WAVE calculates the space required for text labels, spacing, etc. Scaling percentages of 150% and above cause text and other elements to become too large for the space PV-WAVE provides for them, cutting them off or causing them to overlap.

To help correct this behavior, we have introduced the !HD system variable. When !HD is set to 1, PV-WAVE anticipates the scaling that Windows intends to do and adjusts the calculated label sizes and element spacing accordingly. In most cases, setting !HD to 1 allows your existing PV-WAVE GUI applications to maintain their appearance for different resolution/scaling combinations without modifications to your code.

Since you are unable to know the scaling percentage for each user’s individual machine during GUI development, there are steps you can take to accommodate the potential resolutions and scaling factors chosen by different users. The following sections discuss some of these steps and provide additional information about this issue.

DPI stands for the “dots per inch” in a printed or displayed image. The higher the DPI the higher the quality and sharpness of the displayed or printed image appears. When the DPI settings change, the system fonts and user interface (UI) elements also change in size. PV-WAVE users might notice widget applications where the text is too large or too small – or an image appears compacted in size or scaled unreasonably. PV-WAVE programmers might have to reexamine widget layouts, widget font use, and hardcoded widget positional parameters. DPI settings and the user’s ability to control both screen resolution and DPI through system settings directly impact these issues. Adding support for high DPI-awareness in your application ensures the presentation of your applications’ UI is more predictable across multiple displays.

The following demonstrates three simple alternatives to try when experiencing issues with applications not explicitly designed for HD or high DPI monitors.

Applications that do not adjust for larger fonts and UI sizes can face some common issues on high resolution displays. The most common categories of high DPI issues include:

The following sections discuss each of these common problems and possible methods for solving each issue in PV-WAVE.

Incorrect font size

PV-WAVE applications that are not written to be DPI-aware can display incorrect font sizes for text when running in a high DPI environment. Developers should note the possibility of dynamic changes to font sizes and ensure their layout accommodates these changes. You can usually reduce problems in existing applications by adjusting the default font size or using software fonts.

Incorrect layouts

Incorrect layouts in PV-WAVE applications are often caused by hard coding positions in a bulletin board layout. When running on a high DPI setting, the system metrics, such as !Display_Size, can become the source of miscalculations. Because high DPI settings cause the system to use larger fonts and larger UI elements, it means the application takes up more pixels when it draws these elements. When adjusting the systems DPI setting over 100%, the !Display_size system variable does not account for the new “effective resolution.” It is critical that developers correctly calculate and identify the effective resolution to help PV-WAVE applications adjust when run on HD displays and/or in high DPI settings. The formula to calculate the effective resolution is: Effective Resolution = Real Resolution / (DPI/96).

For example, suppose a user has a display of 2160 x 1440 with 144 DPI. The effective resolution is now 1440 x 960, because 2160 / (144/96) = 1440, and 1440 / (144/96) = 960. The effective screen real-estate is thus reduced by 50%. This means that text and UI elements are now roughly the same size as running at Smaller – 100% (96 DPI) with a resolution setting of 1440 x 960. A simple practice is to develop your PV-WAVE application on the lowest DPI setting intended for use, and test on the higher DPI settings to verify proper layouts of UI elements.

Clipped and/or covered UI elements with text

Clipped and/or covered UI elements with text usually indicate inadequate spacing between individual UI elements. When designing a UI element with text or labels, be sure to test at the higher DPI settings to adjust for hard coded pixel positions and font size increases. In general it is better to add white space to the start and end of an element when placing a label or text. The following example demonstrates this adjustment.

Callback procedure

PRO RadioCB, wid, which

CASE which OF

1: PRINT,'First Toggle Selected'

2: PRINT,'Second Toggle Selected'

3: PRINT,'Third Toggle Selected'

ENDCASE

value = WwGetValue(wid)

PRINT, value

END

PRO dpi_ex1

top = WwInit('dpi_ex1', 'Examples', layout)

; For high DPI compatibility add whitespace before

; and after the individual labels to account for text size

; increases.

labels = [' System ', ' Owner ', ' Group ']

rbox = WwRadioBox(layout, labels, 'RadioCB', $
/Vertical, Border=2, Spacing=20)

status = WwSetValue(top, /Display)

WwLoop

END

Partial rendering of a full-screen application

Another common side effect of running applications that were not designed to run at high resolution or high DPI is the partial rendering of a full-screen application. Partial rendering can also occur in applications developed under system metrics that were virtualized on older versions of Microsoft and in applications that use multiple layout types without definitive attachments. To avoid this issue, make sure that your full-screen application uses proper widget attachments when using multiple layouts. Following the recommendations in the Adjusting for applications not designed for high DPI section, along with high DPI testing should help mitigate most visual discrepancies with widget attachments.

For Microsoft Windows configured at 800x600, or 640x480, which is significantly lower than the standard resolution of most workstation displays, you need to adjust your application to use low resolution images. Since bitmaps are used as the image in the button, the size cannot be reduced without altering the bitmap. The PV‑WAVE Navigator application has a Lowres keyword that reconfigures the button bar to display two rows of buttons to account for lower resolution displays. The Lowres keyword also reduces the size of the drawing area in graphics VDA Tools to better fit the display.

UNIX platforms use the X Windows graphics driver and thus behave identically. The Win32 driver, which is used to provide PV-WAVE graphics on Microsoft Windows-based systems, was written to be compatible with the X Windows driver in as many ways as possible; however, several notable differences exist between the two.

To be more efficient, the Win32 graphics driver now uses buffered output. This leads to rare occasions where a program needs to be certain that data are not waiting in a buffer, but have actually been output. The most common side-effect of buffered graphics is seen in improperly stacked graphics. The EMPTY procedure can be used to flush all buffered output.

EMPTY is a low-level graphics routine. PV-WAVE graphics routines generally handle the flushing of buffered data transparently, so the need for EMPTY is rare. Graphics VDA Tools writers will need to be more aware of buffered graphics to ensure proper stacking of the Graphical Elements with respect to the tool’s graphics.

When executed on a device that does not use buffered output, the EMPTY command has no effect.

The handling of color tables differs somewhat between the X Windows and the Microsoft Windows platforms. For the sake of this discussion, the assumption is that X Windows is running in 8-bit pseudo-color mode and Microsoft Windows is running in 256-color mode, since these modes are where differences are most apparent.

In X Windows, colormap entries are allocated, if available, in a shared colormap. This colormap is shared between all the applications running on the workstation and is limited to 256 entries. In PV-WAVE, entries in this shared colormap are reserved when the first graphics window is created. It is possible at the time of this allocation to limit the number of colormap entries reserved by specifying the Colors keyword to the WINDOW command.

The value specified with the Colors keyword can take two forms: 1) A positive value n, specifying “allocate n entries” or 2) A negative value –n, specifying “allocate all but n entries.” The value of the PV-WAVE system variable !D.N_Colors reports the actual number of color indices available.

Microsoft Windows differs from X Windows in several respects. First, colormaps are not specifically shared between applications. The currently active application, known as the “foreground” application, has its colormap installed and its colors are displayed correctly. All other applications are given the foreground application’s colormap and attempt to display their data as best they can. Secondly, the Win32 driver has access to a 256-color palette. Of these colors, 20 are reserved for Microsoft Windows GUI elements, leaving 236 colors. For efficiency and compatibility reasons the driver indicates that it has 256 colors and the variable !D.N_Colors reports 256. In actuality, 20 of those colors are simply mappings into the closest available color of the other 236 colors.

On Microsoft Windows, the Colors keyword to the WINDOW command has no effect.

The DEVICE command provides support for setting alternative graphics functions through the Set_Graphics_Function keyword. The graphics function is a logical function that specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen.

Graphics functions operate on pixel values. Hence, If you are combining pixel values 7 (00000111) and 21 (00010101) with the XOR operation, the resulting pixel value would be 18 (00010010). The actual color on the screen will be dependent on the installed colormap.

Since the PV-WAVE X Windows driver allocates colors in a shared colormap, the color values specified in PV-WAVE commands do not translate directly into X Windows pixel values. For example, the command

PLOT, y, Color=0

specifies color 0 for the plotted line. This will not likely result in pixel value 0 being used, since 0 is typically reserved by the window manager. The Color keyword’s value is translated into a pixel value and the graphics function is applied to this value.

On Microsoft Windows-based systems, since colormaps are not shared among applications, color values translate directly into pixel values and the results may differ greatly from X Windows. One notable example is in using the XOR graphics function with the Color keyword value as 0. On X Windows, as explained above, the pixel value used with the XOR function will likely not be 0 and will be combined with the destination pixels and drawn in a third pixel value. On Microsoft Windows, the color value 0 maps into the pixel value 0. Thus, when combined with the destination pixel values, according to the XOR function’s rules, the resulting pixel values will be exactly the same as the destination pixels and the graphics will appear unchanged.

Several keywords to the WINDOW command that are specific to the X Windows driver have been altered to better fit the Microsoft Windows parlance. Table D-2: Keywords lists X Windows keywords and the Microsoft Windows counterparts.