Appendix: Using PhAB under Microsoft Windows

This appendix describes the main differences between the Windows and native QNX Neutrino versions of PhAB.

• Photon in a single window
• Exiting PhAB
• Advanced options
• PHINDOWSOPTS
• Using the clipboard
• Transferring PhAB projects
• Debugger launch line
• Custom widget development and PhAB
• Using custom TrueType fonts and PhAB
• Photon Hook DLLs
• Running multiple copies of PhAB

Photon in a single window

Like the native QNX Neutrino version of PhAB, the Windows version uses Photon and the Photon Window Manager (pwm) to manage its windows and dialogs. The main difference is that under Windows, Photon runs within a single window.

When you launch PhAB, it first starts a console window that it uses only for status messages. Next, the main Photon window is created. All PhAB windows and dialogs appear within this main window, and any sub-applications launched by PhAB stay within this window. Note that you can run multiple PhAB sessions within this single Photon window.

You can minimize application windows within the Photon window, but since there's no shelf application running, the right mouse button has been set up to list all running applications and to let you bring them to the foreground. To do this, simply click the right mouse button on a blank area of the main Photon window, then select the application you wish to bring to the foreground.

Exiting PhAB

When you exit PhAB, it attempts to shut down all Photon components as well, unless there are other applications still running within the Photon window (such as a second PhAB session or the language editor).

If all Photon components don't shut down automatically, or if you just want to force everything to exit in the event that the system is having problems, you should manually close the Console for PhAB window. If this does not work, type:

ph -kill

from a Windows command prompt.

Advanced options

If you wish to specify command-line options to pwm or to the photon server, you can use these environment variables:

• PWMOPTS
• PHOTONOPTS

You set these environment variables using the Environment tab (in the System program of the Windows Control Panel).

For details on the command-line options for any QNX Neutrino utility, see the Utilities Reference.

PHINDOWSOPTS

You can use the PHINDOWSOPTS environment variable to pass extra options to the special version of Phindows that's used as the display driver for PhAB for Windows. For example, if your Neutrino target is using an 8-bit 256 color mode with a nondefault palette, then to allow the PhAB display on the Windows host to show the colors as they'll appear on the target, you can do the following:

1. Set the Windows display mode to 256 colors.

   In Windows XP, unlike Windows NT/2000, you do this on a per-application basis, by using the Compatibility tab on the properties for the application's shortcut or executable.

2. Set the PHINDOWSOPTS environment variable to specify the same palette file as will be used on the target. For example, if the palette file is called grey.pal, you might set this variable to -P%QNX_TARGET%/usr/photon/palette/grey.pal. In this case, the direction of the slashes doesn't matter.

To set environment variables globally, you can use the Environment Variables button in the Advanced tab of the System program in the Windows Control Panel. To set a variable temporarily, use set variable= in a Command Prompt window, and then type phab to run the Photon Application Builder with that environment variable set.

Using the clipboard

To use the clipboard in PhAB under Windows, you must have permission to write to the directory specified by the HOME environment variable. (If HOME isn't set, PhAB uses HOMEDRIVE followed by HOMEPATH).

If none of these environment variables are set under Windows, or your user account doesn't have permission to write to the directory specified, PhAB's clipboard function (cutting and pasting widgets) won't work.

---

If you have HOME set, and it doesn't exist, PhAB won't be able to launch.

---

Transferring PhAB projects

When transferring PhAB projects between QNX Neutrino and Windows it is important to preserve the exact contents of all files. In other words, each file should be treated as binary, not ASCII, and the case of all filenames should be preserved. The easiest way to ensure this is to create a zip archive at the source, transferring the single binary zip file, and then extracting the contents of the archive at the destination.

Note that tar files can be used to transfer PhAB projects, but if you use Winzip to extract the contents of a tar archive on Windows it will by default treat files as ASCII and change their line endings. To prevent this you must deselect the TAR file smart CR/LF conversion option in Winzip.

Debugger launch line

You can launch the GDB debugger from within PhAB. Edit the project properties to specify the debug command that PhAB should use (for more information, see the Generating, Compiling, and Running Code chapter). The default debug command and arguments used by PhAB on Windows is:

gdb_phab.bat -debugger nto$TPR-gdb --symbols

This runs the commands in the gdb_phab.bat batch file.

PhAB automatically sets the TPR environment variable before issuing the debug command. It contains the name of the current target processor, as determined by the last build performed. Possible values are currently x86, ppc, mips, sh and arm. Having this variable in the debug command automatically selects the correct debugger executable to use.

Finally, since the Windows version of PhAB is never used for self-hosting, PhAB passes the --symbols option to GDB by default. This is like the symbol GDB command, and makes gdb load symbols from the PhAB executable without making it the program executed when you use the run command. This lets you run the executable on the remote target. Here are the initial commands from a typical debug session after you start GDB using the default launch line:

(gdb) target qnx com1
(gdb) upload myprog
(gdb) run myprog
(gdb) break main
(gdb) continue

For the above, we assume that we're connected to the target machine via serial port com1 and that the pdebug remote debug agent is already running on the target.

---

If you want to use a graphical debugger, use the IDE that's part of QNX Momentics. Create a Photon Appbuilder project within the IDE and launch PhAB from there.

---

Custom widget development and PhAB

Photon lets you create applications using widgets that you've built yourself or obtained from a third party. You can build these custom widget libraries into your application and run it on your intended target.

For documentation on writing source code for custom widgets, getting them to run within your application on the target, and getting PhAB to recognize your custom widgets, see Building Custom Widgets. The process for doing these things is essentially the same on all host platforms.

PhAB can dynamically load custom widgets and display them properly as you develop your application on the host machine.

To make PhAB display custom widgets correctly on the host as you develop your application, you need to take some extra steps to recompile and link the custom widget source code for the host platform and processor. This means building shared libraries that PhAB dynamically loads at runtime. If you do not do this, you can set dimensions and specify resources and callbacks, but these settings won't take effect and be displayed until you run your application on the target.

For the following procedure, we assume that you've already performed the steps that aren't specific to the host platform, namely:

• Obtain the custom widget source code.
• Build target libraries from your custom widget sources.
• Add appropriate entries in PhAB's palette definition files.
• Create icon image and resource defaults files in the templates directory.

After you've done all the above, you can begin to use the custom widget class in PhAB. To make PhAB display custom widgets correctly as you use them, follow these additional Windows-specific steps:

1. Download and install the Cygwin development environment from www.cygwin.com. This is an open-source UNIX like system that offers a gcc-based development environment under Windows. We recommend Cygwin version 1.5.5 or later.
2. After installation, start a Cygwin Bash shell to perform the following compile and link steps.
3. Compile your custom widget functions using Cygwin's gcc:

   gcc -c -nostdinc \
   -I /usr/lib/gcc-lib/i686-pc-cygwin/`gcc -dumpversion`/include \
   -I$QNX_HOST/usr/include -I/usr/include \
   -I$QNX_TARGET/usr/include MyWidget.c
     

4. Link your custom widget object files to create a shared library:

   ld -shared -e _dll_entry@12 MyWidget.o \
   -o MyWidget.dll -L$QNX_HOST/usr/lib -lph \
   -lcygwin -lkernel32
     

5. Place your shared object (in this example MyWidget.dll) in a directory specified by the PATH environment variable. Note that LD_LIBRARY_PATH is not recognized by Windows.

The next time you start PhAB after completing these steps, you should be able to see custom widgets displayed correctly as you work with them. If not, consult the PhAB console window for error messages.

Using custom TrueType fonts and PhAB

You can configure PhAB for Windows to use TrueType fonts that you supply, in addition to the standard font set installed with QNX Momentics. To do this:

1. Install the font in Windows using the control panel. See the Windows help for more information on this step.
2. Copy the font's .ttf file to the Photon font repository directory, %QNX_TARGET%\usr\photon\font_repository.
3. Run mkfontdir on the directory to register the new TrueType font in the fontdir file.

   For example: mkfontdir -d %QNX_TARGET%\usr\photon\font_repository

The font is now available when you run PhAB standalone or in the IDE.

Photon Hook DLLs

Photon supports a special method to change the look and feel of widgets at runtime called “Photon hook DLLs”. This method can be used to “skin” an application without recompiling it. For more information about Photon hook DLLs, see the Widget styles section of the Managing Widgets in Application Code chapter.

To make PhAB display widgets correctly on a Windows host as you develop your application, the Photon hook DLL needs to be built under Windows using the following steps:

1. Download and install the Cygwin development environment from www.cygwin.com. This is an open-source UNIX like system that offers a gcc-based development environment under Windows. We recommend Cygwin version 1.5.5 or later.
2. After installation, start a Cygwin Bash shell to perform the following compile and link steps.
3. Compile your Photon hook DLL source code using Cygwin's gcc, for example:

   gcc -c -nostdinc \
    -I /usr/lib/gcc-lib/i686-pc-cygwin/`gcc -dumpversion`/include \
    -I$QNX_HOST/usr/include -I/usr/include \
    -I$QNX_TARGET/usr/include hook.c

4. Link the actual shared library, for example:

   ld -shared -e _dll_entry@12 hook.o -o PtHook.dll \
    -L$QNX_HOST/usr/lib -lph -lcygwin -lkernel32
     

The above steps create a Photon hook DLL called PtHook.dll. To use this DLL, place it in the search path (specified by $PATH) before running PhAB.

Alternatively, you can use a version of the PtMultiHook sample code as the PtHook.dll (see the Widget styles section of the Managing Widgets in Application Code chapter). This DLL can be found at $QNX_HOST/usr/photon/bin/pt_multihook.dll, and should be renamed to PtHook.dll before use. This code looks for the PHOTON_HOOK environment variable, and loads the DLL it points to. If it points to a directory, it loads all the DLLs in the directory. It then executes the PtHook() function in any loaded DLLs.

For example, if your hook DLL is placed in C:\my_photon_hooks\, you can type the following two commands from a Windows command prompt:

set PHOTON_HOOK=c:/my_photon_hooks
appbuilder

Or you can type the following from bash:

export PHOTON_HOOK=c:/my_photon_hooks
appbuilder

To set the environment variable permanently, use the System option on the Windows Control Panel.

Running multiple copies of PhAB

On Windows XP, multiple users might want to run PhAB. In this case, each instance of the PhAB application has to have a unique TCP/IP port for the Photon server and the PhFont server.

The default port numbers are 4871 for Photon and 4870 for PhFont. A Windows XP user who wants to run PhAB in isolation of other users needs to select unique, unused port numbers by setting the environment variables PHOTON and PHFONT. For example, the following two settings could be used:

set PHOTON=tcp:127.0.0.1:4873
set PHFONT=tcp:127.0.0.1:4872

The port numbers are at the end of the strings, and can be set to any unused TCP/IP port.